commit e11159f2a18981810ff6bf05ebc82fbe9add829d Author: Danil Iarosh Date: Tue Sep 22 12:55:47 2026 +0300 feat: initial Exchanger implementation diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md new file mode 100644 index 0000000..df80d6e --- /dev/null +++ b/.agents/AGENTS.md @@ -0,0 +1,124 @@ +# Agent Guidance + +## Обязательный стартовый контекст + +- Перед любыми действиями в проекте полностью прочитать .context/PROJECT_CONTEXT.md. +- Затем первым инструментальным действием восстановить относящийся к задаче контекст через + agentmemory с каноническим project id exchanger, как описано ниже. +- Если .context/PROJECT_CONTEXT.md, память и текущие файлы расходятся, проверить фактическое + состояние проекта, считать его источником истины и синхронизировать контекст после работы. + +## Documentation Language + +- Write all project documentation in Russian by default. +- Apply this rule to guides, READMEs, setup notes, conventions, and other repository documentation unless the user explicitly asks for another language. + +## Git Commit Messages + +- При создании коммитов первая строка сообщения должна быть кратким описанием изменений на английском языке. +- Начиная с третьей строки сообщения коммита следует указывать подробный список изменений на русском языке. + +## Подтверждённая разводка хопперов + +- Актуальная разводка целевой прошивки: сервисная кнопка — `IN8` (active-low), датчик малого остатка первого хоппера — `IN1` (active-low), второго — `IN4` (active-low); физические датчики выдачи первого и второго хопперов — `IN24` и `IN25`. Для программного учёта обычной выдачи и пересчёта использовать подтверждения самой платы, чтобы физические входы не создавали двойной учёт. +- Оба хоппера подтверждены и разрешены. Целевой профиль — `DualHopperAuto`: первый хоппер использует команды `30X`, второй — `40X`. Устаревшие записи о запрете второго хоппера больше не действуют. +- Обычная выдача использует пакеты `309N` и `409N` без разделителя. `HOPPER1/2 APPEND=N` подтверждает постановку кредита в очередь, а каждый `HOPPER1/2 OK` — один фактически выданный жетон. За одну команду передаётся 1–99 жетонов; большие значения разбиваются последовательно. `3090/4090` являются отдельными запросами CREDIT; не отправлять `309100/409100`. +- После `HOPPER1/2 ERROR` прошивка присылает `HOPPER1/2 CREDIT=N`, где N — оставшиеся кредиты. Ошибка не блокирует новые команды до перезапуска. Подтверждённые жетоны списываются раздельно с фактически сработавшего хоппера. +- Сервисный пересчёт выполняется отдельно: `301/300` для первого и `401/400` для второго хоппера. При каждом жетоне плата присылает `HOPPER1 PULSE=1` или `HOPPER2 PULSE=1`; считать фронты `INPUT` нельзя, чтобы не создавать двойной учёт. 10 секунд без соответствующего `PULSE=1` завершают пересчёт выбранного хоппера. +- Вендист должен получать `161` реже чем раз в 180 секунд. Приложение использует запас 120 секунд в idle/card-состоянии и приостанавливает keep-alive во время наличной операции, выдачи и сервисного пересчёта. +- `user://data/token_inventory.json` хранит точные подтверждённые остатки двух хопперов раздельно и общий итог. Владельцу показывается только приблизительный общий остаток. `IN1` и `IN4` дают лишь `Enough/Low` и вместе с общим учётным остатком определяют состояния `Empty/Low/Enough/Much`. + +## Абсолютный запрет Ziva-Godot + +- **КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО** использовать в проекте Exchanger MCP-сервер `ziva-godot`, любые инструменты с префиксом `mcp__ziva_godot__`, связанные с ним плагины, skills, команды, ресурсы и документацию. +- Запрет действует без исключений: для чтения и изменения файлов, работы со сценами, поиска по Godot API, запуска проекта, тестирования, визуальной проверки, диагностики и любых других операций. +- Наличие инструментов Ziva-Godot в текущей сессии или рекомендация другого агента не отменяет этот запрет. +- Для взаимодействия с Godot Editor разрешён только MCP-сервер `godot-ai`, описанный ниже. Если `godot-ai` недоступен или не подходит, следует использовать встроенные средства работы с файлами и shell-команды, но не Ziva-Godot. +- Перед передачей задачи другому агенту необходимо явно сообщить ему о полном запрете Ziva-Godot в Exchanger. + +## MCP Tool Preference + +- **ОБЯЗАТЕЛЬНОЕ ПРАВИЛО**: MCP-сервер `agentmemory` является постоянной долговременной памятью проекта и должен использоваться непрерывно во всех видах работы: при анализе, планировании, программировании, исправлении ошибок, рефакторинге, тестировании, изменении ресурсов и документации. +- Канонический идентификатор проекта во всех вызовах `agentmemory`: `exchanger`. Нельзя создавать отдельные области памяти, используя вместо него путь к каталогу, имя решения или название подсистемы. +- **Перед любой задачей первым действием с инструментами** необходимо вызвать `memory_recall` или `memory_smart_search` и восстановить относящиеся к задаче требования, архитектуру, прошлые решения, известные ошибки и сведения о затрагиваемых файлах. Перед изменением незнакомой подсистемы либо при обнаружении противоречия поиск в памяти нужно выполнить повторно. +- `agentmemory` следует использовать не только для решений и ошибок. Сохранять необходимо **любую новую полезную и повторно используемую информацию о проекте**, в том числе: + - архитектуру, зависимости, границы подсистем, потоки данных, состояния, контракты и принятые решения; + - актуальную структуру каталогов, файлов, сцен, ресурсов и модулей, их назначение, точки входа и связи; + - устройство кодовой базы: ключевые классы, интерфейсы, функции, сигналы, конфигурационные схемы, протоколы, форматы данных, инварианты и тестовую инфраструктуру; + - требования пользователя, ограничения, запреты, договорённости, настройки, внешние интеграции и сведения о соседних проектах; + - содержание и изменения документации, инструкций агентов, дорожной карты, планов реализации и справочных материалов; + - обнаруженные дефекты, причины, способы исправления, опасные места, технический долг и ещё не закрытые вопросы; + - созданные, изменённые, перемещённые и удалённые файлы, затронутые символы и краткое описание фактического изменения; + - команды сборки и тестирования, результаты проверок, особенности среды и подтверждённое состояние реализации. +- Сохранять контекст нужно не только в конце большой задачи, но и после каждого содержательного открытия, архитектурного решения или законченного блока изменений, если эта информация может понадобиться после смены сессии либо другому агенту. Перед финальным ответом пользователю необходимо выполнить итоговый `memory_save`. +- Записи следует делать атомарными и разделять по смыслу и типу (`architecture`, `pattern`, `bug`, `preference`, `fact`). В каждой записи указывать `project: exchanger`, релевантные пути в `files`, понятные `concepts` и подробное описание на русском языке. Для кодовой базы сохранять назначение и поведение файлов и символов, а не бесконтрольно дублировать полный текст исходников. +- Память дополняет, но не заменяет репозиторий. Если данные в `agentmemory` расходятся с текущими файлами, конфигурацией или результатами запуска, источником истины считается проверенное текущее состояние проекта; устаревшую запись необходимо исправить либо сохранить новую запись, явно описывающую расхождение и актуальное состояние. +- Не сохранять в память случайный шум, огромные необработанные логи и секреты, отсутствующие в репозитории или явно не разрешённые пользователем. Любые значимые выводы из таких данных сохранять в кратком структурированном виде. +- Если `agentmemory` временно недоступен, необходимо сообщить об этом в рабочем комментарии, продолжить безопасную локальную работу и повторить сохранение при первой возможности. Недоступность памяти нельзя молча игнорировать. +- Если задача передаётся другому агенту, в поручении требуется обязать его сначала восстановить контекст через `agentmemory`, а по завершении сохранить открытия, изменения, проверки и незакрытые вопросы туда же. +- Для долговременной памяти, восстановления контекста и передачи знаний между агентами разрешён только MCP-сервер `agentmemory`. Не использовать параллельные memory-хранилища других MCP-серверов. +- Для фактической работы с репозиторием, Godot Editor, сборкой и тестами использовать подходящие инструменты; это не заменяет обязательную синхронизацию всех результатов с `agentmemory`. + +## Godot MCP Workflow + +- При работе с Godot-проектом агенту следует использовать MCP-сервер `godot-ai` как основной инструмент взаимодействия с Godot Editor. +- `godot-ai` следует предпочитать для задач, связанных со сценами, узлами (Nodes), скриптами (GDScript), тайлмапами (TileMaps), ресурсами, физикой, ассетами, настройками проекта и редактора, логами/ошибками, тестированием и запуском игры. +- Перед внесением изменений внутри Godot или для анализа проекта следует прочитать актуальную информацию: + - Использовать ресурс `godot://project/info` для получения общей конфигурации из `project.godot`. + - Использовать `scene_get_hierarchy` или ресурс `godot://scene/hierarchy` для получения дерева сцены, анализа структуры узлов, прикреплённых скриптов, групп и дочерних объектов. + - Использовать `editor_state` или ресурс `godot://editor/state` для получения текущего состояния редактора (версия Godot, открытая сцена, состояние готовности). + - Использовать `input_map_manage(op="list")` или ресурс `godot://input_map` для проверки настроенных действий ввода (Input Actions). +- Для редактирования, поиска и работы с кодом/файлами: + - Использовать `script_create` для создания новых скриптов GDScript (.gd). + - Использовать `filesystem_manage(op="write_text")` для создания или перезаписи других текстовых файлов. + - Использовать `script_manage(op="read")` или ресурс `godot://script/{path}` для чтения содержимого GDScript-файлов. + - Использовать `filesystem_manage(op="read_text")` для чтения других текстовых файлов. + - Использовать `script_patch` для точечного внесения изменений в скрипты GDScript. + - Использовать `filesystem_manage(op="search")` для поиска файлов по кодовой базе (по имени, типу ресурса или подстроке пути). + - Использовать `script_manage(op="find_symbols")` для поиска символов (классы, функции, сигналы, переменные) внутри скрипта. +- Для работы со сценами и структурой узлов: + - Открывать нужные сцены через `scene_open`. + - Сохранять изменения сцен через `scene_save`. + - Управлять иерархией узлов с помощью `node_manage` (операции `duplicate`, `move`, `reparent`, `delete`, `rename`, `get_children`, `get_groups`, `add_to_group`, `remove_from_group`). + - Создавать новые узлы с помощью `node_create`. + - Изменять свойства узлов с помощью `node_set_property`, а читать их свойства через `node_get_properties` или ресурс `godot://node/{path}/properties`. + - Использовать `node_find` для поиска узлов по имени, типу или группе. +- Для работы с 2D/3D-ассетами, спрайтами, тайлмапами, ресурсами и анимацией: + - Для создания и управления анимацией использовать `animation_create` и `animation_manage` (операции `create_simple`, `add_property_track`, пресеты `preset_fade`, `preset_slide`, `preset_shake`, `preset_pulse` и др.). + - Для работы с ресурсами (.tres) использовать `resource_manage` (операции `load`, `create`, `assign`, `search`, а также создание текстур градиента/шума, автоподгонка коллайдеров `physics_shape_autofit`). + - Для настройки и работы с тайлами/тайлсетами использовать `tileset_manage` (операции `tileset_get_atlas_tiles` и `tileset_get_atlas_image` для визуального анализа текстуры атласа). + - Для рисования и работы с тайлмапами использовать `tilemap_manage` (операции `tilemap_set_cell`, `tilemap_set_cells_rect` для заполнения прямоугольных областей, `tilemap_get_cells` для получения занятых ячеек, `tilemap_clear` для очистки). +- Для запуска, отладки и тестирования проекта: + - Использовать `test_run` для запуска GDScript-тестов. + - Использовать `project_run` для запуска проекта из редактора (режимы `"main"`, `"current"`, `"custom"`). + - Использовать `project_manage(op="stop")` для остановки запущенной игры. + - Использовать `editor_screenshot` для получения скриншота (источники `"viewport_2d"`, `"viewport"`, `"cinematic"`, `"game"`). + - Регулярно проверять логи и ошибки через `logs_read` (источники `"game"`, `"editor"`, `"plugin"`, `"all"`), очищать логи при необходимости через `editor_manage(op="logs_clear")`. +- Для настроек проекта: + - Применять `project_manage(op="settings_set")` для изменения настроек проекта и `project_manage(op="settings_get")` для чтения настроек. + - Использовать `api_manage(op="get_class")` или ресурс `godot://class/{class_name}` для поиска информации по API Godot во встроенной ClassDB. +- Если `godot-ai` недоступен, выдаёт ошибки или не подходит для конкретной операции, агент может использовать встроенные инструменты редактирования файлов и стандартные shell-команды, учитывая при этом риски отсутствия синхронизации и валидации со стороны редактора Godot. +- Поскольку проект переведен на C# (.NET), все новые и модифицированные скрипты по возможности должны быть написаны на C# (файлы `.cs`), а не на GDScript. При этом необходимо сохранять совместимость с существующими внешними GDScript-компонентами (например, экспортировать нужные поля/свойства с атрибутом `[Export]` в C# для доступа из динамического GDScript). + +## Git Console Output and Chat formatting + +- Никогда не выводите сырой вывод консоли или логов терминала (особенно логи Git) в чат с пользователем. +- При выполнении фоновых или синхронных Git-команд перенаправляйте вывод потоков вывода и ошибок в пустоту (заглушайте вывод), чтобы избежать захламления чата системными логами и дублирования строк: + - В PowerShell используйте перенаправление в пустоту: `*>$null` + - В CMD используйте перенаправление в пустоту: `>nul 2>&1` +- Описывайте результаты работы Git понятным человеческим языком на русском языке, перечисляя только суть изменений и конечные статусы, без копирования отчетов терминала. + +## Atomic Project Structure + +- Все элементы игры (например, игрок, главное меню, враги, интерфейс и т.д.) должны располагаться атомарно в соответствующих по названию папках. +- Каждая такая папка (например, `src/entities/Player/`, `src/scenes/MainMenu/`, `src/entities/enemies/Bat/`) должна содержать в себе все связанные файлы: сцену (.tscn), скрипт (.cs) и любые специфичные для этого элемента текстуры, звуки или локальные ресурсы. + +## Обязательная документация binding-контракта + +- При любом добавлении, удалении, переименовании или изменении binding ID, пути, типа, fallback, + структуры binding-каталога либо правил разрешения биндингов необходимо в рамках той же задачи + обновить файл + `E:\Danil\Projects\Godot\ExchangerThemeDlcBuilder\docs\BINDING_CONTRACT.md`. +- Изменение биндингов нельзя считать завершённым, пока `BINDING_CONTRACT.md` не приведён в + соответствие фактическому контракту и не проверена его согласованность с + `contracts/screen_bindings.v2.json` и host-контрактом Exchanger. diff --git a/.context/PROJECT_CONTEXT.md b/.context/PROJECT_CONTEXT.md new file mode 100644 index 0000000..2362dff --- /dev/null +++ b/.context/PROJECT_CONTEXT.md @@ -0,0 +1,1163 @@ +# Контекст проекта Exchanger + +> Актуализировано: 2026-09-09. +> +> Обязательная стартовая точка для нового чата или агента. Файл не заменяет исходный +> код, .agents/AGENTS.md, README.md, ROADMAP.md и профильные документы. При расхождении +> источником истины является проверенное текущее состояние файлов и фактический +> результат сборки/запуска, затем последние явные решения владельца. + +## 1. Как начинать любую работу + +1. Полностью прочитать .agents/AGENTS.md и этот файл. +2. Прочитать относящийся к задаче раздел ROADMAP.md и профильный документ из docs/. +3. Первым инструментальным действием вызвать agentmemory: + - канонический project id: exchanger; + - использовать memory_recall или memory_smart_search; + - восстановить требования, прошлые решения, ошибки и историю затрагиваемых файлов. +4. Проверить текущие файлы, процессы и внешнее состояние. Память описывает последний + известный снимок, но не гарантирует, что процесс или COM-порт всё ещё в том же состоянии. +5. Перед изменением незнакомой подсистемы повторно запросить agentmemory. +6. После содержательного открытия и перед финальным ответом сохранить результат в + agentmemory атомарными записями с project: exchanger. +7. После правок выполнить релевантную C#-сборку, тесты и проверить логи Godot. + +## 2. Абсолютные правила и запреты + +- Никогда не использовать Ziva-Godot. Запрещены сервер, инструменты, плагины, + навыки, ресурсы, документация и вызовы с префиксом mcp__ziva_godot__. +- Для Godot Editor разрешён и предпочтителен только godot-ai. Если он недоступен, + использовать файлы и официальный Godot CLI. +- Перед godot-ai проверить список сессий: редактор соседнего Theme Builder часто + открыт, его нельзя по ошибке менять вместо Exchanger. +- Не отправлять команды в COM-порт, не запускать hardware-тесты, оплату, моторы или + выдачу без явного разрешения пользователя в текущей задаче. +- Не повторять команду выдачи при неизвестном результате: это может повторно выдать жетоны. +- Не завершать Godot Editor принудительно без разрешения: возможны несохранённые изменения. +- Не удалять и не перезаписывать пользовательские изменения. Рабочее дерево может быть + грязным; сейчас большая часть файлов может отображаться как untracked. +- Документация проекта по умолчанию пишется на русском языке. +- Runtime-код писать на C#/.NET, если нет веской причины для GDScript. +- Фон статический. Не возвращать шейдерный, particle- или video-фон. Анимация фона — + только отдельные спрайты и AnimationPlayer. +- Технические параметры не должны появляться в настройках владельца. +- В UI использовать «промо» и «промо-ролик», не «реклама». +- Пользовательские тексты должны быть короткими, естественными и понятными. + +## 3. Назначение продукта + +Exchanger — полноэкранное киоск-приложение вендингового автомата для продажи и выдачи +жетонов. Основной интерфейс предназначен покупателю; защищённые настройки — владельцу; +монтажная конфигурация хранится только во внешнем TOML без визуального редактора. + +Основные функции: + +- наличная оплата через монетник и купюроприёмник; +- безналичная оплата через контроллер терминала; +- расчёт жетонов по цене и бонусным правилам; +- выдача из двух хопперов с подтверждением каждого жетона платой; +- бинарные датчики уровня «мало/достаточно»; +- точный программный учёт остатка отдельно по двум хопперам; +- защищённый сервисный вход, настройки владельца и сервисный учёт; +- внешняя DLC-тема с полными визуальными сценами; +- Windows kiosk, журналы, восстановление и watchdog. + +Целевой интерфейс — портретный 9:16, viewport 720×1280, stretch canvas_items/expand. +Основной визуальный язык — пиксельный космос: тёмно-синий статический фон, салатовые +акценты, белые панели, НЛО и зелёный маскот. + +## 4. Технологии и среда + +- Godot 4.7.1 Mono, Mobile renderer (Vulkan). Compatibility нельзя включать: подключённый + `addons/native_video` для MP4/MOV/M4V требует RenderingDevice. +- C# / .NET 8 для Windows и Linux; Android-конфигурация предусматривает .NET 9. +- Godot.NET.Sdk/4.7.1. +- NuGet: System.IO.Ports 8.0.0 и Tomlyn 2.10.1. +- NUnit 4 в tests/Exchanger.Tests. +- Физическая приёмка в tests/Exchanger.HardwareTests. +- Главная сцена: src/scenes/App/App.tscn. +- Имя приложения: Exchanger; русское имя: «Размен жетонов»; версия 0.6.0. + +Официальный Godot CLI на текущем ПК: + + D:\Applications\Godot\Godot_v4.7.1-stable_mono_win64\ + Godot_v4.7.1-stable_mono_win64_console.exe + +Путь машинно-зависимый. + +## 5. Структура репозитория + + .agents/ инструкции агентов + .context/ переносимый контекст + config/ встроенные JSON/TOML defaults + docs/ + architecture/ архитектурные решения + hardware/ протокол и приёмка платы + operations/ export, kiosk, настройки, QA, soak + src/ + core/ + Audio/ громкость + Configuration/ AppSettings, миграции, SettingsService + Inventory/ точный учёт жетонов + Logging/ безопасные журналы + Navigation/ ScreenManager + Session/ SessionController и state machine + TechnicalConfiguration/ TOML монтажника + ThemeManager/ DLC и binding-контракт + hardware/ + Abstractions/ аппаратные интерфейсы + MockHardware/ wire-симулятор + MockMachine/ mock бизнес-границы + PeripheryController/ auth, протокол, команды, состояния + SerialPortHardware/ desktop serial для Windows/Linux + UsbSerialHardware/ заготовка Android + scenes/ атомарные экраны + ui/ общие UI-компоненты + tests/ + Exchanger.Tests/ unit/integration/smoke + Exchanger.HardwareTests/ тесты реальной платы + runtime/ Godot runtime smoke + tools/ export, soak, kiosk/watchdog + README.md + ROADMAP.md + project.godot + export_presets.cfg + +Каталог references/ содержит локальные референсы и документацию производителя, +исключён из Git и production export. Не удалять и не считать production-ассетами. + +## 6. Архитектура приложения + + UI и сцены темы + ↓ типизированные действия + SessionController / SessionFlow + ↓ + PeripheryMachineController + ↓ + IHardwarePort + ↙ ↘ + MockHardware SerialPortHardware + +Инварианты: + +- UI не знает о SerialPort, worker-потоке и строках wire-протокола. +- SessionController — единственный владелец текущей пользовательской операции. +- ScreenManager только переключает экраны и process mode; бизнес-логики в нём нет. +- App — композиционный корень конфигурации, темы, экранов, сессии и hardware. +- ThemeManager и ScreenManager — Autoload. +- Фоновый COM-worker не вызывает Godot API. Кадры передаются в главный поток очередью, + которую App._Process доставляет через ProcessPendingEvents(). +- Completed возможен только после подтверждённой фактической выдачи. +- Потеря связи сбрасывает платёжные состояния. Оплата и выдача автоматически не повторяются. + +Основные экраны: + +- HomeScreen; +- CashPaymentScreen; +- CardAmountScreen; +- CardCustomAmountScreen; +- CardTerminalScreen; +- SuccessScreen; +- ErrorScreen; +- ServiceAccessScreen; +- SettingsScreen. + +Состояния: + + Home + ├─ CashAccepting → Dispensing → Completed → Home + └─ CardAmountSelection + └─ CardCustomAmount (опционально) + → CardTerminalWait → Dispensing → Completed → Home + + Любое активное состояние + → PaymentDeclined / Error / Cancelled + → Home + +На `CardTerminalWait` верхняя кнопка «Назад» и действие `kiosk_back` сначала отменяют +активный безналичный запрос через hardware-границу и возвращают в `CardAmountSelection` +в рамках той же локальной операции. Красная кнопка «ОТМЕНА» завершает сессию и возвращает Home. + +## 7. Темы и binding-контракт + +### 7.1. Граница ответственности + +В приложении одна встроенная fallback-тема. Разработка тем полностью вынесена в: + + E:\Danil\Projects\Godot\ExchangerThemeDlcBuilder + +Все изменения Theme Builder по требованию владельца выполнять через подагента. В поручении +обязательно передать запрет Ziva-Godot и требование использовать agentmemory. + +Host-приложение: + +- загружает готовый PCK; +- инстанцирует сцены темы без изменения геометрии и оформления; +- ищет узлы по metadata exchanger_binding_id; +- подключает бизнес-логику, динамические данные и события; +- не переоформляет присутствующие узлы self-contained сцен; +- при отсутствии обязательного биндинга использует канонический `FallbackPath`: принимает + совместимый узел старой сцены либо переносит готовый узел встроенной темы-заглушки. + +Точечная подстановка fallback является единственным разрешённым исключением и нужна для обратной +совместимости уже выпущенных тем. Она не даёт host права визуально переделывать существующие +элементы внешней темы. Общий контракт меняется только при новой бизнес-функции. + +9 сентября 2026 года исправлен регресс: `settings.scroll.content.animated_banner_texts_panel` +был добавлен в PCK, но отсутствовал в `ThemeSceneContract.RuntimeBindings`; загрузчик считал +metadata «неожиданным биндингом» и отклонял весь PCK. ID объявлен как `Control` с canonical +fallback-path, после чего headless runtime подтвердил активацию `space-pixel`. + +### 7.2. Текущий контракт + +- Manifest v2 требует девять полных сцен. +- Immutable JSON-каталог содержит 481 обязательный binding id. Для новой темы Builder отдельно + требует ещё 24 supplemental runtime-binding. Ещё четыре ID для текстов баннеров, выбора + промо-изображения и переключателя питомца optional и подставляются fallback-слоем для + выпущенной темы; полностью обновлённая тема содержит 509 + element-binding. Metadata корней, питомца и его навигации считаются + отдельно. +- Последний известный SHA-256 каталога: + DDDC89118BEEA78A820561464001656136ED42AC1AD5710FB109D25ADAF44143. +- Production-сцены и вложенные компоненты доверенной темы могут содержать GDScript и стандартные + runtime-узлы Godot. Host не применяет прежний decoration budget, лимиты узлов, кадров, FPS, + скорости анимации или размера PCK; граница безопасности обеспечивается namespace/manifest, + типами биндингов и запретом подмены ресурсов приложения. +- Проверяются root-имена, пути, типы, дубли и неизвестные bindings. Пропущенные обязательные + bindings разрешаются через встроенный fallback по закреплённым путям. +- Supplemental runtime-контракт Settings включает корневой `settings.footer`, кнопку + `settings.footer.save_and_exit_button` и нижний + `settings.scroll.content.footer_clearance`; JSON-каталог остаётся на 481 binding. +- Для отключаемого учёта добавлены supplemental runtime-binding-и Settings: + `settings.scroll.content.service_inventory_panel.margin.content.inventory_enabled` (`CheckButton`) + и `settings.scroll.content.service_inventory_panel.margin.content.description` (`Label`). + Независимый лимит покупки использует supplemental `settings.scroll.content.service_inventory_panel.margin.content.purchase_limit_enabled` + (`CheckButton`). Старые + PCK получают metadata по каноническому пути либо готовый встроенный fallback; JSON-каталог, + количество 481 и закреплённый SHA-256 не меняются. +- CardAmount сохраняет обязательный `card_amount.content.reward_panel.content.value` для базовых + жетонов и получает отдельный supplemental Label + `card_amount.content.reward_panel.content.bonus` с fallback-путём + `SafeMargin/Content/RewardPanel/Content/Bonus`. Бонус не объединяется с базовым количеством: + все карточные и наличный экраны используют `+ N ЖЕТОНОВ\nВ ПОДАРОК` либо `БЕЗ БОНУСА`. +- Семь supplemental runtime-binding-ов `*.content.*.home_navigation_button` добавляют готовую + кнопку с иконкой дома на CashPayment, CardAmount, CardCustomAmount, CardTerminal, Success, + Error и ServiceAccess. Её основа — theme-вариант `KeypadButton`, который в `space-pixel` + использует готовый `assets/ui/button_square.png`; на четырёх экранах с BackButton она стоит рядом с ним, на остальных + трёх занимает верхнее левое навигационное место. Host только подключает безопасный переход: + незавершённая оплата отменяется, а при Dispensing кнопка Success отключена до физического + завершения выдачи. Старые PCK получают побиндинговый встроенный fallback. +- Пакет монтируется в res://exchanger_theme_dlc/. +- Замена DLC требует полного перезапуска. + +Для немедленного управления видимостью Home поверх закреплённого JSON-каталога добавлены +runtime-binding-и `home.scroll.content.advertisement_panel` и +`home.decoration.right_character`. Первый обязателен и указывает на весь готовый промо-блок; +второй необязателен, поскольку не каждая тема содержит отдельного персонажа справа. Settings +предоставляет готовую theme-owned панель `settings.scroll.content.menu_visibility_panel` и три +`CheckButton` для показа остатка, правого персонажа и промо. Host только меняет `Visible`, не +создаёт и не перестраивает визуальные элементы темы. + +Обратная совместимость является побиндинговой. Если metadata обязательного ID отсутствует, но +старая тема сохранила узел на каноническом `FallbackPath`, runtime подключает этот узел без +изменения его внешнего вида. Если отсутствует и узел, соответствующий элемент переносится из +встроенной сцены и сохраняет встроенный `Theme`. Вложенный отсутствующий блок переносится один раз +на уровне верхнего отсутствующего родителя. При невозможности безопасной точечной композиции +только этот экран остаётся полностью встроенным; остальные экраны DLC продолжают использоваться. +Неизвестные ID, дубли, неверные типы, неверные root/metadata и повреждённый контракт по-прежнему +отклоняются. JSON-каталог остаётся закреплённым: 481 binding, прежний SHA-256. +Headless runtime-smoke на mock загрузил без пересборки ранее установленный `space-pixel.pck` +SHA-256 `5756191317B0318F1833657573B75A5240E96E3B4B063A7E6012C7165B9A2B7D`: совместимость +восстановлена для одного Home-binding и четырёх Settings-binding. Актуальный полный PCK отдельно +загрузился без единой подстановки. В обоих запусках COM/UART не использовался. + +Текущая тема: + +- id: space-pixel; +- имя: «Космическая pixel-тема»; +- путь: user://theme_dlc/active_theme.pck; +- Windows: %APPDATA%\Godot\app_userdata\Exchanger\theme_dlc\active_theme.pck. + +Интерактивный питомец является необязательным theme-owned компонентом. Manifest публикует его +через нейтральное поле `InteractivePetScene`; рекомендуемый путь текущей темы — +`res://exchanger_theme_dlc/components/interactive_pet.tscn`. Exchanger валидирует путь и загружает +`PackedScene` в runtime-описание темы, но не перестраивает ради питомца готовые сцены темы. +Расположение PNG и названия каталогов принадлежат конкретной теме и не являются частью контракта. +Имена и число анимаций полностью принадлежат теме. Если она реализует +`get_pet_action_animation(action_name)`, host получает через него соответствие нейтральных действий +(`idle`, `interact`, `celebrate`, `walk_left`, `walk_right`, `climb_start`, `climb_up`, +`climb_down`, `climb_finish`, `drag`, `drop`, `landing`) фактическим именам своих клипов; +отсутствующее соответствие безопасно откатывается к `idle`. Builder viewer и verifier проверяют +этот optional pet API и активный manifest, без фиксированной сцены `space-pixel`. +Текущая реализация `space-pixel` публикует 22 анимации и 414 кадров. В частности, её +theme-owned имя правого стартового клипа — `walking_start_right`; приложение не нормализует +имена или папки текстур темы. +Поведение выполняет app-owned `InteractivePetHost` в отдельном CanvasLayer поверх всех экранов, +кроме Settings. Каждая non-settings сцена темы через собственные невидимые metadata-маркеры +версии 1 объявляет границы, поверхности с точками посадки и двунаправленные рёбра подъёма; host +не угадывает геометрию по именам `Control` и не меняет визуальную сцену. При смене экрана host +сохраняет старую экранную позицию питомца, переключает граф и проигрывает падение до default-floor +новой сцены, после чего питомец автономно ходит, поднимается/спускается у заявленных краёв и сидит +на её кнопках и окнах. В Settings питомец скрыт без сброса сохранённой позиции. Он также +перетаскивается первым пальцем или зажатой ЛКМ и после отпускания падает на ближайшую нижнюю +поверхность. Анимация `hanging` действует только во время удержания, `falling` — во время +падения. При подъёме/спуске host не использует hanging-анимацию, зарезервированную для удержания. +Обычная ходьба, подъём и спуск запрашиваются как нейтральные действия и переводятся темой через +её mapping; отсутствие необязательного действия безопасно приводит к idle-fallback. +Во время каждого ненулевого подъёма или спуска host выбирает случайную точку в пределах 20–80% +ребра, останавливает anchor и выполняет полный порядок `climbing_action_start → climbing_action → +climbing_action_stop`; средний looping-клип проигрывается один цикл. После stop возобновляется +исходная `climb_up` либо `climb_down` и продолжается тот же маршрут. Возможность считается +all-or-nothing: если тема не предоставляет хотя бы одно из трёх действий, подъём остаётся +непрерывным без частичной последовательности. +Debug/Release NUnit прошли по 529/529. Полный `InteractivePetBehaviorSmoke` с явным актуальным +`space-pixel.pck` и mock-оборудованием подтвердил точный порядок трёх клипов, неподвижный anchor +во время sequence и продолжение исходного маршрута после stop. Заодно устранено противоречие +reduced-effects: после landing он больше не запускает случайный автономный подъём. +Reduced-effects отключает только автономное блуждание. + +Обычное падение теперь завершает полную цепочку `falling → landing → idle`: после контакта +с объявленной поверхностью `InteractivePetHost` входит в отдельное состояние `Landing`, запускает +семантический `landing` и ожидает сигнал темы `pet_animation_completed`; расчёт длительности по +frame count/FPS остаётся только защитным таймаутом. Лишь после фактического завершения клипа host +с равной вероятностью запускает `sit`, подъём к достижимой верхней поверхности либо `idle`; если +верхнего маршрута нет, подъём безопасно заменяется idle. Даже если при смене сцены anchor уже совпал с новой поверхностью, host не +пропускает состояние `Landing`. Для старой темы без `landing` host выдерживает безопасную фазу +`Landing` в 0,5 секунды и пишет предупреждение вместо немедленной посадки. +Празднование, запрошенное во время падения или приземления, остаётся в очереди до окончания +`landing`, после чего начинаются четыре цикла `dancing`. Theme-owned composite action по-прежнему +сам владеет своей внутренней последовательностью и не получает второй host-side `landing`. + +После завершения обычной ходьбы host выбирает действие простоя: в 35% случаев запускает +зацикленный `idle` на 3–5 секунд, в 65% — `sitting` на 1,5–3,5 секунды. Старая тема без +`sitting` безопасно получает `idle`. Падение сохраняет отдельную цепочку +`falling → landing → idle`. + +Для сложных theme-specific последовательностей поддерживается необязательный all-or-nothing +composite API: `has/start/cancel` и сигналы `started/finished`. Exchanger выдаёт каждому запуску +ограниченный `InteractivePetActionRuntime` для viewport, anchor, самой высокой доступной опоры, +политик навигации/контактов/границ/ввода, перемещения и финальной посадки. Runtime инвалидируется +при смене экрана/темы, drag и конфликтующем действии. Старые темы без полного API используют +одиночные анимации с каноническими именами. Текущий `space-pixel` реализует `interact` как условный поворот, +`come_closer` с масштабом VisualRoot до ×2, повторы `action`, вычисляемое падение через низ/верх, +`landing` на самой высокой опоре и возврат в `idle`; reduced-effects пропускает приближение/wrap. + +Поверхность питомца может объявить metadata +`exchanger_pet_surface_visibility_binding_id`. При каждом входе на экран host повторно читает +граф и исключает поверхность вместе с её рёбрами, если связанный готовый `CanvasItem` скрыт. +На Home это не позволяет питомцу сидеть в воздухе на отключённых остатке или промо-блоке. + +При переходе клиентской сессии в `SessionState.Dispensing`, непосредственно перед отправкой +команды выдачи контроллеру, App запрашивает у питомца четыре последовательных цикла `dancing`. +Если питомец ещё падает после открытия Success, праздник ставится в очередь +до посадки. Длительность полного цикла вычисляется из frame count/FPS темы; каждый цикл явно +перезапускается, после четвёртого питомец возвращается к `Sitting`. `space-pixel` публикует +одноимённый `dancing`; для старых тем без этой анимации host использует `action`. + +Для `space-pixel` единая точка контакта питомца с поверхностью задаётся theme-owned смещением +`GROUND_OFFSET = (64, 96)`, а актуальный scale `0.845` ровно на 30% больше исходного `0.65`. +Сниженная высота теперь относится только к `sitting`: дочерний визуал имеет поправку `(0,0)`. +Все остальные анимации получают локальную theme-owned поправку `(0,-24)`, то есть поднимаются на +`20.28` экранного пикселя при текущем масштабе и возвращаются на прежнюю высоту. Host по-прежнему +масштабирует визуал, область захвата и ground offset общей формулой; root, navigation, hit box и +контактная точка при смене состояния не меняются. + +Актуальный Builder `space-pixel.pck` с 22 анимациями/414 кадрами, прямыми каноническими именами, +вероятностным простоем после ходьбы, composite `interact`, +увеличенным питомцем, state-specific высотой, упрощённым разделом «Общие», отдельным +переключателем ограничения покупки и унифицированной панелью `К ВЫДАЧЕ`, а также семью +дополнительными кнопками «Главная», системным выбором промо-медиа и переключателем питомца, +имеет размер 1697904 байт и SHA-256 +`3EF7A198D84C1AF009ED7727DD8C00DCCC033ACA292CC8FFE61DB5E5813989E4`. +Пользовательский `active_theme.pck` установлен из этой сборки; пакет будет подхвачен после +полного перезапуска Exchanger. В восьми non-settings сценах объявлены 54 поверхности и 49 +двунаправленных переходов; Settings намеренно не содержит +графа. Host runtime-smoke с установленной PCK и mock-оборудованием подтвердил загрузку, +touch/LMB drag, посадку, подъём на Home/CashPayment, выбор индивидуального графа каждой сцены, +сохранение исходной координаты и `falling`-падение на пол новой сцены, а также скрытие в Settings. +Тот же smoke зафиксировал ровно четыре запуска `dancing` после падения на Success и возврат в +`Sitting` после четвёртого цикла. +Новая сборка прошла Builder validator/preview-smoke, PCK verifier и production-loader Exchanger +с явным путём на mock-оборудовании. Полный `InteractivePetBehaviorSmoke` подтвердил composite +последовательность, scale ×2, вертикальный wrap и возврат управления host. Для использования +новых ресурсов во внешней теме следует установить новый PCK и полностью перезапустить Exchanger, +поскольку пакет монтируется только при старте процесса. + +Несовместимый PCK должен быть отклонён до запуска экранов с безопасным fallback. +Спецификация: docs/THEME_DLC.md. + +## 8. Конфигурация и пользовательские данные + +На Windows user://: + + %APPDATA%\Godot\app_userdata\Exchanger\ + +Custom user directory не задан. + +Основные файлы: + + config/appsettings.json настройки владельца + config/appsettings.json.bak резервная копия + config/technical_settings.toml монтажная конфигурация + config/.embedded/* defaults, извлечённые из PCK + data/token_inventory.json остатки двух хопперов + logs/godot.log журнал движка + logs/exchanger.log журнал приложения + logs/operations.jsonl журнал операций + logs/settings-audit.jsonl аудит изменений + theme_dlc/active_theme.pck внешняя тема + +res://config/default_settings.json и res://config/technical_settings.toml находятся +внутри PCK. В one-EXE это не обычные файлы. AppSettingsLoader читает их через +Godot.FileAccess, материализует в user://config/.embedded/, затем передаёт System.IO. + +`technical_settings.toml` версии 1 поддерживает optional авторитетный раздел `[theme]` с полями +`enabled`, `directory` и `file_name`. Путь собирается как `/.pck`; имя +задаётся без расширения, каталог — через `user://` либо абсолютным путём текущей ОС. Старые TOML +без раздела остаются совместимыми и не переопределяют `appsettings.json`. Аргументы `--theme-dlc` +и `--no-theme-dlc` применяются последними. Репозиторный профиль выбирает +`user://theme_dlc/active_theme.pck`. +Windows-пути с обратными слешами поддерживаются через literal TOML-строку, например +`directory = 'D:\Exchanger\themes'`; также допустимы прямые или экранированные двойные слеши. + +Авторитетный интервал повторного подключения платы находится в +`[controller].reconnect_interval_seconds`; штатное значение шаблона и текущей локальной установки — +30 секунд. Первое подключение выполняется сразу. Если платы нет, каждая следующая попытка получает +новый 30-секундный дедлайн; если работавший транспорт отключился, полный интервал отсчитывается от +фактического falling edge `IsConnected`. Reconnect повторяет только открытие порта и авторизацию, +но никогда не повторяет оплату или выдачу. + +После добавления выбора темы через технический TOML и проверки Windows-путей прошли `426/426` Release unit-тестов. +Headless startup на Godot 4.7.1 с `--mock-hardware=true` загрузил установленную `space-pixel`, +активировал питомца и завершился без ошибок theme/config/runtime. + +Имя последовательного порта валидируется по фактической ОС процесса. При `use_mock = false` +Windows принимает только `COM1`…`COM256`, Linux — `/dev/ttyUSB*`, `/dev/ttyACM*` и +`/dev/serial/by-id/*`; прочие пути отклоняются до открытия транспорта. При `use_mock = true` +поле `port` не используется и не проверяется, поэтому общий безопасный шаблон с `COM3` пригоден +для Linux mock-запуска. Отсутствие `/dev/serial/by-id/` допустимо: для Silicon Labs CP210x можно +использовать фактический `/dev/ttyUSB0`; `/dev/usb/` не является UART-узлом. + +В export_presets.cfg обязательно: + + include_filter="config/*.toml" + +Без этого Godot не включает TOML в PCK и startup ломается. + +Настройки владельца автосохраняются с debounce. Дополнительно в отдельном фиксированном футере, +не входящем в `ScrollContainer`, есть кнопка «Сохранить и выйти»: она немедленно завершает +ожидающее сохранение и возвращает Home только при корректных данных и отсутствии незавершённой +сервисной операции. Пока открыта любая встроенная экранная клавиатура, кнопка отключена, а её +обработчик дополнительно отклоняет программный вызов выхода. На это время кнопка и панель футера +получают `MouseFilter.Ignore`, поэтому геометрия футера не перехватывает нижний ряд клавиатуры; +после закрытия восстанавливаются исходные фильтры ввода. Повторная сервисная кнопка выполняет тот +же безопасный выход даже при открытой экранной клавиатуре: аппаратное событие идёт напрямую через +`OnPhysicalServiceRequested()` и `TryFinishEditing()`, закрывает клавиатуру, завершает сохранение и +возвращает Home. Ограничение `OnSaveAndExitPressed()` относится только к экранной кнопке. PIN задаётся +в приложении при первом включении PIN-защиты, а не в окружении Windows. + +Текущая схема `AppSettings` имеет версию 25. `AnimatedBannerTexts` содержит четыре независимые +настройки подписей нижних анимированных плашек с НЛО: наличные, выбор суммы картой, ручной ввод +суммы и шаблон таймера терминала (`{seconds}` заменяется текущим значением). Тексты доступны в +разделе «Общие» и не меняют верхнюю реплику персонажа. Раздел `MenuVisibility` содержит положительные +флаги `ShowStockStatus`, `ShowCustomText`, `ShowPromotionBlock` и `ShowInteractivePet`; все четыре +по умолчанию `true`. +Для обратной совместимости `ShowCustomText` сохраняется в JSON под прежним именем +`ShowRightCharacter`; он одновременно управляет пользовательской речевой плашкой и theme-owned +персонажем справа. `ShowInteractivePet` не меняет сцену темы: host только скрывает или вновь +включает готового theme-owned питомца; при включении он начинает с падения на пол текущего экрана. +Поэтому миграция старого файла не скрывает элементы неожиданно. Изменения относятся к разделу +«Сервис», автосохраняются и применяются к уже созданному Home без перезапуска приложения. +Раздел `TokenInventory` содержит включённые по умолчанию `Enabled` и `PurchaseLimitEnabled`. +Первый управляет ведением остатка, сервисными действиями и числовой индикацией; второй независимо +включает запрет покупки сверх остатка без изменения бинарных датчиков. + +Владелец видит: + +- общую громкость, mute и громкость промо; +- цену жетона и бонусные правила; +- карточные суммы и ручной ввод; +- включение наличной/безналичной оплаты; +- отдельные таймауты оплаты наличными и безналичными средствами; +- тексты нижних анимированных баннеров с НЛО, включая шаблон таймера `{seconds}`; +- свой текст для речевого bubble и телефон поддержки; название автомата сохраняется в конфигурации, + но больше не редактируется через UI владельца; +- промо: картинка выбирается кнопкой через системный файловый диалог (PNG/JPG/JPEG/WEBP), а каждый + ролик добавляется через такой же диалог (OGV/MP4/MOV/M4V); ручной путь остаётся доступен для совместимости; +- в разделе «Сервис» — независимое скрытие остатка жетонов, theme-owned персонажа справа, + целого промо-блока на Home и интерактивного питомца; +- сервисный учёт полного точного остатка и его полное отключение. + +Не показывать владельцу DLC-пути, COM, baud rate, AES, FPS, window/debug/mock, +сырые логи и протокольные предупреждения. + +## 9. Текущая техническая конфигурация + +Репозиторный TOML намеренно безопасный: use_mock = true. + +На текущем компьютере машинный файл переключён на реальный контроллер: + + %APPDATA%\Godot\app_userdata\Exchanger\config\technical_settings.toml + use_mock = false + port = "COM3" + baud_rate = 115200 + +Резервная копия: + + technical_settings.toml.before_real_controller + +Оба хоппера включены; профиль DualHopperAuto. + +На целевом Debian пользователь подтвердил обнаружение USB-UART ядром: Silicon Labs CP2102, +VID:PID `10c4:ea60`, серийный номер `0001`; драйвер `cp210x` подключил устройство как +`/dev/ttyUSB0`. Это подтверждает наличие драйвера и device node, но ещё не подтверждает права +пользователя, запуск Linux ELF, авторизацию платы или обмен протоколом из Exchanger. + +Это не является разрешением запускать плату. Перед аппаратной работой проверить, +не занят ли COM3 процессом Exchanger или конфигуратором, и получить разрешение. + +## 10. Контроллер 2.3.5 + +### 10.1. Транспорт + +- USB-COM/UART, 115200, 8N1, parity None, flow control None. +- ASCII-кадры заканчиваются CR, LF или CRLF. +- Исходящие команды заканчиваются CRLF. +- Frame timeout 100 мс, max frame 1024 байта. + +### 10.2. Авторизация + +Порядок, синхронизированный с актуальным plate_config_app: + + open + → RTS reset + → "periphery controller ver_" + → пауза 2000 мс + → 07 + → CHAL + → 08 + → RAES + → AUTH_PC_OK/AUTH_CNT_OK + → точный READY! + +- Challenge: 16 байт / 32 uppercase HEX. +- AES-256 ECB, PaddingMode.None, без IV. +- В коде хранится обфусцированное представление ключа; восстановление XOR 0x37. +- Эффективный ключ не выводить в логи, чат или документацию. +- Только точный READY! разрешает рабочие команды. +- Таймауты: banner 20 с; CHAL/RAES обычно по 2 с; READY 5 с. + +Код: ControllerAuthentication.cs и PeripheryControllerSecurity.cs. + +### 10.3. Платёжные команды + +| Действие | Wire | +| --- | --- | +| Начать наличную сессию | 162, затем 141, 151 | +| Остановить наличную сессию | 142, 152 | +| Монеты | MONEY:COINS:<сумма> → ASK:COINS:<сумма> | +| Купюры | MONEY:BILL:<сумма> → ASK:BILL:<сумма> | +| Подтвердить карточную сумму | 142, 152, 161, 163<сумма> | +| Карточный результат | MONEY:CASHLESS:<сумма> → ASK:CASHLESS:<сумма> → 162 | +| Отменить безналичную | 162 | +| Keep-alive Вендиста | 161 каждые 120 с в idle/card, всегда реже 180 с | + +MONEY:CASHLESS должен точно совпасть с 163. Каналы взаимоисключающие: перед наличной +веткой отключается Вендист; перед card-веткой отключаются монетник и купюроприёмник. + +### 10.4. Хопперы и входы + +| Назначение | Вход/канал | Семантика | +| --- | --- | --- | +| Сервисная кнопка | IN8 | active-low | +| Мало жетонов, hopper 1 | IN1 | active-low: сигнал есть → мало | +| Мало жетонов, hopper 2 | IN4 | active-low: сигнал есть → мало | +| Датчик выдачи hopper 1 | IN24 | active-low | +| Датчик выдачи hopper 2 | IN25 | active-low | +| Команды hopper 1 | 30X | первый хоппер | +| Команды hopper 2 | 40X | второй хоппер | + +Если в старой аппаратной документации встречается ??? для второго датчика, это устарело. +Последнее явное решение владельца: hopper 2 = IN25. + +Обычная выдача: + +- 309N — 1–99 жетонов первому хопперу; +- 409N — 1–99 жетонов второму; +- без разделителя; +- APPEND=N подтверждает только очередь; +- каждый HOPPER1/2 OK подтверждает один физический жетон; +- ERROR, затем CREDIT=N сообщает оставшийся кредит; +- больше 99 разбивать на пакеты максимум по 99; следующий пакет отправлять только после всех + соответствующих `HOPPER1/2 OK` предыдущего пакета, а `APPEND=N` не считать завершением; +- 3090/4090 — запрос CREDIT; не отправлять 309100/409100. +- в `DualHopperAuto` всегда сначала использовать точный учётный остаток hopper 1: выдать из него + `min(запрос, остаток hopper 1)`, затем выдать недостающую разницу из hopper 2; +- если суммарного учётного остатка меньше запроса, не отправлять ни одной команды выдачи; +- аппаратная ошибка активного хоппера не запускает автоматический retry/failover: действует + at-most-once-политика и возвращается подтверждённый частичный результат. + +Сервисный пересчёт: + +- hopper 1: 301 старт, 300 остановка; +- hopper 2: 401 старт, 400 остановка; +- считать только HOPPER1/2 PULSE=1; +- 10 секунд без соответствующего PULSE завершают пересчёт; +- INPUT-снимки для подсчёта не использовать, иначе будет двойной учёт. + +Датчики уровня дают только Low/Enough, не точное количество. + +Конфигурация хопперов является общей границей приложения. `DualHopperAuto` включает оба канала, +`Hopper1Auto` — только первый, `Hopper2Auto` — только второй. При одноканальном профиле выдача, +mock, Home, сервисный пересчёт и ручное пополнение используют только включённый хоппер; подпись и +кнопки отключённого скрываются в Settings. Сохранённый остаток отключённого хоппера не стирается, +но не входит в доступный общий остаток до повторного включения. После изменения прошли `431/431` +Release unit-тестов и headless-smoke Godot 4.7.1 с mock-оборудованием и внешней темой `space-pixel`. +Первоначальная реализация ошибочно запрашивала у ThemeView биндинги контейнеров `hopper1/hopper2`, +которых нет в v2-контракте, и из-за этого прерывала `ConfigureScreens` во внешней теме. Исправление +скрывает только уже контрактные Label и Button; сцены темы и контракт не расширялись. Диагностика +по Debian-логу подтвердила обрыв сразу после активации питомца и до подключения аппаратной границы. +После исправления свежая Debug-сборка с тем же `space-pixel.pck` дошла до `Mock-сценарий Exchanger +запущен`, Release-тесты прошли `431/431`. Повторно экспортирован Linux release: +`artifacts/linux/debian13/Exchanger.x86_64`, 155349224 bytes, +SHA-256 `787E366CD56DE2B0D81CF8A99DE6CAA32A5492A0B41BF73653440C17D62EE4C9`. + +После платформенной адаптации последовательного порта 2026-09-03 Linux release экспортирован +повторно: `artifacts/linux/debian13/Exchanger.x86_64`, 155351952 байта, +SHA-256 `7312E79514842EB5EA3193604F71CAAE412654957640032B62D66E202802284C`; +проверены ELF64 и AMD64 (`e_machine = 0x003E`). Экспорт завершился с кодом 0 и включил native +`libSystem.IO.Ports.Native.so`; финальные диагностические сообщения Godot о leaked RID/ObjectDB +относятся к завершению headless export-процесса. Сам ELF на Debian и реальный UART ещё не запускались. + +Для диагностики Debian собран отдельный Debug ELF, не заменяющий release: +`artifacts/linux/debian13/debug/Exchanger.Debug.x86_64`, 155630576 байт, +SHA-256 `A1FB92126D6ED753DF968180075D7409678E5F0A7C454CB6D2B954DC024682B6`. +Это ELF64 AMD64, экспортированный через `--export-debug`; запуск на Debian ещё не выполнялся. + +## 11. Учёт жетонов + +- `AppSettings.TokenInventory.Enabled` и `PurchaseLimitEnabled` включены по умолчанию; версия + конфигурации — 23. +- Точный остаток хранится отдельно по двум хопперам, начальное значение 0. +- Он меняется по подтверждённой выдаче, пересчёту и ручному добавлению. +- Пересчёт заменяет остаток выбранного хоппера подтверждённым количеством. +- Ручное добавление применяется только после подтверждения. +- В Settings владельцу показываются точный общий остаток и отдельные точные остатки hopper 1/2; + заголовки обновляются после пересчёта, ручного добавления и подтверждённой выдачи. +- На Home покупателю показывается приблизительный общий остаток справа от полосы: + <100, шаг 100 до 1000, затем шаг 500. +- Полоса объединяет учёт и датчики в Empty / Low / Enough / Much. +- При включённых учёте и лимите полное количество с бонусом не может превысить сумму остатков только + подключённых хопперов. Card отклоняется до `BeginCardPayment`, cash — до `DispenseTokens`; + экраны готовых/ручных сумм применяют тот же лимит. +- При включённом учёте и выключенном лимите остатки остаются видимыми и списываются, но не + блокируют оплату; доступность Home определяется датчиками. `DualHopperAuto` выдаёт из hopper 1 + до его записанного остатка, затем направляет всю разницу в hopper 2. +- При выключенном учёте точный файл сохраняется, но не ограничивает и не списывает выдачу; + точные значения, пересчёт/добавление и приблизительный Label Home скрываются. Качественный + уровень продолжает определяться бинарными датчиками. +- В `DualHopperAuto` без учёта весь запрос идёт через hopper 1 последовательными пакетами до 99. + Ошибка не вызывает автоматический failover. Перед повторным включением после такой работы нужен + физический пересчёт, поскольку сохранённый остаток намеренно остаётся прежним. +- Свежие `example.pck` и `space-pixel.pck` содержат отдельный theme-owned переключатель лимита, + прошли Builder contract/validator/preview/PCK smoke и визуальную проверку `720×1280`. Host + runtime-smoke с mock-оборудованием завершился с exit code 0 без fallback-подстановок для обоих + пакетов. Артефакты: `example.pck` — 464268 байт, SHA-256 + `AC03334354D285E36A25BFB81D60880F829700F083AF5D728F10AB15C764B63D`; `space-pixel.pck` — + 1436492 байта, SHA-256 `166660916913E4766FC91437155BB8B78A405150B3A599CF401CD78A83DFB727`. + Пользовательский `active_theme.pck` не заменялся. + +Платёжные итоги унифицированы 2026-09-07: CashPayment имеет заголовок `К ВЫДАЧЕ`, а CardAmount и +CardCustomAmount показывают базовые жетоны слева и отдельный бонус справа в том же формате, что +CashPayment. Общий formatter исключает расхождение склонений и переносов. Debug-сборка прошла без +предупреждений, 487/487 NUnit-тестов; встроенная тема, свежие `example.pck` и `space-pixel.pck` +прошли `PaymentRewardFormattingSmoke` с mock-оборудованием. Builder contract/validator/preview/PCK +smoke и визуальная проверка `720×1280` также прошли. Новые пакеты: `example.pck` — 464876 байт, +SHA-256 `02B8505FB7F0EF4F4E9C2905D97E8F8751A1DDE86DDF460AFC958CCE6AF51994`; +`space-pixel.pck` — 1436988 байт, SHA-256 +`4D9AA00FE2096794331B348916D1766B47A45D9EDFEE60BEAB0E424ED4761A67`. Пользовательский +`active_theme.pck` не заменялся. Предыдущий установленный PCK также прошёл compatibility-smoke: +для CardAmount восстановлен один отсутствующий Bonus binding. COM/UART не использовался. + +Нельзя подменять бинарный датчик фиктивным числом. + +## 12. Сервисный режим и ввод + +- IN8 открывает Settings из свободного Home. +- При включённом PIN сначала ServiceAccessScreen. +- Повторный IN8 в Settings завершает автосохранение и возвращает Home. +- Экранная кнопка «Сохранить и выйти» выполняет тот же `TryFinishEditing()`; её футер закреплён + у нижней границы экрана, не прокручивается и исключён из drag-области списка. +- Диалог ручного добавления жетонов автоматически фокусирует поле количества, выделяет текущее + значение и открывает цифровую theme-owned клавиатуру. Поле находится вне основного ScrollContainer, + поэтому клавиатурный контроллер не пытается прокручивать Settings для этого поля. +- Удержание кнопки не должно создавать повторы. +- Settings явно обрабатывает вертикальный drag одним пальцем и зажатой ЛКМ; содержимое следует + за указателем в обе стороны, а deadzone 12 px сохраняет обычные короткие нажатия по контролам. +- Обработчик не запускается поверх сервисного диалога, экранной клавиатуры и штатной полосы + прокрутки. Desktop-мышь дополнительно эмулирует touch; реальный экран может посылать touch напрямую. +- Прежняя ставка только на штатный drag ScrollContainer оказалась недостаточной на физическом + Windows-тачскрине; повторная проверка исправления на автомате остаётся в ROADMAP 4.1. +- Фиксированный футер проверен runtime-smoke во встроенной теме, старом установленном PCK через + побиндинговый fallback и новом полном `space-pixel.pck`; Debug/Release проходят 454/454 теста. +- В legacy-PCK прежний полноэкранный Scroll может проходить под непрозрачным fallback-футером; + добавленный `footer_clearance` позволяет поднять последние поля, а host не меняет геометрию темы. + +Экранная клавиатура: + +- текстовое поле → RU/EN/спецсимволы; +- числовое поле → цифровая клавиатура; +- Shift, язык, символы, очистка, backspace, пробел и курсор; +- справа сверху кнопка скрытия с текстурой стрелки вниз; +- геометрия клавиатуры принадлежит теме, host только привязывает действия. + +«Свой текст» подставляется в speech bubble Home. В разделе «Общие» скрыты legacy-поле +`ApplicationName` и весь `BrandingPreviewPanel`; host принудительно сохраняет эту политику и для +старых внешних тем. Существующее значение `Branding.ApplicationName` не удаляется и продолжает +использоваться Home/footer там, где это предусмотрено темой. Скрытое поле названия не участвует +в блокировке сохранения пользовательской формы. + +Актуальный `Branding.SupportPhone` подставляется во все пользовательские экраны: Home обновляет +свой контрактный `Support`, встроенные экраны — `KioskFooter`, а внешняя DLC-тема — уже готовую +метку `Footer/Support`. Host не добавляет узлы и не меняет компоновку темы; если у стороннего +footer нет этой готовой метки, он остаётся визуально неизменным. + +Встроенная сцена и theme-owned Settings обеих эталонных DLC синхронизированы. Binding-каталог не +менялся и сохраняет 481 запись с SHA-256 +`DDDC89118BEEA78A820561464001656136ED42AC1AD5710FB109D25ADAF44143`, поэтому +`ExchangerThemeDlcBuilder/docs/BINDING_CONTRACT.md` для этой правки не обновлялся. Debug и Release +unit-наборы прошли по 460/460; runtime-smoke прошёл со встроенной темой и с новым +`space-pixel.pck`. Builder contract/validator/preview/PCK smoke и визуальная проверка `720×1280` +прошли для `example` и `space-pixel`. Новые пакеты: `example.pck` — 463324 байта, SHA-256 +`25E90059652EC26BD1779F7D6761F1CD1248A458F8C93F8E242596D3988FDE9F`; `space-pixel.pck` — +1435548 байт, SHA-256 `E5941A4E7437BA996945E85551714F8B6E11F77A64808C68B29A8B88F66629AB`. +Пользовательский `active_theme.pck` автоматически не заменялся. + +## 13. Логи, безопасность и восстановление + +- Не логировать PIN, ключи, платёжные секреты, значения настроек, приватные пути и + сырые payload контроллера. +- В C# Debug-конфигурации `AppLogger.Debug` принудительно включает безопасный уровень `[DEBUG]`; + вызовы помечены `Conditional("DEBUG")` и полностью удаляются компилятором из Release. +- Debug-журнал подробно фиксирует открытие serial-устройства, безопасную классификацию ошибки + доступа/занятости/I/O, reset DTR/RTS, worker и его итоговые счётчики, reconnect, состояния + транспорта и переходы handshake. Содержимое 07/08/CHAL/RAES, AES-данные и сырые кадры скрыты. +- В разделе «Диагностика» Debug-сборки runtime summary дополнительно показывает платформу, + состояние транспорта, этап авторизации, UART и reconnect-интервал. +- OperationJournal фиксирует единственный итог операции. +- Незавершённая операция после перезапуска становится UnknownAfterRestart; ничего не повторять. +- Настройки сохраняются атомарно через temporary + replace и backup. +- Некорректный TOML не применяется частично. +- Структурно неверный DLC отклоняется до инстанцирования рабочих сцен; отсутствие отдельных + обязательных биндингов безопасно компенсируется встроенными элементами. + +## 14. Сборка, тесты и export + +Обычные проверки: + + dotnet build Exchanger.csproj -c Release + dotnet test tests\Exchanger.Tests\Exchanger.Tests.csproj -c Release --no-restore + +Последний подтверждённый результат: 0 ошибок/0 предупреждений; unit-тесты 529/529 в Debug и +Release. Последний полный запуск +hardware-проекта безопасно пропустил все 18 аппаратных тестов без обращения к оборудованию. +Runtime-smoke экранной клавиатуры проходит со встроенной и установленной DLC-темой на +`--mock-hardware=true`; отдельно проверена недоступность фиксированной кнопки выхода при каждой +текстовой, цифровой и сервисной цифровой клавиатуре, а также физический hit-test нижнего ряда +текстовой и цифровой панелей поверх отключённого футера. +Авторские клавиши контроллера после каждой вставки, удаления, очистки или замены выделения +немедленно отправляют одно `LineEdit.TextChanged`; для `SpinBox` затем сразу вызывается `Apply()`. +Поэтому рабочая копия Settings и автосохранение больше не ждут первого нажатия «Стереть». + +Отдельный `TokenInventoryAccountingSmoke` проходит во встроенной теме, `example.pck` и +`space-pixel.pck` только в заранее подготовленных изолированных user-профилях с +mock-оборудованием. Прямой запуск на рабочем `user://` запрещён, потому что сценарий намеренно +переключает и автосохраняет параметры учёта. Он подтверждает включённый по +умолчанию учёт и отдельный лимит, разрешение оплаты при выключенном только лимите с сохранением +числовых элементов, а также скрытие сервисных элементов и приблизительного остатка Home при +выключении самого учёта. Реальный COM/UART не открывался. +Свежие пакеты Builder: `example.pck` — 464876 байт, SHA-256 +`02B8505FB7F0EF4F4E9C2905D97E8F8751A1DDE86DDF460AFC958CCE6AF51994`; +`space-pixel.pck` — 1658080 байт, SHA-256 +`89FD110EE067513CA19804F63208EE59400306EB14044CB0BAA1E95AAE0D13AA`. +Активный пользовательский PCK не устанавливался и остался размером 1436988 байт, SHA-256 +`4D9AA00FE2096794331B348916D1766B47A45D9EDFEE60BEAB0E424ED4761A67`. + +`PaymentRewardFormattingSmoke` использует Debug-only C# bridge только для снятия лимита покупки +в памяти трёх экранов. Он не открывает Settings и не меняет рабочий JSON, выбирает первый +фактический пресет и сравнивает карточные base/bonus с CashPayment вместо ожидания конкретного +бонусного правила. Встроенная тема, `example.pck` и актуальный `space-pixel.pck` проходят этот +smoke на mock-оборудовании. + +В Settings точный учтённый остаток отображается как суммарно, так и отдельно для hopper 1/2. +Значения берутся из `TokenInventorySnapshot.Hopper1Count/Hopper2Count` и обновляются после +подтверждённой выдачи, пересчёта и ручного добавления. Fallback и `space-pixel` прошли runtime-smoke +с mock-оборудованием; внешний PCK принят по контракту из 481 биндинга. В Theme Builder сервисная +панель визуально проверена в `720×1280`: обе подписи полностью видимы и не перекрывают кнопки. + +Все динамические количества жетонов в пользовательском платёжном/выдачном потоке используют +единый `TokenCountFormatter`: `1 жетон`, `2–4 жетона`, `5–20 жетонов`, с отдельным правилом для +`11–14`. Исправлены CardAmount, CardCustomAmount, CashPayment, CardTerminal и Success, включая +прогресс выдачи и подарочные жетоны. Сцены внешней темы не менялись: host подставляет только текст. +Runtime-smoke с явным `space-pixel.pck` и mock-оборудованием прошёл без binding-ошибок. + +В `CardCustomAmountScreen` видимая левая кнопка нижнего ряда использует сохранённый legacy-binding +`...clear_button`, но теперь выполняет удаление только последней цифры. Её подпись во встроенной и +актуальных внешних темах — «СТЕРЕТЬ»; отдельный обязательный `BackspaceButton` сохранён скрытым для +совместимости контракта. Пустой ввод после удаления отображается как `0`. Старый установленный PCK +уже получает новую логику без пересборки, хотя его прежняя надпись изменится только после обновления +самого пакета темы. Обе актуальные Builder-темы собраны и проверены; `space-pixel` визуально +проверен при 720×1280, слово «СТЕРЕТЬ» целиком помещается в кнопку, а новый PCK проходит runtime +production-loader на mock-оборудовании. + +Маршрутизация `DualHopperAuto` использует строгий приоритет hopper 1. При запросе `N` планируется +`H1=min(N, остаток H1)`, `H2=N-H1`; команда hopper 2 отправляется только после всех ожидаемых +подтверждений hopper 1. Недостаточный суммарный учётный остаток блокирует выдачу до отправки +`309N/409N`. Mock использует то же правило и больше не учитывает несуществующие жетоны. +Выдача более 99 жетонов из любого одного хоппера выполняется строго последовательно пакетами: +например, 205 превращается в `99 → 99 → 7`; следующий пакет не отправляется по `APPEND` или после +98 подтверждений, а только после последнего ожидаемого `OK`. При переходе между хопперами сначала +завершаются все пакеты hopper 1, затем начинается первый пакет hopper 2. + +Runtime-smoke 2026-09-02 в Godot 4.7.1 Mono с mock-оборудованием подтвердил Settings: +короткое касание не прокручивает список, drag одним пальцем работает в обе стороны, +drag зажатой ЛКМ прокручивает список; диалог ручного пополнения обоих хопперов автоматически +показывает цифровую клавиатуру и получает фокус. Fallback и явный `space-pixel.pck` прошли. +Физическую проверку исправлений на тачскрине автомата всё равно выполнить по ROADMAP 4.1. + +Не запускать build и test параллельно: оба могут писать один Release Exchanger.dll и +дать ложный CS2012 file in use. + +Hardware tests: + + tests/Exchanger.HardwareTests/run-board-tests.ps1 + +Категории: HardwareProbe, HardwareSafe, HardwareInteractive, HardwarePayment, +HardwareDispense, HardwareCable. Даже safe требует разрешения и свободного COM. +Payment/Dispense/Interactive не запускать автоматически. + +One-file параметры desktop-экспорта: + + binary_format/embed_pck=true + dotnet/embed_build_outputs=true + include_filter="config/*.toml" + +Windows-пресеты разделены по назначению: + + Windows x64 Release -> artifacts/windows/release/Exchanger.exe + Windows x64 Debug -> artifacts/windows/debug/Exchanger.Debug.exe + +CLI-сборщик `tools/export-windows.ps1` принимает `-Configuration Release|Debug`; значение по +умолчанию — Release. Скрипт жёстко сопоставляет конфигурацию с `--export-release` или +`--export-debug`, поэтому для воспроизводимой сборки не использовать общий ручной режим экспорта. +Debug включает console wrapper, debug symbols и C# sources; Release отключает их. + +Фактическая проверка 2026-09-02: + + artifacts/windows/Exchanger-0.6.0-Debug-20260902-104450/ + artifacts/windows/Exchanger-0.6.0-Release-20260902-104532/ + +Debug создал `Exchanger.Debug.exe` (185175952 байта) и `Exchanger.Debug.console.exe` +(91136 байт). Release создал единственный `Exchanger.exe` (190151408 байт). Оба основных EXE +прошли headless smoke с `--mock-hardware=true --no-theme-dlc`, exit code 0, без физического COM. +Контрольные файлы `NotSigned`; не считать наличие `codesign/enable=true` гарантией подписи — +проверять `Get-AuthenticodeSignature` для каждого release-артефакта. + +Нельзя исключать весь addons/**: это удаляет runtime GodotxToast. Исключаются только: + + addons/godot_ai/** + addons/log/** + addons/reload_current_scene/** + +`addons/native_video` — runtime GDExtension и не исключается из export. Он регистрирует +`NativeVideoStream` для MP4/MOV/M4V, который host загружает через обычный `VideoStreamPlayer` без +зависимости C#-кода от типа расширения; OGV сохраняет встроенный fallback `VideoStreamTheora`. +Внешний MP4/MOV/M4V остаётся по исходному пути и передаётся Native Video напрямую. Windows +backend переводит абсолютный drive-path в UTF-16 file URI, поэтому Unicode и пробелы не требуют +копии, служебной ссылки или ASCII-псевдонима. +Windows использует Media Foundation. На Debian/Ubuntu до runtime-приёмки нужны GStreamer runtime +`libgstreamer1.0-0`, `libgstreamer-plugins-base1.0-0`, `gstreamer1.0-plugins-base`, +`gstreamer1.0-plugins-good`, `gstreamer1.0-plugins-bad`, `gstreamer1.0-libav` и +`gstreamer1.0-vaapi`, а также Vulkan и доступный аппаратный декодер. Для диагностики допустима +переменная `GODOT_NATIVE_VIDEO_ALLOW_SOFTWARE=1`, но она не является production-режимом. + +Текущий export: + + artifacts/windows/test_q/Exchanger.exe + +В test_q должен быть ровно один EXE, без DLL, PCK и QA-файлов. + +Добавлен Linux-пресет: + + Linux x86_64 (Debian 13) + artifacts/linux/debian13/Exchanger.x86_64 + +Он использует официальный Linux x86_64 .NET export template, встраивает PCK и managed +build outputs, сохраняет production-фильтры Windows-пресета и включает config/*.toml. +Release-экспорт фактически выполнен на Windows-хосте через Godot 4.7.1: актуальный файл имеет +размер 155351952 байта; заголовок 7F 45 4C 46, ELFCLASS64 = 2, +e_machine = 0x003E (AMD64/x86_64). dotnet publish использовал RID linux-x64, +self-contained = true и включил native System.IO.Ports. На Debian файл ещё не +запускался, поэтому runtime, графика, touch, DLC и UART там пока не приняты. +Наличие пресета ещё не означает полную Linux-готовность. Платформенная валидация serial-path +уже реализована и покрыта тестами; до физической приёмки Debian нужно настроить доступ сервисного +пользователя через dialout/udev, подготовить Linux kiosk/autostart и проверить touch, DLC, UART +и watchdog на целевом ПК. + +Последний файл: + +- 190229328 байт; +- Authenticode CN=Robotail; +- timestamp DigiCert; +- сертификат самоподписанный, поэтому без доверенного корня Windows может показать + недоверенную цепочку. + +Безопасный packaged smoke: + + .\artifacts\windows\test_q\Exchanger.exe --headless --quit-after 180 -- --mock-hardware=true + +После него проверить godot.log и exchanger.log. Успешный export недостаточен: +обязательно запустить готовый EXE и проверить сцену, конфигурацию и тему. + +## 15. Последний runtime-снимок + +На 2026-09-01 после исправления one-EXE: + +- space-pixel активирована; +- главный экран создаётся без исключений; +- COM3 доступен; +- контроллер прошёл handshake; +- журнал подтвердил безопасное исходное состояние; +- godot.log не содержал ERROR/Exception; +- видимый Exchanger.exe был оставлен запущенным и отвечал. + +Это исторический снимок. В новом чате проверить процессы: Exchanger может удерживать COM3. + +Исправленная критическая ошибка one-EXE: + +1. res:// ошибочно передавался System.IO; +2. TOML не включался в export; +3. addons/** удалял runtime-autoload. + +Не откатывать исправления в AppSettingsLoader.cs, export_presets.cfg и +ProjectAssetSmokeTests.cs. + +## 16. Дорожная карта и открытые задачи + +Завершены этапы 0–6. Этап 8 выполняется; этапы 7, 9 и 9.1 частично закрыты. +Все проверки, требующие физического автомата, централизованы в ROADMAP.md, раздел +«4.1. Проверки на автомате», и не переоткрывают завершённые программные этапы. + +Ближайшие задачи: + +1. Выполнить централизованный пакет физических проверок ROADMAP 4.1: панель/touch, + производительность, контроллер, платежи, оба хоппера, пересчёт и 24-часовой soak. +2. Подготовить установку, обновление и откат Windows-релиза. +3. Провести чистую установку на целевом Windows-устройстве и определить production-доверие подписи. +4. Зафиксировать пару версий приложения и прошивки. +5. Завершить Linux-адаптацию: udev/dialout, kiosk/autostart и физическая приёмка. +6. Android-порт — после desktop MVP; физическая Android-приёмка также перечислена в ROADMAP 4.1. + +ROADMAP синхронизирован 2026-09-07: добавлена отключаемая политика точного учёта и её отдельная +физическая проверка; ранее удалено устаревшее утверждение, что плата отключена, +зафиксированы one-file Windows export, текущее состояние подписи, успешная историческая +авторизация COM3 и отдельный этап Linux x86_64 для Debian 13. Новые аппаратные действия +по-прежнему требуют проверки фактического подключения/занятости COM3 и отдельного разрешения. + +## 17. Известные ловушки + +- Успешный export не означает успешный runtime. +- Linux-пресет не делает Windows-имя COM3 переносимым для реального оборудования: при + `use_mock = false` в Debian нужен `/dev/ttyUSB*`, `/dev/ttyACM*` либо стабильный + `/dev/serial/by-id/*`; при `use_mock = true` поле порта намеренно игнорируется. +- GlobalizePath для res:// не превращает packed resource в обычный файл. +- TOML требует include_filter. +- Нельзя исключать весь addons/** при runtime-autoload GodotxToast. +- Открытый Godot Editor может держать старую C# assembly. +- Godot 4.7.1 сообщает в headless runtime о неподдерживаемом SVG boot splash + `res://src/images/logo.svg` и использует стандартный splash; это не сорвало runtime-smoke, + но production splash нужно отдельно перевести в PNG. +- Exchanger или plate_config_app может удерживать COM3. +- Проверять реальные metadata DLC до активации. +- Host не должен переделывать существующие визуальные элементы темы; разрешено только точечное + добавление готового встроенного fallback для отсутствующего обязательного биндинга. +- Не считать INPUT вместе с HOPPER OK/PULSE. +- Датчик уровня бинарный. +- Отключение точного учёта не очищает файл остатка; перед повторным включением после реальных + выдач обязательно пересчитать хопперы. +- Не смешивать 30X/IN1/IN24 и 40X/IN4/IN25. +- APPEND не подтверждает физическую выдачу; подтверждает только OK. +- Не выводить developer-кадры в пользовательский UI. +- Settings владельца — не инженерная панель. + +## 18. Канонические документы + +- README.md — обзор и запуск. +- ROADMAP.md — план и прогресс. +- .agents/AGENTS.md — инструкции агентов. +- docs/architecture/decisions.md — архитектура. +- docs/THEME_DLC.md — темы. +- docs/REFERENCE_ANALYSIS.md — референсы. +- docs/hardware/PERIPHERY_CONTROLLER_2_3_5.md — контроллер. +- docs/hardware/BOARD_ACCEPTANCE_TESTS.md — приёмка платы. +- docs/operations/TECHNICAL_CONFIGURATION.md — TOML. +- docs/operations/SETTINGS_ACCESS_MATRIX.md — настройки владельца. +- docs/operations/ON_SCREEN_KEYBOARD.md — клавиатура. +- docs/operations/WINDOWS_EXPORT.md — export. +- docs/operations/WINDOWS_KIOSK_SETUP.md — kiosk. +- docs/operations/RECOVERY_AND_MOCK_QA.md — восстановление. +- docs/operations/SOAK_TEST.md — soak. +- docs/operations/PERFORMANCE_BASELINE.md — производительность. + +## 19. Чек-лист передачи результата + +- [ ] В начале вызван agentmemory. +- [ ] Прочитаны профильные файлы и проверено текущее состояние. +- [ ] Не использовался Ziva-Godot. +- [ ] COM не затрагивался без разрешения. +- [ ] Host не менял визуальную структуру сцен темы. +- [ ] Не затёрты пользовательские файлы. +- [ ] dotnet build прошёл без ошибок/предупреждений. +- [ ] Релевантные NUnit-тесты прошли. +- [ ] Проверены godot.log и exchanger.log. +- [ ] После export запущен именно готовый EXE. +- [ ] git diff --check чист. +- [ ] README/ROADMAP/docs обновлены при изменении контракта. +- [ ] Итог сохранён в agentmemory с project: exchanger. + +## 20. Последнее изменение: Native Video и Mobile/Vulkan + +Проект переведён с Compatibility на Mobile/Vulkan ради GDExtension `addons/native_video`. +Настройки промо принимают OGV, MP4, MOV и M4V, а системный диалог выбора показывает все четыре +формата. Автоматические NUnit-проверки фиксируют список форматов, Mobile-настройки проекта, +наличие release-библиотек Windows/Linux и отсутствие исключения addon из export. Headless Godot +успешно загрузил проект и GDExtension, но реальное MP4-воспроизведение требуется принять на GPU +целевой Windows и Debian-системы. + +Внешние MP4/MOV/M4V остаются по исходному пути и на Windows передаются Native Video напрямую: +backend формирует UTF-16 file URI без копии, служебной ссылки или ASCII-псевдонима. При +переходе с Home на Settings `VideoStreamPlayer` ставится на паузу, а при возврате возобновляется. +После исправления lifecycle Native Video переход Home → Settings, смена плейлиста и Dispose штатно вызывают `Stop()`, очищают `Stream` и освобождают decoder/audio pipeline. При возврате ролик открывается заново с позиции 0; временный кэш player/stream больше не используется. + +## 21. Последнее изменение: автоматический поиск UART + +В `[controller].port` технического TOML разрешены режимы автопоиска: `COM` в Windows и +`ttyUSB` (также `/dev/ttyUSB`) в Linux. На первичном подключении и каждом штатном reconnect +приложение читает список доступных портов ОС, отбирает нужный тип, сортирует по числу с нуля +и проверяет кандидаты штатной авторизацией до первого `READY!`. Ошибка открытия либо handshake +продолжает текущий перебор, а физический обрыв уже авторизованного контроллера сохраняет паузу +`reconnect_interval_seconds` до нового цикла. Полные имена порта сохраняют точный прежний режим; Linux также принимает короткое точное имя `ttyUSB<номер>` и открывает соответствующий `/dev/ttyUSB<номер>`. + + +## 22. Последнее изменение: перцептивная громкость промо + +Громкость промо применяется к шине `Advertisement`, направленной в `Master`. Шкала 1–100 % +теперь равномерно отображается в диапазон −60…0 dB: 3 % = −58.2 dB, 50 % = −30 dB, 100 % = +0 dB; 0 % по-прежнему принудительно отключает шину (−80 dB и mute). Это заменило прежнюю +амплитудную формулу `20 × log10(percent / 100)`, при которой 3 % давали лишь −30.46 dB и +воспринимались слишком громко. Изменение закреплено тестами `AudioVolume_ConvertsPercentToDecibels`. + +## 23. Последнее изменение: переносимая Linux-сборка Native Video + +11 сентября 2026 года Linux Debug/Release-библиотеки в `addons/native_video` и +`artifacts/linux/debian13` заменены переносимыми x86_64-сборками. Предыдущее падение +`SIGILL` в `native_video_init` на целевом MiniPC вызывала инструкция AVX-512, +унаследованная от CPU машины сборки; кириллица в пути проекта к падению не относилась. +Новые библиотеки собраны для baseline x86_64 без AVX/AVX2/AVX-512 и прошли проверку +дизассемблированием. + +- Debug SHA-256: `70BA73836A2696BF57B590A17A6D87D2CB40EAB19C43E7FB2FAA8B745CF613FA`. +- Release SHA-256: `7D08177448F28D912818804E159EDD3088DC894191175776E22679E7FBDDE9A6`. + +Обе библиотеки успешно загружаются Godot 4.6.3 в Linux; GStreamer decode-smoke +подтвердил видео, AAC-аудио, seek и повторное открытие. Готовый +`artifacts/linux/debian13/Exchanger.x86_64` после переноса библиотек прошёл WSL +headless-smoke в Godot 4.7.1 с mock-оборудованием без `SIGILL`; физический запуск на +целевом MiniPC после замены файла остаётся обязательной проверкой. + +## 24. Последнее изменение: выравнивание интерактивного питомца + +11 сентября 2026 года в теме `space-pixel` устранено лишнее смещение всех +non-sitting-анимаций на `(0, -24)` локальных пикселя. При runtime scale `0.845` +оно поднимало видимого питомца на `20,28` экранного пикселя относительно корректной +anchor-точки поверхности. После визуального уточнения владельца только анимация +`sitting` получила отдельное положительное смещение `(0, 24)`, то есть опущена на +`20,28` экранного пикселя; все остальные анимации остаются с нулевым смещением. +`GROUND_OFFSET = (64, 96)`, координаты поверхностей, маршруты, Exchanger host и +binding-контракт не менялись. + +Новый `space-pixel.pck` имеет размер 1700352 байта и SHA-256 +`931A2EAA118722B95E49EA097C8CE41CE9E655F2CF7248CCA050B28A9AF50357`. +Он установлен как `user://theme_dlc/active_theme.pck`; предыдущая пользовательская +версия сохранена рядом как `active_theme.before_sitting_lower_fix_20260911.pck`, а +исходный пакет до обеих правок — как `active_theme.before_pet_alignment_fix_20260911.pck`. +Полный `InteractivePetBehaviorSmoke` Exchanger с явным новым PCK и mock-оборудованием +прошёл: drag, landing, смена экранов, навигация и composite-action завершились успешно. +Дополнительный headless-запуск через установленный `user://active_theme.pck` подтвердил +его загрузку и активацию питомца без ошибок запуска. Для применения новой темы в уже +открытом приложении требуется полный перезапуск процесса Exchanger. + + +## 23. Последнее изменение: изоляция удалённых промо-роликов + +> Историческая запись: описанный ниже cache workaround удалён и заменён штатным lifecycle из раздела 27. + +Из-за fail-fast Native Video 4.7 приложение не вызывает для внешнего MP4 `VideoStreamPlayer.Stop()` и не очищает `Stream` во время работы: поток и его player остаются в кэше до закрытия экрана/перезапуска. При любом изменении плейлиста путь, удалённый из `Advertisement.VideoPaths`, теперь сразу изолируется: его player получает `Paused = true`, `VolumeDb = -80 dB` и `Visible = false`. При возврате с Settings возобновляется только player, путь которого всё ещё состоит в актуальном плейлисте; иначе выбирается следующий актуальный ролик либо показывается постер/текст. Логика идентична для встроенного промо-узла и DLC theme presenter. Автоматически проверены build и 548 NUnit-тестов; Native Video scenario требует ручной GPU-проверки: удалить активный MP4, сохранить, выйти из Settings — звук удалённого ролика не должен появиться. + +Повторное добавление ранее удалённого пути не переиспользует позицию паузы: путь хранится в quarantine-наборе, а при следующем выборе соответствующему кэшированному player задаётся `StreamPosition = 0` до `Play()`. Это сохраняет безопасный cache workaround и гарантирует старт ролика с начала. + +## 25. Последнее изменение: устойчивость lifecycle промо-роликов + +> Историческая запись: лимит и retention-cache больше не существуют; актуальная модель описана в разделе 27. + +Кэш VideoStreamPlayer, необходимый как обход fail-fast Native Video при teardown, +теперь ограничен 24 уникальными нормализованными путями за запуск (двукратный лимит +настроечного плейлиста из 12 роликов). Если лимит исчерпан, новый путь не открывается, +а в лог пишется предупреждение о необходимости перезапустить приложение; это +предотвращает неограниченный рост кэша при последовательных заменах роликов. + +Подписка Finished ведётся отдельно для каждого player. Обработчик переключает +плейлист только если сигнал пришёл от текущего активного, не paused и всё ещё +настроенного ролика; сигналы скрытых/изолированных player игнорируются. При +закрытии узла/презентера все обработчики снимаются. В presenter также игнорируются +отложенные сигналы после Dispose. + +Валидация дубликатов видео использует тот же NormalizeSelectedVideo, что и runtime: +варианты одного Windows-пути с обратными и прямыми слешами считаются одинаковыми и +подсвечиваются в обеих строках. Известное ограничение остаётся: если файл заменён +по тому же абсолютному пути, текущий кэшированный stream не перезагружается до +перезапуска приложения. Полное безопасное освобождение/reload должен предоставить +Native Video GDExtension. Автоматически подтверждены dotnet build без предупреждений +и 549 NUnit-тестов; требуется ручная GPU-проверка смены плейлистов и возврата из +Settings. + +## 26. Последнее изменение: нормализация и безопасные ошибки промо + +Для промо-плейлиста введён единый comparison key: пробелы и обратные слеши нормализуются во всех точках, а на Windows дополнительно игнорируется регистр имени файла; на Linux регистр сохраняет значение. Этот ключ используют нормализация AppSettings, проверка дубликатов и снимок применённых настроек. Поэтому запись одного ролика как C:\\Ads\\clip.mp4 и C:/Ads/clip.mp4 больше не создаёт две записи. + +Оба промо-адаптера также не реагируют на `Finished`, когда узел скрыт, промо отключено или presenter уже освобождён. `AdvertisementPlayer` заново подписывается на событие при повторном входе готового узла в scene tree. Ошибка обычной загрузки/старта ролика записывается в журнал и переводит плейлист к следующему файлу вместо падения UI. Ограничение на `Stop()` и очистку `Stream` снято исправлением из раздела 27. + +## 27. Последнее изменение: штатный lifecycle Native Video + +16 сентября 2026 года Native Video исправлен для `Stop()`, `Stream = null`, смены внешнего +MP4 и `QueueFree()`. Дополнительно устранён panic при повторном назначении кэшированного +`NativeVideoStream`: Godot ObjectID со старшим битом теперь передаётся через gdzig с сохранением +битового представления. `AdvertisementPlayer` и `AdvertisementPresenter` переведены на один +player без retention-cache и quarantine; скрытие, смена настроек и Dispose полностью завершают +decode/audio pipeline, а повторное назначение начинает воспроизведение с позиции 0. + +Автоматически пройдены 549 NUnit-тестов и отдельная runtime-сцена на Godot 4.7.1: 50 смен +двух внешних MP4, пять пересозданий активного промо-узла и десять циклов скрытия/возврата. +Windows и Linux Debug/Release-библиотеки синхронизированы в `addons/native_video`; Linux-копии +также обновлены в `artifacts/linux/debian13`. Headless-тест подтверждает decode/audio/lifecycle, +но финальная визуальная приёмка Vulkan-презентации на целевых GPU остаётся ручной. + +## 28. Последнее изменение: доступность переключателя питомца + +В «Скрытии элементов меню» готовый `CheckButton` теперь имеет подпись +«ИНТЕРАКТИВНЫЙ ПИТОМЕЦ». Он по-прежнему сохраняет пользовательское +`MenuVisibility.ShowInteractivePet` и управляет `InteractivePetHost`, но становится недоступным +и визуально выключенным, когда активная тема не объявляет `InteractivePetScene`. Предпочтение не +перезаписывается: при последующем подключении темы с питомцем прежнее значение сразу применяется. +Обновлены встроенная сцена Settings и production-сцены `example`/`space-pixel` Theme Builder; +существующий optional supplemental binding не изменялся, поэтому старые темы остаются совместимы. diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..f28239b --- /dev/null +++ b/.editorconfig @@ -0,0 +1,4 @@ +root = true + +[*] +charset = utf-8 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..8ad74f7 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# Normalize EOL for all files that Git considers text files. +* text=auto eol=lf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..240b2f1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,18 @@ +# Godot 4+ specific ignores +.godot/ +/android/ +**/bin/ +**/obj/ + +# Local visual and video references +references/ + +# Local reports from physical controller acceptance tests +artifacts/board-tests/ + +# Local runtime soak reports +artifacts/soak/ + +# Reproducible Windows exports and sanitized staging project +artifacts/windows/ +artifacts/export-staging/ diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..ca74aef --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,26 @@ +{ + "version": "0.2.0", + "configurations": [ + { + // Используйте IntelliSense, чтобы узнать, какие атрибуты существуют для отладки C#. + // Используйте наведение для описания существующих атрибутов + // Для получения дополнительных сведений посетите https://github.com/dotnet/vscode-csharp/blob/main/debugger-launchjson.md + "name": ".NET Core Launch (console)", + "type": "coreclr", + "request": "launch", + "preLaunchTask": "build", + // Если вы изменили требуемые версии .NET Framework, обязательно обновите путь к программе. + "program": "${workspaceFolder}/tests/Exchanger.Tests/bin/Debug/net8.0/Exchanger.Tests.dll", + "args": [], + "cwd": "${workspaceFolder}/tests/Exchanger.Tests", + // Дополнительные сведения о поле \"console\" см. в https://aka.ms/VSCode-CS-LaunchJson-Console + "console": "internalConsole", + "stopAtEntry": false + }, + { + "name": ".NET Core Attach", + "type": "coreclr", + "request": "attach" + } + ] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..1f2ed10 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "godotTools.editorPath.godot4": "d:\\Applications\\Godot\\Godot_v4.7.1-stable_mono_win64\\Godot_v4.7.1-stable_mono_win64.exe" +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..4b4dc70 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,41 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "build", + "command": "dotnet", + "type": "process", + "args": [ + "build", + "${workspaceFolder}/tests/Exchanger.Tests/Exchanger.Tests.csproj", + "/property:GenerateFullPaths=true", + "/consoleloggerparameters:NoSummary;ForceNoAlign" + ], + "problemMatcher": "$msCompile" + }, + { + "label": "publish", + "command": "dotnet", + "type": "process", + "args": [ + "publish", + "${workspaceFolder}/tests/Exchanger.Tests/Exchanger.Tests.csproj", + "/property:GenerateFullPaths=true", + "/consoleloggerparameters:NoSummary;ForceNoAlign" + ], + "problemMatcher": "$msCompile" + }, + { + "label": "watch", + "command": "dotnet", + "type": "process", + "args": [ + "watch", + "run", + "--project", + "${workspaceFolder}/tests/Exchanger.Tests/Exchanger.Tests.csproj" + ], + "problemMatcher": "$msCompile" + } + ] +} \ No newline at end of file diff --git a/Exchanger.csproj b/Exchanger.csproj new file mode 100644 index 0000000..4d3eb72 --- /dev/null +++ b/Exchanger.csproj @@ -0,0 +1,19 @@ + + + net8.0 + net9.0 + true + enable + + + + + + + + + + + diff --git a/Exchanger.sln b/Exchanger.sln new file mode 100644 index 0000000..86296b9 --- /dev/null +++ b/Exchanger.sln @@ -0,0 +1,108 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio 2012 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Exchanger", "Exchanger.csproj", "{5D613F27-48AD-4F54-BA37-F1FA68853047}" +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{0AB3BF05-4346-4AA6-1389-037BE0695223}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Exchanger.Tests", "tests\Exchanger.Tests\Exchanger.Tests.csproj", "{EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Exchanger.HardwareTests", "tests\Exchanger.HardwareTests\Exchanger.HardwareTests.csproj", "{B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Debug|x64 = Debug|x64 + Debug|x86 = Debug|x86 + ExportDebug|Any CPU = ExportDebug|Any CPU + ExportDebug|x64 = ExportDebug|x64 + ExportDebug|x86 = ExportDebug|x86 + ExportRelease|Any CPU = ExportRelease|Any CPU + ExportRelease|x64 = ExportRelease|x64 + ExportRelease|x86 = ExportRelease|x86 + Release|Any CPU = Release|Any CPU + Release|x64 = Release|x64 + Release|x86 = Release|x86 + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Debug|Any CPU.Build.0 = Debug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Debug|x64.ActiveCfg = Debug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Debug|x64.Build.0 = Debug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Debug|x86.ActiveCfg = Debug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Debug|x86.Build.0 = Debug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportDebug|Any CPU.ActiveCfg = ExportDebug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportDebug|Any CPU.Build.0 = ExportDebug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportDebug|x64.ActiveCfg = ExportDebug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportDebug|x64.Build.0 = ExportDebug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportDebug|x86.ActiveCfg = ExportDebug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportDebug|x86.Build.0 = ExportDebug|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportRelease|Any CPU.ActiveCfg = ExportRelease|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportRelease|Any CPU.Build.0 = ExportRelease|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportRelease|x64.ActiveCfg = ExportRelease|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportRelease|x64.Build.0 = ExportRelease|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportRelease|x86.ActiveCfg = ExportRelease|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.ExportRelease|x86.Build.0 = ExportRelease|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Release|Any CPU.ActiveCfg = Release|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Release|Any CPU.Build.0 = Release|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Release|x64.ActiveCfg = Release|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Release|x64.Build.0 = Release|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Release|x86.ActiveCfg = Release|Any CPU + {5D613F27-48AD-4F54-BA37-F1FA68853047}.Release|x86.Build.0 = Release|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Debug|Any CPU.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Debug|x64.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Debug|x64.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Debug|x86.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Debug|x86.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportDebug|Any CPU.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportDebug|Any CPU.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportDebug|x64.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportDebug|x64.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportDebug|x86.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportDebug|x86.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportRelease|Any CPU.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportRelease|Any CPU.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportRelease|x64.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportRelease|x64.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportRelease|x86.ActiveCfg = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.ExportRelease|x86.Build.0 = Debug|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Release|Any CPU.ActiveCfg = Release|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Release|Any CPU.Build.0 = Release|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Release|x64.ActiveCfg = Release|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Release|x64.Build.0 = Release|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Release|x86.ActiveCfg = Release|Any CPU + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B}.Release|x86.Build.0 = Release|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Debug|Any CPU.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Debug|x64.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Debug|x64.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Debug|x86.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Debug|x86.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportDebug|Any CPU.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportDebug|Any CPU.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportDebug|x64.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportDebug|x64.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportDebug|x86.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportDebug|x86.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportRelease|Any CPU.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportRelease|Any CPU.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportRelease|x64.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportRelease|x64.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportRelease|x86.ActiveCfg = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.ExportRelease|x86.Build.0 = Debug|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Release|Any CPU.Build.0 = Release|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Release|x64.ActiveCfg = Release|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Release|x64.Build.0 = Release|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Release|x86.ActiveCfg = Release|Any CPU + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44}.Release|x86.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(NestedProjects) = preSolution + {EF7558BC-5B7E-43F7-9891-A62AC6AA3B5B} = {0AB3BF05-4346-4AA6-1389-037BE0695223} + {B1A95F7E-8D83-4D19-A91E-1CF7089E2D44} = {0AB3BF05-4346-4AA6-1389-037BE0695223} + EndGlobalSection +EndGlobal diff --git a/README.md b/README.md new file mode 100644 index 0000000..dc8fcec --- /dev/null +++ b/README.md @@ -0,0 +1,359 @@ +# Exchanger + +Exchanger — полноэкранное тач-приложение для напольного разменника, продающего и выдающего жетоны за наличную или безналичную оплату. Проект разрабатывается на Godot 4.7 Mono/C# для Windows x64 с расчётом на будущий перенос аппаратного транспорта на Android ARM64. + +Целевой аппарат использует портретный тач-экран, показывает цену и бинарное состояние запаса жетонов («много»/«мало»), принимает наличные через купюро- и монетоприёмник либо запускает оплату на отдельном банковском терминале, после чего безопасно инициирует выдачу. События оплаты, баланса, запаса и выдачи должны поступать от внешнего контроллера автомата. + +## Текущее состояние + +Завершены Этапы 0–3, программная часть Этапа 4 и весь программный пакет Этапа 6; приложение проходит полный пользовательский сценарий на типизированном mock-контроллере и документированный wire-профиль 2.3.5 на детерминированном симуляторе. После обновления авторизации физическая плата на COM3 прошла отдельный строгий auth-probe 1/1 и безопасную автоматическую приёмку 8/9: startup-баннер, AES-handshake, точный `READY!`, цифровые входы, четыре status-запроса и три цикла переподключения работают; отдельный запрос состояния Вендиста `160` дважды остался без ответа. Интерактивные платежи, выдача и отключение USB остаются отдельными явно подтверждаемыми проверками. + +Указанные результаты COM3 относятся к предыдущему состоянию прошивки. После текущего обновления протокола плата отключена, поэтому новая разводка и команды пока проверены только симулятором; аппаратная приёмка отложена до её подключения. + +- главная сцена `src/scenes/App/App.tscn`; +- портретный `HomeScreen` с ценой, запасом, двумя способами оплаты, промо-fallback и поддержкой; +- рабочие ветки наличной и карточной оплаты, включая другую сумму, ожидание терминала, успех и отказ; +- `ScreenManager` Autoload с централизованным реестром, fade-переходами и блокировкой повторного ввода; +- единственная встроенная программная fallback-тема; +- безопасная замена fallback-темы одним внешним DLC-пакетом `.pck` при запуске; +- статический фон DLC-темы с отдельным слоем анимированных спрайтов; +- облегчённый режим, отключающий необязательные фоновые анимации; +- типизированная внешняя конфигурация; +- файловый журнал с ротацией; +- фильтрация вторичных касаний; +- аппаратный интерфейс `IHardwarePort`; +- рабочие `MockMachineController`, `PeripheryControllerSimulator`, Windows COM-транспорт и безопасная Android-заглушка; +- конфигурируемые тарифы, бонусы, карточные пресеты, способы оплаты, пользовательские таймауты, брендинг, промо и оформление; +- актуальная привязка цифровых входов платы: `IN8` — сервисная кнопка, `IN1` — сигнал «мало жетонов» первого хоппера, `IN24` — его датчик выдачи, `IN4` — сигнал «мало жетонов» второго хоппера; вход датчика выдачи второго хоппера пока не определён; +- компонент состояния запаса жетонов `Enough/Low/Unknown` без фиктивного точного количества; +- отдельный подтверждаемый владельцем учётный остаток жетонов: ручное пополнение, списание подтверждённой выдачи и автоматический пересчёт активного хоппера; +- безопасное состояние соединения `Disconnected/Authenticating/Ready/Faulted` и ненавязчивый сервисный индикатор на домашнем экране; +- `SessionController` с явными состояниями, таймаутами и защитой от повторной выдачи; +- чистый `SessionFlow`, уникальный локальный контекст операции и управляемый монотонный источник времени для тестов; +- типизированные безопасные ошибки и отдельный JSONL-журнал начала/итога операций; +- `AdvertisementPlayer` с локальным плейлистом, постером/текстовым fallback и остановкой вне HomeScreen. +- production kiosk-профиль с borderless fullscreen, скрытым курсором и восстановлением окна после + потери фокуса либо изменения дисплея; +- сервисный вход по аппаратному `SERVICE`: защита включается в самом приложении, первый защищённый вход предлагает дважды задать единый сервисный PIN, последующие входы требуют его проверки; допустимые изменения сохраняются автоматически, повторное нажатие сервисной кнопки возвращает на главный экран; +- шестираздельный редактор настроек владельца автомата: общие данные, звук, промо, тарифы, оплата и сервисный учёт жетонов; + технические параметры, диагностика и тестовая выдача в пользовательском UI отсутствуют; +- Windows watchdog, задача автозапуска и process soak-runner. + +По документации контроллера 2.3.5 реализованы Windows COM-транспорт, framing, строгий startup-handshake и платёжные команды. Порядок авторизации сверен с `plate_config_app`: RTS-reset, баннер `periphery controller ver_`, пауза 2000 мс, `07 → CHAL → 08 → RAES` и допуск к работе только после точной строки `READY!`. Оба хоппера включены в целевой `DualHopperAuto`: первый использует `309N/3090` и `301/300`, второй — `409N/4090` и `401/400`; фактическая выдача подтверждается `HOPPER1/2 OK`, пересчёт — `HOPPER1/2 PULSE=1`. Учётные остатки хранятся отдельно, а выдача списывается с фактически сработавшего канала. Универсальная конфигурация репозитория сохраняет безопасный `Unsupported`, пока профиль конкретного автомата не выбран явно. Подробности: [docs/hardware/PERIPHERY_CONTROLLER_2_3_5.md](docs/hardware/PERIPHERY_CONTROLLER_2_3_5.md). Актуальный прогресс перечислен в [ROADMAP.md](ROADMAP.md). + +После завершения Этапа 1 были изучены визуальные референсы реального корпуса и интерфейса. Они уточнили целевую портретную ориентацию и две разные платёжные ветки. Ландшафтный `StartScreen` удалён и заменён портретным домашним экраном. Подробные выводы находятся в [docs/REFERENCE_ANALYSIS.md](docs/REFERENCE_ANALYSIS.md). + +Этап 0 завершён. Базовые договорённости, включая универсальность до появления целевого железа и отложенную интеграцию контроллера, зафиксированы в [docs/architecture/decisions.md](docs/architecture/decisions.md). + +Команды `309N` и `409N` ограничены 99 жетонами: `309100` и `409100` возвращают ошибки групп 30 и 40. Приложение автоматически разбивает крупную выдачу на последовательные пакеты максимум по 99 жетонов и маршрутизирует их между двумя учётными остатками. + +## Целевой интерфейс по референсам + +- Портретный формат 9:16; нативная сетка интерфейса и preview — 720×1280. +- Пиксельная космическая тема, согласованная с оформлением корпуса: сам фон статичен, а НЛО, персонажи и другие движущиеся элементы реализуются отдельными анимированными спрайтами. +- Домашний экран без дополнительного шага «Начать»: цена жетона, запас, способы оплаты, кнопка выдачи и промо-ролик. +- Наличная ветка: текущий баланс, расчёт жетонов/бонуса, инструкции для купюр и монет. +- Карточная ветка: предустановленные суммы, ввод другой суммы, ожидание прикладывания карты и результат. +- Постоянно видимые брендовые элементы и телефон техподдержки. +- Маскот и фоновые анимации, не перекрывающие функциональные панели. + +Промо-ролик, показанный в референсах, является отдельным ограниченным блоком домашнего экрана и не используется как фон приложения. + +Конкретные числа и графические материалы из референсов пока считаются демонстрационными. Перед production необходимо подтвердить тарифы, бонусы, бренд и права на ассеты. + +## Технологии + +| Компонент | Значение | +| --- | --- | +| Движок | Godot 4.7.1 Mono | +| Язык | C# | +| .NET | .NET 8; Android-конфигурация — .NET 9 | +| Рендерер | Mobile (Vulkan) | +| Основная платформа | Windows x64 | +| Перспективная платформа | Android ARM64 | +| Целевой профиль железа | Пока не определён; приложение проектируется аппаратно-независимым и конфигурируемым | +| Логический viewport | 720×1280, портретный 9:16, `canvas_items/expand` | +| Debug-window | 720×1280 | +| Аппаратный транспорт MVP | COM/Serial на Windows | + +## Требования для разработки + +- Godot 4.7.1 Mono или совместимая версия Godot 4.7 Mono. +- .NET SDK 8. +- Windows x64 для текущей целевой сборки. + +Путь к редактору, используемый локальной конфигурацией VS Code, хранится в `.vscode/settings.json`. На другой машине его необходимо изменить на фактический путь к Godot Mono. + +## Запуск + +### Через Godot Editor + +1. Открыть `project.godot` в Godot 4.7.1 Mono. +2. Дождаться импорта ресурсов и сборки C#-проекта. +3. Запустить главную сцену клавишей `F6` либо весь проект клавишей `F5`. + +В debug- и production-сборках интерфейс использует нативную сетку 720×1280. В полноэкранном режиме Godot масштабирует её на портретную панель через `canvas_items/expand`. + +### Проверка C#-сборки + +```powershell +dotnet build Exchanger.sln +``` + +### Автоматические тесты + +```powershell +dotnet test Exchanger.sln +``` + +Отдельный проект `tests/Exchanger.Tests` использует NUnit 4. Обычный набор тестов выполняется без запуска окна Godot и проверяет конфигурацию, миграции, атомарное сохранение и восстановление настроек, сервисный доступ, учётный остаток и автоматический пересчёт жетонов, безопасный audit, ротацию журналов, настройки оборудования, штатную отмену реального COM-чтения, аудиопараметры, брендинг, промо, DLC-тему, полносценовый binding-контракт, owner-only состав настроек, production export, тарифы, бонусы, карточные суммы, способы оплаты и таймауты, конечный автомат, framing COM-протокола, команды и полные cash/card-сценарии контроллера, обязательные `ASK:*`, взаимоисключение приёмников, строгий startup-handshake `banner → 2000 ms → 07/CHAL/08/RAES → READY!`, AES и восстановление ключа, wire-симулятор, оба формата `INPUT`, актуальную разводку `IN8/IN1/IN4/IN24`, keep-alive Вендиста, at-most-once, раздельный учёт и выдачу обоими хопперами через `309N/409N → APPEND/OK` либо `ERROR/CREDIT`, строковые импульсы раздельного сервисного пересчёта, malformed-кадры, ошибки соединения, JSONL-восстановление и отсутствие накопления подписок. Ускоренный soak моделирует 1440 минут и 480 выдач, а отдельный стресс выполняет 10 000 жизненных циклов `SessionFlow`. Загрузка сцен и ресурсов дополнительно проверяется в Godot Editor через разрешённый проектом MCP-сервер `godot-ai`. + +Для физической платы подготовлен отдельный `Exchanger.HardwareTests` с 18 безопасными и подтверждаемыми приёмочными проверками, включая изолированный handshake probe. Без явного флага они пропускаются и никогда не открывают COM-порт. Порядок проверки handshake, status-команд, SERVICE, приёмников оплаты, Вендиста, датчика, хоппера и USB-reconnect описан в [docs/hardware/BOARD_ACCEPTANCE_TESTS.md](docs/hardware/BOARD_ACCEPTANCE_TESTS.md). + +### Headless smoke-тест + +```powershell +Godot_v4.7.1-stable_mono_win64.exe --headless --path . --quit-after 10 +``` + +### Windows x64 export + +```powershell +.\tools\export-windows.ps1 -Configuration Release +.\tools\export-windows.ps1 -Configuration Debug +``` + +Пресеты `Windows x64 Release` и `Windows x64 Debug` разведены также в редакторе. Скрипт использует +очищенную staging-копию и жёстко выбирает `--export-release` либо `--export-debug`; без параметра +собирается Release. Готовый self-contained каталог создаётся в `artifacts/windows/`. Подробности и +smoke-проверка: [docs/operations/WINDOWS_EXPORT.md](docs/operations/WINDOWS_EXPORT.md). + +## Конфигурация + +Настройки, доступные владельцу автомата, по умолчанию находятся в: + +```text +res://config/default_settings.json +``` + +При первом запуске приложение создаёт пользовательскую копию: + +```text +user://config/appsettings.json +``` + +В пользовательской конфигурации задаются: + +- fullscreen/debug-window режим; +- целевой FPS; +- разрешение и путь к внешнему DLC-пакету темы; +- облегчённый режим эффектов; +- таймауты сессии; +- общая громкость, master mute и отдельная громкость промо-ролика; +- доступность наличной и карточной оплаты, карточные пресеты, максимальная сумма и шаг ручного ввода; +- безопасные таймауты бездействия, ожидания оплаты и показа результата; +- включение промо, звук промо-роликов, fallback-текст, локальный постер и плейлист OGV/MP4/MOV/M4V; +- ограничения файлового журнала. + +Монтажные параметры оборудования вынесены в отдельный TOML-файл: + +```text +res://config/technical_settings.toml +user://config/technical_settings.toml +``` + +Пользовательская копия создаётся при первом запуске и не показывается в интерфейсе приложения. +Она задаёт основной последовательный порт (`COM*` в Windows, `/dev/ttyUSB*`, `/dev/ttyACM*` +или `/dev/serial/by-id/*` в Linux), mock-режим, параметры связи, наличие обоих хопперов, индексы и +полярность их датчиков, сервисную кнопку и интервалы опроса. TOML применяется поверх устаревшего +раздела `Hardware` в JSON; аргумент `--mock-hardware` остаётся последним безопасным переопределением. +Изменения вступают в силу только после полного перезапуска. Схема, диапазоны и порядок проверки: +[docs/operations/TECHNICAL_CONFIGURATION.md](docs/operations/TECHNICAL_CONFIGURATION.md). + +Параметр `[controller].reconnect_interval_seconds` задаёт паузу между повторными открытиями порта. +Штатно это 30 секунд: приложение повторяет подключение, если платы не было при запуске, и начинает +новый полный отсчёт после отключения работавшей платы. Платёжные и выдающие команды при reconnect +никогда не повторяются автоматически. + +Модель настроек содержит цену жетона, бонусные правила, карточные суммы, телефон поддержки и плейлист промо-роликов. Датчики обоих хопперов сообщают только «достаточно» или «мало». Точные подтверждаемые остатки хранятся раздельно в `user://data/token_inventory.json`, начинаются с нуля, уменьшаются после подтверждённой выдачи и меняются отдельными действиями для каждого хоппера в разделе «Сервис». Два независимых переключателя управляют поведением: «Учитывать остаток жетонов» включает ведение и показ точного остатка, а «Не продавать больше остатка» отдельно запрещает покупку сверх сохранённого количества с учётом бонуса. Если ограничение выключено, остаток продолжает отображаться и списываться, но не блокирует оплату. Если выключен сам учёт, скрываются пересчёт, пополнение и приблизительное количество Home, а файл остатка не изменяется. Перед повторным включением учёта после реальных выдач требуется пересчёт. + +Поддерживаются аргументы запуска: + +```text +--windowed +--fullscreen +--theme-dlc=D:\ExchangerThemes\active_theme.pck +--no-theme-dlc +--mock-hardware=true +--reduced-effects +``` + +Конфигурация версии 19 сохраняется через `SettingsService` атомарной заменой файла. Перед изменением +создаётся `appsettings.json.bak`; повреждённый пользовательский JSON восстанавливается из последней +корректной копии либо безопасных значений по умолчанию и не прерывает запуск. + +В debug-сборке с домашнего экрана `F10` переключает тот же сервисный вход; если защита PIN выключена, +редактор открывается напрямую, а при включённой защите сначала используется общая PIN-клавиатура. В редакторе владельца доступны свой текст +для речевого bubble и контакт техподдержки без отдельного предпросмотра раздела, общая громкость, +master mute, отдельная громкость промо-ролика, короткий проверочный сигнал, стоимость жетона, бонусные +правила, карточные пресеты, предел и шаг ручной суммы, доступность наличной/карточной оплаты, +пользовательские таймауты, промо-poster/fallback/плейлист, защита PIN, предварительный расчёт +и автоматическое сохранение. Из всех подходящих бонусных правил применяется один наибольший бонус; значения разных строк не +суммируются. Нулевая цена, значения вне диапазона, повторяющиеся суммы/пороги и отключение обоих +способов оплаты блокируют сохранение и показываются рядом с соответствующим полем. Пустой набор +карточных пресетов допустим: пользователь сохраняет доступ к пункту «Другая сумма». Обычная +release-сборка игнорирует действие `F10`. В production экран PIN открывается только аппаратным +событием `SERVICE`, только из `Home` и только при отсутствии операции. Единый сервисный PIN +включается в разделе «Общие» и дважды задаётся на экране приложения при следующем входе. +Открытый PIN нигде не сохраняется: в JSON находятся только случайная соль, PBKDF2-SHA256-хеш и число итераций; +PIN и производные значения не записываются в журналы. Тема/DLC, COM-порт, mock-режим, параметры +окна/FPS, журналирование, диагностика и тестовая выдача не показываются владельцу. Аппаратные +параметры изменяются только через отдельный TOML при техническом развёртывании. Полная матрица: +[docs/operations/SETTINGS_ACCESS_MATRIX.md](docs/operations/SETTINGS_ACCESS_MATRIX.md). +При тапе на текстовое поле открывается встроенная в тему экранная клавиатура с русской и английской +раскладками, Shift и отдельной страницей спецсимволов; для числового поля открывается цифровая +клавиатура. Обе панели можно скрыть кнопкой справа сверху, а поле автоматически прокручивается выше +клавиатуры. Системная виртуальная клавиатура для этих полей отключена. Подробности: +[docs/operations/ON_SCREEN_KEYBOARD.md](docs/operations/ON_SCREEN_KEYBOARD.md). +Master и промо разведены по Godot +audio buses `Master` и `Advertisement`, поэтому громкость промо-ролика не влияет на остальные звуки. + +Внешняя тема остаётся частью deployment-конфигурации: отсутствующий или не прошедший проверку +пакет оставит встроенную fallback-тему. Путь к `.pck`, включение DLC и `ReducedEffects` намеренно +не показываются в настройках владельца. + +Промо-ресурсы принимаются только из `res://`, `user://` либо по абсолютному локальному пути. +Постеры поддерживают PNG/JPG/JPEG/WEBP, видео — OGV (Ogg Theora), MP4, MOV и M4V. MP4/MOV/M4V +воспроизводятся GDExtension `addons/native_video` через тот же `VideoStreamPlayer`; для них нужен +Mobile или Forward+ (Vulkan), Compatibility не поддерживается. При выборе внешнего MP4/MOV/M4V +ролик остаётся на месте и передаётся Native Video напрямую по исходному пути, включая Unicode и +пробелы; копии, служебные ссылки и ASCII-псевдонимы не создаются. Существование файла проверяется +до сохранения. Отключённое промо может временно хранить недоступный плейлист, но не читает файлы, +не запускает декодирование и показывает на Home безопасный текст «ПРОМО ОТКЛЮЧЕНО». + +Смена плейлиста использует штатный lifecycle Godot: активный player получает `Stop()`, его +`Stream` очищается, а новый источник начинается с позиции 0. То же завершение выполняется при +скрытии HomeScreen и освобождении узла; старый decoder и его аудио не сохраняются в runtime-кэше. +Регрессионная сцена `tests/runtime/NativeVideoLifecycleSmoke.tscn` проверяет 50 смен двух внешних +MP4, скрытие/возврат и многократное удаление активного `AdvertisementPlayer`. + +## Журналы + +Операции приложения записываются в: + +```text +user://logs/exchanger.log +user://logs/operations.jsonl +user://logs/settings-audit.jsonl +``` + +`exchanger.log` содержит диагностические сообщения с уровнем и категорией. `operations.jsonl` хранит структурированные события начала и единственного итога по локальному `OperationId`. `settings-audit.jsonl` фиксирует только время, роль, названия изменённых разделов и необходимость перезапуска. При перезапуске незавершённые операции безопасно закрываются как `UnknownAfterRestart`, без автоматического повтора оплаты или выдачи. Журналы автоматически очищаются по сроку хранения и общему лимиту; платёжные секреты, значения настроек, полные пути и сырые ответы оборудования не записываются. Подробные правила и mock-чек-лист: [docs/operations/RECOVERY_AND_MOCK_QA.md](docs/operations/RECOVERY_AND_MOCK_QA.md). + +## Структура проекта + +```text +res:// +├── docs/ # Архитектурные решения и анализ референсов +├── config/ # Встроенная конфигурация +├── tests/Exchanger.Tests/ # NUnit-тесты чистого ядра и smoke-проверки файлов +├── src/ +│ ├── core/ +│ │ ├── Configuration/ # AppSettings и загрузка JSON +│ │ ├── TechnicalConfiguration/ # Монтажный TOML и его строгая валидация +│ │ ├── Logging/ # Файловый журнал +│ │ ├── Navigation/ # Реестр и менеджер экранов +│ │ ├── Session/ # Конечный автомат операции +│ │ └── ThemeManager/ # Runtime-контракт, fallback и загрузчик DLC +│ ├── hardware/ +│ │ ├── Abstractions/ # IHardwarePort и IMachineController +│ │ ├── MockHardware/ # Имитация сырого транспорта +│ │ ├── MockMachine/ # Типизированный симулятор автомата +│ │ ├── SerialPortHardware/ # Desktop-порт Windows/Linux +│ │ └── UsbSerialHardware/ # Android-заглушка +│ ├── scenes/ +│ │ ├── App/ # Композиционный корень +│ │ ├── ServiceAccessScreen/ # Защищённый PIN-вход +│ │ ├── SettingsScreen/ # Настройки владельца и сервисный учёт +│ │ ├── HomeScreen/ # Домашний экран +│ │ ├── CashPaymentScreen/ # Оплата наличными +│ │ ├── CardAmountScreen/ # Выбор карточной суммы +│ │ ├── CardCustomAmountScreen/ # Цифровая клавиатура +│ │ ├── CardTerminalScreen/ # Ожидание банковского терминала +│ │ ├── SuccessScreen/ # Выдача и успех +│ │ └── ErrorScreen/ # Отказ и ошибки +│ └── ui/ +│ ├── OnScreenKeyboard/ # Логика текстовой и цифровой клавиатур +│ ├── StaticBackground/ # Статический фон и слой анимированных спрайтов +│ ├── AdvertisementPlayer/ # Локальное видео и fallback +│ ├── TokenStockStatus/ # Состояние запаса жетонов +│ └── TouchInputGuard/ # Защита от мультитача +└── addons/ # Сторонние плагины +``` + +Сцены, их C#-скрипты и специфичные ресурсы хранятся атомарно в одной тематической папке. + +## Темы и DLC + +В Exchanger нет каталога разработки тем и встроенных `.tres`-тем. Единственная минимальная fallback-тема создаётся кодом, поэтому приложение сохраняет рабочий интерфейс без внешних файлов. При старте `ThemeManager` ищет один `.pck` по пути из пользовательского `appsettings.json`; успешно проверенный DLC полностью заменяет fallback до создания экранов. Manifest v2 предоставляет полные визуальные сцены всех девяти экранов: app-owned C#-контроллеры связываются с ними через metadata `exchanger_binding_id`, не передавая теме бизнес-логику. + +Исходники тем, manifest, фоновые изображения и сцены находятся только в соседнем Godot-проекте `../ExchangerThemeDlcBuilder`: `themes/example/` служит готовым шаблоном, `themes/space-pixel/` — текущей оформленной темой, остальные темы лежат в `themes//`. Основное приложение содержит runtime-контракт имён сцен, binding-resolver и безопасный загрузчик. Для manifest v2 приложение сверяет закреплённый SHA-256 машиночитаемого каталога и проверяет все 481 обязательный биндинг девяти сцен по ID и Godot-типу. Горячего переключения и списка тем нет; после замены `.pck` приложение нужно перезапустить. + +Современная production-сцена темы самодостаточна: её корень содержит metadata `exchanger_self_contained_visuals = true`, собственный `Theme`, прямой `TextureRect` `ThemeBackground` и прямой слой `BackgroundDecoration`. Все девять сцен пакета обязаны использовать один и тот же режим. Для такого пакета глобальные `BackgroundTexturePath` и `BackgroundDecorationPath` оставляют пустыми; приложение отклоняет смешанную или дублирующую визуальную композицию. + +Runtime не переоформляет самодостаточную сцену: он не назначает ей другой `Theme`, type variations, +размеры или theme overrides. Приложение находит готовые элементы по binding-id, подключает события +и обновляет только функциональные значения — текст, видимость, доступность и состояние полей. + +Тематические PCK считаются доверенными. Внутри production-сцен разрешены GDScript, сигналы, +`AnimatedSprite2D`, `AnimationPlayer`, шейдеры, частицы, аудио, видео и другие runtime-возможности +Godot. Формат, binding-id, пользовательские пути и сборка пакета описаны в +[docs/THEME_DLC.md](docs/THEME_DLC.md). + +## Аппаратный слой + +UI не обращается к порту напрямую. `SessionController` работает через типизированный `IMachineController`, а будущий протокольный адаптер будет использовать низкоуровневый `IHardwarePort`; поэтому экраны не зависят от COM-порта, Android USB API или строк wire-протокола. + +Сейчас доступны: + +- `MockHardwarePort` — минимальная служебная заглушка транспорта для UI mock-режима; +- `PeripheryControllerSimulator` — детерминированный wire-симулятор handshake, `INPUT`, платежей и обоих хопперов для интеграционных тестов без COM-порта; +- `MockMachineController` — детерминированно имитирует наличный баланс, карточный результат, бинарный уровень запаса и подтверждение выдачи; +- `SerialPortHardware` — реальный Windows/Linux-транспорт с отдельным worker, очередями и reconnect; +- `PeripheryMachineController` — типизированный адаптер протокола универсального контроллера 2.3.5; +- `UsbSerialHardware` — явно неподдерживаемая Android-заглушка. + +COM-порт использует `System.IO.Ports` 8.0.0 и параметры 115200 8N1/None. Авторизация и платежи реализованы по спецификации 2.3.5. Обфусцированное представление ключа встроено в `PeripheryControllerSecurity` и восстанавливается XOR `0x37`. Целевой режим — `DualHopperAuto`: `309N` обслуживает первый хоппер, `409N` — второй, пакеты ограничены 99 жетонами, а подтверждения `OK/ERROR/CREDIT` принимаются только от активного канала. Шаблон TOML включает оба хоппера, но остаётся безопасным благодаря `use_mock = true`; реальный профиль активируется только техническим специалистом. Команда выдачи автоматически не повторяется. + +В актуальной разводке `IN8` active-low переключает сервисный вход, `IN1` сообщает уровень первого хоппера, `IN4` — второго. Обычная выдача использует `309N` и `409N` и считает только соответствующие кадры `HOPPER1/2 OK`. Сервисный пересчёт запускается отдельно командами `301/300` или `401/400`, считает только `HOPPER1/2 PULSE=1` выбранного канала и завершается после 10 секунд тишины. Физические импульсные входы не участвуют в программном счёте. Общая полоска объединяет точный учёт и бинарные датчики в состояния «нет жетонов», «мало», «достаточно» и «много». + +`IMachineController` также публикует безопасное сервисное состояние соединения. На главном экране штатный статус скрыт в production и виден в debug; авторизация, обрыв или аппаратная ошибка отображаются всегда, но без имени COM-порта, сырых кадров и деталей handshake. При потере связи запас становится `Unknown`, поэтому запуск новой оплаты блокируется. + +## Универсальность оборудования + +Пока целевой ПК и тач-панель отсутствуют, проект не оптимизируется под одну модель устройства. UI проверяется на нескольких портретных разрешениях, параметры оборудования и сценариев выносятся в конфигурацию, а платформенные транспорты остаются за `IHardwarePort`. Фактические DPI, GPU, производительность, системный киоск-режим и работа в перчатках будут проверены на реальном аппарате без изменения границ UI и бизнес-логики. + +## Киоск-режим + +Release-сборка настраивает borderless fullscreen, скрывает курсор и повторно применяет оконный +профиль после потери фокуса либо изменения состава/разрешения дисплеев. Godot не может надёжно +заблокировать Alt+Tab, Ctrl+Alt+Del и системные жесты, поэтому полный киоск дополнительно настраивается +средствами Windows. Скрипты автозапуска/watchdog и безопасная процедура установки находятся в +`tools/windows`; инструкция — [docs/operations/WINDOWS_KIOSK_SETUP.md](docs/operations/WINDOWS_KIOSK_SETUP.md). +Ускоренный и процессный soak описаны в [docs/operations/SOAK_TEST.md](docs/operations/SOAK_TEST.md). + +## Сторонние компоненты + +В проекте подключены: + +- Godot AI; +- GodotX Toast; +- Log.gd; +- Reload Current Scene. + +Эти editor/development addons исключаются из production export; приложение не зависит от них. + +Лицензии сторонних компонентов находятся рядом с ними в `addons/` либо в отдельных сопроводительных файлах, например `godot-ai-LICENSE.txt`. + +## Лицензия проекта + +Собственная лицензия Exchanger в настоящий момент не объявлена. Ошибочный корневой `LICENSE`, автоматически скопированный из GodotX Toast, удалён. Это не затрагивает лицензии сторонних компонентов. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..af03ad4 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,1688 @@ +# Дорожная карта проекта Exchanger + +## 1. Назначение документа + +Этот файл — единая точка отслеживания разработки полноэкранного приложения вендингового аппарата для выдачи жетонов. Он фиксирует текущее состояние, принятые архитектурные решения, порядок реализации, критерии готовности, риски и вопросы, требующие согласования. + +Дата формирования первоначального плана: **2026-08-20**. + +Последняя актуализация состояния: **2026-09-07**. + +## 2. Легенда статусов + +- `[ ]` — задача не начата. +- `[~]` — задача выполняется. +- `[x]` — задача выполнена и проверена. +- `[!]` — задача заблокирована внешней зависимостью или решением. +- `[?]` — требуется уточнение или согласование. + +Правило обновления: задача получает `[x]` только после выполнения указанных для неё проверок и критериев приёмки. При завершении этапа следует добавлять короткую запись в журнал прогресса в конце файла. + +## 3. Цель продукта + +Создать на Godot 4.7 Mono/C# надёжное портретное киоск-приложение для напольного разменника жетонов. Приложение должно: + +1. Показывать интерфейс с единственной встроенной fallback-темой, заменяемой при запуске одним внешним DLC со статическим фоном и отдельными анимированными 2D-спрайтами. +2. Показывать цену жетона, бинарное состояние запаса «много/мало» и бонусные условия. +3. Поддерживать отдельные сценарии оплаты наличными и картой. +4. Безопасно отправлять команду выдачи жетонов через последовательный порт. +5. Дожидаться результата выдачи и показывать успех либо понятную ошибку. +6. Возвращаться в исходное состояние по таймаутам и после завершения сессии. +7. Работать прежде всего на Windows x64 и не связывать UI с конкретной реализацией порта, чтобы в будущем заменить её на Android USB-Serial. +8. Воспроизводить промо-контент на домашнем экране без влияния на основной сценарий. +9. Соответствовать портретному корпусу и пиксельной космической айдентике из подтверждённых референсов. + +## 4. Текущее состояние проекта + +- [x] Создан проект `Exchanger` на Godot 4.7.1 Mono. +- [x] Настроена сборка C# под .NET 8; Android-конфигурация проекта указывает .NET 9. +- [x] Выбран рендерер `mobile` (Vulkan): он нужен runtime-расширению Native Video для MP4/MOV/M4V. +- [x] C#-решение собирается без ошибок и предупреждений. +- [x] Подключены плагины `godot_ai`, `godotx_toast`, `log` и `reload_current_scene`. +- [x] Подключён runtime GDExtension `native_video`: настройки промо принимают OGV/MP4/MOV/M4V, + а export сохраняет его Windows/Linux библиотеки; внешние MP4/MOV/M4V сохраняют исходный путь. + Unicode-пути Windows передаются Native Video напрямую без копий, ссылок и ASCII-псевдонимов. +- [x] Устранён временный кэш player/stream: `Stop()`, `Stream = null`, смена источника и + `QueueFree()` проходят штатно; 50 циклов проверены в реальном `AdvertisementPlayer`. +- [x] Создана атомарная структура `src/core`, `src/scenes`, `src/ui`, `src/hardware` и каталогов ассетов; разработка тем полностью вынесена из репозитория приложения. +- [x] Созданы первые собственные C#-скрипты, ресурсы и сцены. +- [x] Главной сценой назначена `src/scenes/App/App.tscn`. +- [x] Добавлен пользовательский Input Action `kiosk_back`; устаревший `debug_cycle_theme` удалён вместе с переключением тем. +- [x] Корневой `README.md` полностью переписан под Exchanger. +- [x] Ошибочный корневой `LICENSE` от GodotX Toast удалён; лицензии сторонних компонентов сохранены рядом с ними. +- [x] Зафиксировано, что собственная лицензия Exchanger пока не объявлена. +- [x] Проанализированы восемь изображений и видео интерфейса; выводы сохранены в `docs/REFERENCE_ANALYSIS.md`. +- [x] Каталог `references/` исключён из Git через `.gitignore` и отмечен как непроизводственный источник концептов. +- [x] Динамический shader/particle-фон удалён; активная сцена использует `StaticBackground` со статическим цветом/изображением и отдельным слоем анимированных спрайтов. +- [x] Ландшафтный `StartScreen` удалён и заменён портретным `HomeScreen`; логический viewport синхронизирован с theme-preview на 720×1280. +- [x] Инициализирован локальный Git-репозиторий; remote и первый коммит будут настроены отдельным решением владельца проекта. +- [x] Полный runtime переведён на C#/.NET 8, девять атомарных экранов и один внешний + self-contained DLC; `space-pixel` принят по manifest v2 с 481 обязательным биндингом. +- [x] Подтверждён целевой `DualHopperAuto`: первый хоппер использует `30X`, `IN1` и `IN24`, + второй — `40X`, `IN4` и `IN25`, сервисная кнопка — `IN8`. +- [x] Windows x64 release собран как один `Exchanger.exe` со встроенными PCK и .NET outputs; + packaged smoke прошёл на mock и подтвердил авторизацию реального контроллера на COM3. +- [x] Windows export разделён на явные пресеты `Windows x64 Release` и `Windows x64 Debug`; + staging-скрипт жёстко выбирает соответствующий `--export-release` или `--export-debug`. +- [x] Этапы 4 и 5 закрыты: COM-транспорт и полный MVP-сценарий реализованы и покрыты + автоматическими проверками; оставшаяся физическая приёмка вынесена в раздел 4.1. +- [x] В разделе «Сервис» добавлено немедленное скрытие элементов Home: учётного остатка, + theme-owned персонажа справа и целого промо-блока; скрытые панели исключаются из маршрутов питомца. +- [x] Точный учёт жетонов и запрет покупки сверх остатка управляются раздельно: можно продолжать + показывать/списывать остаток, не ограничивая им оплату; отключение учёта скрывает сервисные действия. +- [~] Добавлен и проверен one-file Linux x86_64 export для Debian 13; платформенная валидация + serial-path завершена, udev/dialout и kiosk остаются открытыми. + +### 4.1. Проверки на автомате + +Этот раздел — единая очередь проверок, требующих физического автомата, его панели, контроллера, +платёжной периферии или целевого системного блока. Они не переоткрывают завершённые программные +этапы. Перед каждым аппаратным запуском требуется проверить фактическое подключение и занятость +порта, подготовить автомат и получить отдельное разрешение на конкретную группу тестов. + +#### Интерфейс, панель и производительность + +- [ ] Проверить читаемость с рабочего расстояния и при ярком освещении. +- [ ] Проверить управление пальцем и в перчатках: все девять экранов, прокрутку Settings, + текстовую и цифровую клавиатуры, первое касание и отсутствие действий по hover. +- [ ] Проверить масштабирование сетки 720×1280, ориентацию, калибровку touch и размеры зон + на фактическом разрешении панели. +- [ ] Повторить performance baseline на целевом ПК: FPS, CPU-время, память и draw calls + в fallback и `space-pixel`, в полном и облегчённом режимах. +- [ ] Профилировать одновременную работу анимированных спрайтов DLC и декодера реального MP4/OGV-промо-ролика в Mobile/Vulkan. +- [ ] Проверить отключение/возврат дисплея, потерю фокуса, kiosk/autostart и watchdog. + +#### Контроллер, платежи и хопперы + +- [ ] Повторить безопасную приёмку COM3: framing, AES-handshake, точный `READY!`, `INPUT`, + status-запросы, безопасное исходное состояние и несколько штатных reconnect-циклов. +- [ ] Проверить физическое отключение/возврат USB-COM: UI не зависает, worker не дублируется, + незавершённая выдача не повторяется, позднее подтверждение не завершает новую операцию. +- [ ] Проверить `IN8`/SERVICE, уровни запаса `IN1` и `IN4`, удержание кнопки без повторов и + открытие/закрытие Settings с включённым и выключенным PIN. +- [ ] Проверить монетник и купюроприёмник: включение/отключение каналов, `MONEY:*`, `ASK:*`, + накопление суммы, отмену, таймаут и отсутствие двойного учёта. +- [ ] Проверить безналичную оплату: точное совпадение суммы `163` и `MONEY:CASHLESS`, + `ASK:CASHLESS`, отмену, timeout/decline и keep-alive `161` реже 180 секунд. +- [ ] Проверить обычную выдачу обоих хопперов: `309N`/`409N`, пакеты 1–99, `APPEND=N`, + по одному подтверждению на каждый `HOPPER1/2 OK`, маршрутизацию и раздельное списание остатка. +- [ ] Проверить частичную/ошибочную выдачу: `ERROR` → `CREDIT=N`, запросы `3090/4090`, + отсутствие автоматического retry и единственный итог операции. +- [ ] Проверить сервисный пересчёт обоих хопперов: `301/300` и `401/400`, учёт только + `HOPPER1/2 PULSE=1`, завершение после 10 секунд тишины и безопасную остановку мотора. +- [ ] Проверить три сочетания политики на реальном автомате: учёт с лимитом, учёт без лимита и + полностью выключенный учёт; подтвердить блокировку card/cash до аппаратной команды, работу + бонусов, продолжение списания без лимита, скрытие сервисных действий и пересчёт перед включением. +- [ ] Проверить перезапуск/потерю питания во время операции: запись получает + `UnknownAfterRestart`, оплата и выдача автоматически не повторяются. + +#### Длительная и установочная приёмка + +- [ ] Выполнить непрерывный 24-часовой soak с повторными сессиями, оплатой, выдачей, + SERVICE, автосохранением, ротацией логов и периодическим отключением/возвратом дисплея. +- [ ] Провести чистую установку Windows-релиза на целевом устройстве; проверить доверие подписи, + конфигурацию, внешний DLC, автозапуск, обновление и откат. +- [ ] После программной Linux-адаптации запустить ELF на Debian 13 и принять графику, touch, + внешний DLC, USB-UART, udev/dialout, kiosk/autostart и watchdog. + Предварительное обнаружение выполнено: Debian распознал Silicon Labs CP2102 `10c4:ea60` + штатным `cp210x` и создал `/dev/ttyUSB0`; права и обмен с Exchanger ещё не проверялись. +- [ ] Если будет выбран Android-порт, провести на целевом ARM64-устройстве export/runtime, + USB permission/reconnect, Mobile renderer, touch, системные жесты, поворот, + энергосбережение и полный регрессионный сценарий. + +## 5. Зафиксированные архитектурные решения + +### 5.1. Рендерер + +Использовать **Mobile renderer (Vulkan)** как базовый режим. Это обязательное требование +runtime-расширения Native Video для MP4/MOV/M4V; оно совместимо с 2D-пиксельным UI и целевой +Windows/Linux конфигурацией. Compatibility нельзя включать, пока требуется Native Video. Для +слабого GPU остаётся `ReducedEffects`; производительность и аппаратное декодирование должны быть +приняты на целевом железе в разделе 4.1. + +### 5.2. Слои приложения + +```text +Пользовательский интерфейс и экраны + ↓ +Контроллер сессии и конечный автомат операции + ↓ +Сервис протокола контроллера + ↓ +IHardwarePort + ↙ ↘ +MockHardwarePort SerialPortHardware + ↘ + UsbSerialHardware (stub) +``` + +UI не должен знать о `SerialPort`, потоках и формате строк протокола. Он реагирует на типизированные состояния и события контроллера сессии. + +### 5.3. Состояния пользовательской сессии + +```text +Home + ├→ CashAccepting + │ → Dispensing + │ → Completed + └→ CardAmountSelection + → CardCustomAmount (опционально) + → CardTerminalWait + → Dispensing + → Completed + → Home + +Любое активное состояние + → PaymentDeclined, Error или Cancelled + → Home +``` + +Переход в `Completed` разрешён только после подтверждения выдачи контроллером. Сам факт отправки `DISPENSE` не считается успешной выдачей. + +### 5.4. Сцены и глобальные сервисы + +- Главная сцена: `src/scenes/App/App.tscn`. +- `App` создаёт два `CanvasLayer`: фон с `layer = 0` и UI с `layer = 1`. +- Экраны — отдельные атомарные сцены `Control` со своим C#-скриптом и локальными ресурсами. +- `ThemeManager` и `ScreenManager` регистрируются как Autoload, как требует ТЗ. +- `SessionController`, адаптер протокола и аппаратный сервис принадлежат главной сцене или отдельному композиционному узлу приложения; их не следует без необходимости превращать в глобальные Singleton. +- `ScreenManager` переключает сцены экранов и не содержит бизнес-логику оплаты или выдачи. +- `SessionController` является единственным владельцем состояния текущей операции. +- `HomeScreen` сразу показывает цену, запас, способы оплаты, промо-fallback и контакты поддержки. +- Платёжные сцены разделяются по назначению: `CashPaymentScreen`, `CardAmountScreen`, `CardCustomAmountScreen` и `CardTerminalScreen`. +- `AdvertisementPlayer` является пассивным UI-компонентом домашнего экрана и останавливает декодирование, когда экран скрыт. + +### 5.5. Формат темы + +В Exchanger существует одна программная fallback-тема. Разрабатываемые темы полностью вынесены в соседний `ExchangerThemeDlcBuilder` и подключаются только как один внешний Godot `.pck`. После загрузки runtime-представление `VendingThemeDefinition` содержит: + +- стабильный идентификатор и отображаемое имя темы; +- `Theme` для Control-интерфейса; +- необязательную статическую `Texture2D` фона; +- необязательные `PackedScene` фоновых слоёв/декораций и именованных пассивных визуальных слотов экранов; +- для manifest v2 — полный набор из девяти пассивных визуальных сцен экранов с каноническими + именами и metadata binding-id; +- fallback-цвет; облегчённый режим хранится в конфигурации приложения. + +Сам фон всегда статичен: `ColorRect` с fallback-цветом и, при наличии, неподвижный `TextureRect`. Анимированные спрайты темы добавляются отдельной `PackedScene`; такая сцена может содержать `AnimatedSprite2D` и `AnimationPlayer`, но обязана быть пассивной декорацией и не зависеть от экранов приложения. Фоновые шейдеры, частицы и видео не используются. Промо-ролик допускается только внутри отдельного UI-блока `AdvertisementPlayer` на `HomeScreen`. + +Полносценовая тема не содержит бизнес-логику: приложение инстанцирует собственные C#-контроллеры, +до `_Ready` заменяет встроенный визуальный корень сценой DLC и разрешает кнопки, поля и динамические +области через стабильную metadata `exchanger_binding_id`. Вложенность узлов темы свободна. Manifest +v1 сохраняет обратную совместимость как стилевой пакет; v2 требует все девять сцен целиком и +точную копию каталога из 481 обязательного биндинга. Host закрепляет SHA-256 каталога и до +активации отклоняет неверные пути, root-имена, неизвестные или неверно типизированные binding-id +и дубли. Отсутствующий обязательный binding восстанавливается по каноническому `FallbackPath` +узлом старой сцены либо готовым элементом встроенной темы-заглушки. + +В основном проекте нет каталога `themes/` и исходных ресурсов тем. Путь к единственному внешнему DLC берётся из пользовательского `appsettings.json`; пакет имеет версионированный manifest, изолированное пространство `res://exchanger_theme_dlc/`, монтируется без замены ресурсов приложения и требует перезапуска для обновления. + +### 5.6. Потоки и последовательный порт + +- Только реализация `SerialPortHardware` работает с `System.IO.Ports`. +- Чтение выполняется в отдельном потоке с корректной отменой и освобождением ресурсов. +- Фоновый поток не вызывает API Godot и не обращается к Node/Resource/UI. +- Принятые строки и изменения соединения передаются в поток Godot через `ConcurrentQueue` либо `CallDeferred`. +- Разбор строк протокола выполняется отдельно от транспорта и покрывается тестами. +- Повтор команды выдачи после неизвестного результата запрещён без идемпотентного идентификатора операции или явного подтверждения, что первая команда не была принята. + +### 5.7. Конфигурация + +- Встроенные безопасные значения: `res://config/default_settings.json`. +- Пользовательские настройки: `user://config/appsettings.json`. +- При первом запуске создаётся пользовательский файл на основе значений по умолчанию. +- Ошибочный файл не должен ломать запуск: ошибка логируется, применяются безопасные значения по умолчанию. +- Планируемые параметры: порт, baud rate, таймауты, путь и разрешение внешнего DLC темы, режим имитации оборудования, уровень эффектов, общая громкость и громкость промо-ролика, mute, параметры логирования, цена жетона, карточные суммы, бонусные правила, бинарное mock-состояние запаса, способы оплаты, телефон поддержки и плейлист промо-роликов. +- Секреты платёжного терминала в конфигурации приложения не хранятся; платёжная интеграция находится на стороне внешнего контроллера. + +### 5.8. Критические эксплуатационные ограничения + +- Godot может включить borderless fullscreen и перехватывать обычные действия приложения, но не может надёжно запретить Alt+Tab, Ctrl+Alt+Del или системные жесты Windows. Полная блокировка обеспечивается Windows Assigned Access/Shell Launcher, политиками ОС и учётной записью киоска. +- Тач-ввод принимает только первое касание (`Index == 0`). Дополнительные касания игнорируются централизованно. +- Минимальная интерактивная область — 64×64 px, основной текст — не меньше 24–32 px на целевом разрешении. +- В интерфейсе нет функций, доступных только по hover. +- Целевой UI проектируется в портретном 9:16 с нативным viewport 720×1280; панели большего разрешения используют масштабирование `canvas_items/expand`. + +### 5.9. Требования из визуальных референсов + +- Корпус — высокий напольный автомат с зелёной рамой, портретным экраном, физическими приёмниками справа и лотком выдачи ниже экрана. +- Основной стиль — пиксельная космическая тема: тёмно-синий фон, салатовые акценты, белые панели, НЛО и зелёный маскот. +- Домашний экран сразу показывает цену жетона, остаток, выбор наличной/карточной оплаты, действие выдачи, промо-ролик и контакты поддержки. +- Наличная оплата отображает накопленный баланс и инструкции для купюро- и монетоприёмника. +- Карточная оплата содержит пресеты сумм, ввод другой суммы, ожидание терминала и отдельный результат. +- Бонусные жетоны рассчитываются конфигурируемыми правилами, а не зашиваются в UI. +- Референсные файлы не являются production-ассетами; права, финальные исходники, тарифы и бренд требуют подтверждения. + +## 6. Целевая структура каталогов + +```text +res:// +├── config/ +│ └── default_settings.json +├── src/ +│ ├── core/ +│ │ ├── Configuration/ +│ │ ├── Logging/ +│ │ ├── ThemeManager/ +│ │ ├── Navigation/ +│ │ └── Session/ +│ ├── hardware/ +│ │ ├── Abstractions/ +│ │ ├── MockHardware/ +│ │ ├── SerialPortHardware/ +│ │ ├── UsbSerialHardware/ +│ │ └── ControllerProtocol/ +│ ├── scenes/ +│ │ ├── App/ +│ │ ├── HomeScreen/ +│ │ ├── CashPaymentScreen/ +│ │ ├── CardAmountScreen/ +│ │ ├── CardCustomAmountScreen/ +│ │ ├── CardTerminalScreen/ +│ │ ├── SuccessScreen/ +│ │ └── ErrorScreen/ +│ ├── ui/ +│ │ ├── StaticBackground/ +│ │ ├── AdvertisementPlayer/ +│ │ ├── TokenStockStatus/ +│ │ └── TouchInputGuard/ +│ └── vfx/ +│ └── SuccessEffect/ +└── tests/ + ├── Unit/ + ├── Integration/ + └── Fixtures/ +``` + +Структура уточняется по мере реализации, но сохраняется правило атомарности: сцена, скрипт и специфичные ресурсы элемента лежат в одной тематической папке. + +## 7. План реализации + +### Этап 0. Базовые решения и гигиена репозитория — завершён + +Цель: получить однозначную техническую основу до реализации UI и оборудования. + +- [x] Зафиксировать продуктовые требования в `ROADMAP.md`. +- [x] Зафиксировать исходный Compatibility renderer как исторический baseline. +- [x] Обновить корневой `README.md`: назначение, требования, запуск, структура, конфигурация и состояние проекта. +- [x] Удалить ошибочную корневую лицензию GodotX Toast, сохранив лицензии сторонних аддонов; собственную лицензию пока не объявлять. +- [x] Инициализировать локальный Git-репозиторий; подключение remote и первый коммит оставить отдельным решением владельца. +- [x] Решить хранение проектных инструкций: `.agents/AGENTS.md` версионируется и не исключается через `.gitignore`. +- [x] Добавить файл архитектурных решений `docs/architecture/decisions.md`. +- [x] Зафиксировать границу протокола: до появления документации wire-формат и команды не выдумываются; документация является входом Этапа 3, реальный COM — Этапа 4. +- [x] Принять универсальную аппаратную стратегию: не привязывать UI, конфигурацию и бизнес-логику к отсутствующему целевому ПК/GPU/тач-контроллеру. +- [x] Отложить выбор модели контроллера и проверку реального COM-обмена до добавления владельцем списка команд и документации в `references/`. +- [x] Зафиксировать контроллер единственным источником сведений об оплате, запасе, приёмниках, выдаче и аппаратных ошибках; конкретные сообщения определит будущая документация. + +Критерий выхода выполнен: стабильны платформонезависимая граница `IHardwarePort`, универсальные требования к UI и правило не проектировать неизвестный протокол. Аппаратно-зависимые детали оформлены как входные данные Этапов 3–4 и не блокируют UI, mock-сценарии и бизнес-логику ранних этапов. + +### Этап 1. Первый вертикальный срез: запуск, тема и стартовый экран — завершён + +Цель: получить запускаемое полноэкранное приложение с первой темой и безопасной заглушкой оборудования. + +#### 1.1. Настройки приложения + +- [x] Установить базовый viewport 1920×1080 и режим растяжения `canvas_items/expand`. +- [x] Включить borderless fullscreen для production-профиля. +- [x] Предусмотреть удобный оконный debug-режим через конфигурацию или аргумент запуска. +- [x] Сохранить исходный Compatibility renderer как исторический baseline. +- [x] Настроить ограничение/целевую частоту 60 FPS и поведение при потере фокуса. +- [x] Добавить главную сцену `App` и назначить её в `application/run/main_scene`. +- [x] Проверить запуск на 1920×1080 и другом соотношении сторон: 1024×768, а также fullscreen 2560×1440. + +#### 1.2. Конфигурация и логирование + +- [x] Реализовать типизированную модель `AppSettings` с валидацией диапазонов. +- [x] Реализовать загрузку defaults → пользовательский JSON → аргументы запуска. +- [x] Добавить безопасное восстановление после битого/неполного JSON. +- [x] Реализовать журнал ключевых событий с временными метками и категориями. +- [x] Добавить ротацию/ограничение размера файлов в `user://logs`. +- [x] Не записывать в лог платёжные секреты и лишние персональные данные. + +#### 1.3. Тема, статический фон и анимированные спрайты + +- [x] Создать `VendingThemeDefinition`. +- [x] Создать базовый UI Theme со шрифтами, размерами, отступами и состояниями кнопок. +- [x] Создать первую тему `cosmic`. +- [x] Реализовать `ThemeManager` Autoload; первоначальный реестр позднее заменён моделью fallback + один DLC. +- [x] Исключить жёсткие пути к теме из экранов. +- [x] Применять одну активную тему ко всем экранам; горячая смена позднее удалена в пользу замены DLC при перезапуске. +- [x] Создать `StaticBackground`: обязательный `ColorRect` и необязательный статический `TextureRect`. +- [x] Передавать fallback-цвет и статическую текстуру из определения темы. +- [x] Поддержать отдельную тематическую сцену анимированных 2D-спрайтов через `PackedScene`. +- [x] Отключать необязательные анимированные спрайты в облегчённом режиме, сохраняя статический фон. +- [x] Удалить из активной темы фоновые шейдеры и частицы как не соответствующие референсам. + +#### 1.4. StartScreen и аппаратная заглушка + +- [x] Создать атомарную сцену `StartScreen` с логотипом и кнопкой «Начать». +- [x] Обеспечить области касания не меньше 64×64 px и читаемый текст. +- [x] Временная debug-кнопка смены темы была реализована для прототипа и позднее полностью удалена. +- [x] Создать `IHardwarePort` без зависимости от Godot UI. +- [x] Создать `MockHardwarePort`, который логирует команды и воспроизводит ответы по сценарию. +- [x] Создать `UsbSerialHardware` как явно неподдерживаемый Android stub. +- [x] Создать каркас `SerialPortHardware`, не открывая реальный порт при старте сцены. +- [x] Проверить наличие `System.IO.Ports`: сборка отсутствует в установленных reference/shared packs .NET. +- [x] Получено разрешение устанавливать необходимые NuGet-пакеты; `System.IO.Ports` будет добавлен только при фактическом начале Этапа 4. + +Критерии приёмки этапа: + +- приложение запускается в главную сцену без ошибок; +- стартовый экран корректен в fullscreen и debug-window режимах; +- единая активная тема применяется к UI и фону; позднее источником стал fallback либо один внешний DLC при запуске; +- fallback-фон включается настройкой; +- mock получает тестовую команду, а UI не зависит от конкретного транспорта; +- повторная C#-сборка и запуск из Godot проходят без ошибок. + +### Этап 2. Портретный интерфейс, навигация и жизненный цикл сессии — завершён + +Цель: перестроить технический прототип под портретный аппарат из референсов и реализовать детерминированные переходы без реального оборудования. + +- [x] Перевести viewport и debug-window в портретный режим; после сверки с theme-preview закрепить нативную сетку 720×1280. +- [x] Реализовать `ScreenManager` Autoload и контейнер экранов в `App`. +- [x] Загружать экраны через централизованный `ScreenRegistry`, а не из разрозненных жёстких путей. +- [x] Сохранить общий статический фон между экранами и добавить короткие fade-переходы только для UI. +- [x] Блокировать ввод на время перехода полноэкранным `TransitionInputBlocker`; устранить перенос отпускания тача на новый экран. +- [x] Заменить `StartScreen` на `HomeScreen` с ценой, запасом, двумя способами оплаты, промо-fallback и контактами поддержки. +- [x] Создать `CashPaymentScreen` с балансом, расчётом жетонов/бонуса и инструкциями физических приёмников. +- [x] Создать `CardAmountScreen` с конфигурируемыми пресетами сумм. +- [x] Создать `CardCustomAmountScreen` с цифровой клавиатурой, ограничениями и подтверждением. +- [x] Создать `CardTerminalScreen` с ожиданием, отменой и обратным отсчётом. +- [x] Создать `SuccessScreen` с режимами `Dispensing` и `Completed`. +- [x] Создать `ErrorScreen` с отдельными визуальными состояниями отказа оплаты, связи, запаса и выдачи. +- [x] Реализовать `AdvertisementPlayer` с локальным видео, циклом, fallback-постером и остановкой на скрытых экранах. +- [x] Добавить модели `PricingSettings`, `BonusRule`, `PaymentPreset`, `BrandingSettings` и `AdvertisementSettings`. +- [x] Добавить компонент `TokenStockStatus` только с состояниями `Enough/Low/Unknown`, без числового остатка и `Empty`. +- [x] Реализовать `SessionController` и явные состояния сессии. +- [x] Реализовать общий таймаут бездействия 30–60 секунд для платёжных экранов. +- [x] Реализовать отдельный таймаут карточного терминала 120 секунд. +- [x] Реализовать возврат после успеха через 10 секунд. +- [x] Сбрасывать выбранную сумму/способ оплаты, таймеры и временные данные при возврате в `Home`. +- [x] Централизованно фильтровать мультитач и принимать только первое касание. +- [x] Защитить навигацию, платёжные действия и выдачу от повторного тапа, переноса отпускания и повторной команды. +- [x] Восстанавливать безопасный HomeScreen после неизвестного состояния сессии. + +Критерии приёмки этапа: + +- весь сценарий проходится на mock без реального COM-порта; +- назад, отмена и каждый таймаут приводят к определённому состоянию; +- быстрые повторные касания не создают две сессии и не дублируют выдачу; +- все экраны используют текущую тему и не владеют бизнес-логикой. +- портретный UI соответствует композиции референса, нативно рендерится в 720×1280 и масштабируется на панели 9:16; +- промо-ролик не продолжает декодироваться вне HomeScreen и имеет рабочий fallback. + +### Этап 3. Протокол контроллера и симулятор оборудования — завершён + +Цель: отделить строковый протокол от транспорта и проверить все ветки сценария. + +Условие входа выполнено: владелец проекта добавил в `references/` документацию контроллера 2.3.5 и список команд. Этап закрывает документированный wire-профиль и безопасное поведение для отсутствующих форматов. Production-команда силового канала, физические номера входов и проверка AES на плате относятся к последующей аппаратной интеграции и не подменяются предположениями. + +- [x] Изучить спецификацию универсального контроллера 2.3.5 и описать поддерживаемую часть в `docs/hardware/PERIPHERY_CONTROLLER_2_3_5.md`. +- [x] Реализовать ASCII-фрейминг по `CR`/`LF` с лимитом буфера, минимальной длиной и timeout 100 мс. +- [x] Реализовать типизированные команды авторизации, оплаты, отмены, status-запросов и legacy-хоппера; отсутствующий production-профиль силового канала представлен явным безопасным `Unsupported`. +- [x] Реализовать типизированные ответы startup-баннера `periphery controller ver_`, `CHAL`, `RAES`, `AUTH_PC_OK`, `AUTH_CNT_OK`, точного `READY!`, `MONEY:*`, `HOPPER1 APPEND/OK/ERROR/CREDIT/PULSE`, совместимые ответы второго хоппера, `SERVICE`, `INPUT` и обобщённые ошибки; недокументированные status/heartbeat-ответы безопасно классифицируются как неизвестные. +- [x] Привязать подтверждённые входы новой прошивки: active-low `IN8` публикует сервисный запрос по одному фронту, `IN1` задаёт бинарный запас первого хоппера, `IN4` — второго. `IN24` сохранён как физический датчик первого канала, но runtime считает подтверждения строками платы; оба канала `30X/40X` включены и остаются конфигурируемыми. +- [x] Добавить бинарное состояние запаса `Enough/Low` из реального `INPUT` (вариант с пробелом тоже принимается) без вымышленного точного количества; до первого снимка либо при отключённом входе используется `Unknown`. +- [x] Добавить события принятой наличной суммы и обязательные подтверждения `ASK:COINS/BILL`. +- [x] Добавить запуск/отмену Вендиста, keep-alive и `Approved` по `MONEY:CASHLESS`; несовпадение суммы даёт `Declined`, а `Cancelled/Timeout` воспроизводятся доменным mock и таймером сессии, поскольку отдельных wire-сообщений в спецификации нет. +- [x] Связать действия с аппаратными последовательностями: наличные `162 → 141 → 151`, остановка + наличных `142 → 152`, подтверждение карточной суммы `142 → 152 → 161 → 163`, + отмена/таймаут карты `162`; повторная отмена не засоряет FIFO одинаковыми командами. +- [x] Обработать частичные строки, несколько сообщений в одном чтении, timeout, переполнение, не-ASCII и неизвестные кадры. +- [x] Добавить доменную таблицу типизированных ошибок и безопасных текстов; документированные hopper/transport/controller ошибки сопоставлены, неизвестные коды сворачиваются в безопасный `Unavailable` без утечки сырого кадра. +- [x] Сырые строки оборудования и внутренние исключения не передаются в пользовательский интерфейс. +- [x] Mock покрывает успех, отказ, отмену, таймаут, disconnect, полную/частичную ошибку и задержку; `PeripheryControllerSimulator` дополнительно прогоняет настоящий handshake/parser, malformed-кадр, оплату, датчик и legacy-выдачу без COM-порта. +- [x] Добавлен debug-only режим ручной эмуляции оплаты, потери связи и ошибок выдачи. +- [x] Зафиксировать at-most-once-политику выдачи: адаптер подавляет повторную команду и не выполняет retry после обрыва или ошибки; новая явная операция разрешена без перезапуска приложения. +- [x] Для обоих хопперов отправлять пакеты `309N`/`409N` без разделителя (1–99 жетонов), считать `APPEND=N` подтверждением очереди и ждать N соответствующих кадров `OK`; после `ERROR` дождаться `CREDIT=N` активного канала и вернуть частичный результат. Большие выдачи разбиваются и маршрутизируются по раздельным учётным остаткам; `3090/4090` запрашивают остаток кредита. + +Критерий выхода выполнен: все ветви конечного автомата воспроизводимы детерминированно без физического аппарата, parser/authenticator/simulator не зависят от Godot Node, а unsupported-возможности не активируются по предположениям. + +### Этап 4. Реальный Windows COM-порт — завершён + +Цель: подключить аппаратный транспорт без нарушения потоковой безопасности Godot. + +- [x] Реализовать открытие/закрытие `SerialPort` с port name и параметрами протокола 115200 8N1/None. +- [x] Реализовать отдельный worker-поток чтения/записи и механизм отмены. +- [x] Реализовать потокобезопасные очереди входящих событий и исходящих команд. +- [x] Публиковать события соединения и кадры только в главном потоке Godot через `ProcessPendingEvents()`. +- [x] Реализовать последовательную очередь отправки команд с окончанием `CRLF`. +- [x] Добавить read/write timeout и периодическую попытку повторного открытия порта с конфигурируемым интервалом. +- [x] Не выполнять автоматический повтор выдачи, если результат первой команды неизвестен. +- [x] Корректно отменять worker, закрывать и освобождать порт при выходе/перезапуске. +- [x] Программно обрабатывать исчезновение USB-COM и повторное открытие устройства; логика и + 200 циклов симуляции проверены, физическая приёмка кабеля вынесена в раздел 4.1. +- [x] Не журналировать сырые кадры и секрет handshake; неизвестные/developer-кадры логируются только по категории. +- [x] Добавить атомарный сервисный индикатор `Disconnected/Authenticating/Ready/Faulted`: в production штатный `Ready` скрыт, а обрыв и ошибка видимы без раскрытия COM-порта и протокольных данных. +- [x] Провести автоматический стресс-тест 200 последовательных переподключений с обрывом во время выдачи; команда не повторяется, отложенное подтверждение не принимается, переходы состояния не накапливаются. +- [x] Подготовить отдельный аппаратный NUnit-набор для платы: safe handshake/status/input/reconnect, ручные SERVICE/cash/sensor, отдельно подтверждаемые real payment, hopper и USB-cable сценарии с TRX-отчётом. +Критерии приёмки этапа: + +- ни один фоновый поток не обращается к Godot API; +- отключение кабеля не замораживает UI; +- реконнект не создаёт лишних потоков и подписок; +- выдача не дублируется после таймаута или обрыва связи; +- приложение корректно закрывает порт. + +Этап завершён: транспорт, потоки, reconnect, at-most-once и безопасное освобождение порта +реализованы и проверены автоматически; ранее COM3/framing/AES-handshake, `INPUT`, безопасные +status-запросы и три reconnect-цикла подтверждены на плате. Полная физическая приёмка автомата +ведётся отдельно по разделу 4.1 и не является незавершённой программной задачей этапа. + +### Этап 5. Полный MVP-сценарий автомата — завершён + +Цель: интегрировать оплату, выдачу, обратную связь и пользовательские состояния. + +- [x] При выборе способа оплаты создавать уникальный локальный контекст операции и запись в журнале. +- [x] Реализовать расчёт жетонов по цене и бонусным правилам для наличной и карточной веток. +- [x] Блокировать начало оплаты при `Unknown`; разрешать при `Enough` и `Low`, не имитируя проверку несуществующего точного остатка. +- [x] Для наличной ветки обновлять баланс по типизированным событиям и явно определять момент начала выдачи. +- [x] Для карточной ветки передавать выбранную сумму аппаратной границе и различать Approved/Declined/Cancelled/Timeout. +- [x] На экране ожидания терминала разделить действия: верхняя кнопка «Назад» отменяет + активный безналичный запрос и возвращает к выбору суммы, красная «ОТМЕНА» завершает сессию. +- [x] Перейти в ожидание оплаты и принять только релевантный сигнал текущего состояния. +- [x] Игнорировать просроченное подтверждение от предыдущей mock-сессии. +- [x] После подтверждения оплаты один раз сформировать команду выдачи. +- [x] Поддержать крупные тарифы: общее количество выдаётся последовательными пакетами `309N`, следующий пакет отправляется после N кадров `HOPPER1 OK` предыдущего. +- [x] Показывать состояние «Идёт выдача», не преждевременный успех. +- [x] Обновлять прогресс/счётчик по каждому подтверждённому контроллером импульсу выдачи. +- [x] Показывать «Получите жетоны» только после подтверждения завершения. +- [x] Сопоставить ошибки с типизированными безопасными действиями `ReturnHome`/`TryAnotherPaymentMethod`/`ContactSupport`. +- [x] Не показывать действие «Повторить» после ошибок: экран ошибки разрешает только возврат + домой, смену способа оплаты либо обращение в поддержку и никогда не повторяет выдачу. +- [x] Логировать начало и единственный итог с локальным `OperationId` без платёжных секретов; + отсутствующий в протоколе transaction ID не эмулируется и не используется для небезопасной сверки. +- [x] Выполнить автоматический сброс после успеха и управляемый сброс после ошибки. +- [x] При старте закрывать незавершённые локальные записи как `UnknownAfterRestart` без + автоматического retry; при отсутствии документированного запроса статуса операция не повторяется. + +Критерий готовности MVP выполнен программно: полный сценарий от `Home` до подтверждённой выдачи +проходит через типизированный mock и детерминированный wire-симулятор, а известные ошибки +завершаются безопасным и понятным состоянием. Сквозная физическая проверка на автомате вынесена +в раздел 4.1. + +### Этап 6. Киоск-режим, настройки и эксплуатационная надёжность — завершён + +Цель: подготовить приложение к работе без постоянного оператора и дать авторизованному сервисному +персоналу безопасный способ изменять эксплуатационные параметры без ручного редактирования JSON. + +- [x] Настроить borderless fullscreen и скрытие курсора в production. +- [x] Подготовить инструкцию Windows kiosk/shell setup для блокировки системных действий. +- [x] Добавить автоматический запуск приложения после входа/загрузки Windows. +- [x] Добавить watchdog/перезапуск процесса средствами ОС. +- [x] Добавить обработку потери фокуса, смены разрешения и состава дисплеев. +- [x] Не позволять пользовательскому вводу открывать debug/service функции: `F10` работает только + в debug-сборке из `Home`, production-вход начинается только с аппаратного `SERVICE`. +- [x] Реализовать защищённый PIN-вход в сервисный режим с лимитом попыток и временной блокировкой; + единый PIN включается и впервые задаётся внутри приложения, в конфигурации хранится только PBKDF2-хеш с солью. +- [x] Исключить из настроек владельца версию, тему/DLC, порт и контроллер, окно/FPS, диагностику, + журналы и тестовую выдачу; технические параметры оставить только в deployment-конфигурации. + +#### 6.1. Редактор настроек программы + +- [x] Провести инвентаризацию `AppSettings` и разделить параметры на операторские, инженерные, + debug-only и секретные; AES-ключ, платёжные секреты и сырые команды контроллера никогда не + показывать и не сохранять через UI. +- [x] Ввести единый `SettingsService`/репозиторий конфигурации: экраны работают с валидированной + рабочей копией и неизменяемым активным снимком, а не записывают JSON напрямую. +- [x] Создать атомарный экран настроек владельца внутри защищённого режима с пятью разделами: + «Общие», «Звук», «Промо», «Тарифы» и «Оплата». +- [x] Добавить общую громкость 0–100%, mute и отдельную громкость промо-ролика; применять + значения через выделенные Godot audio buses и сохранять их в пользовательской конфигурации. +- [x] Добавить безопасную кнопку проверки звука, которая не запускает оплату, выдачу или + полноразмерный промо-ролик. +- [x] Сделать редактируемой стоимость одного жетона `TokenPriceRubles`; показывать рядом + предварительный расчёт количества жетонов для типовых сумм и запрещать нулевое/отрицательное + значение. +- [x] Реализовать редактор дополнительных жетонов `BonusRules`: строки «минимальная сумма → + бонусные жетоны», добавление, удаление и изменение правил, сортировка порогов, запрет дублей и + отрицательных значений. +- [x] Явно зафиксировать в UI семантику бонусов: применяется одно максимальное подходящее правило, + бонусы разных строк не суммируются; до сохранения показывать итог «базовые + бонусные» для + контрольных сумм. +- [x] Реализовать настройку карточных пресетов: добавление/удаление сумм, сортировка, отсутствие + дублей, максимальная сумма и шаг ручного ввода; валидировать суммы относительно цены жетона и + правил `PricingPolicy`. +- [x] Добавить отдельное включение/отключение наличной и карточной оплаты; не позволять сохранить + конфигурацию, в которой отключены оба пользовательских способа оплаты. +- [x] Сделать настраиваемыми пользовательские таймауты бездействия, ожидания оплаты и показа + результата в безопасных пределах; рядом объяснить влияние каждого параметра. +- [x] Добавить редактирование названия автомата, подзаголовка и телефона поддержки с ограничениями + длины и preview итогового текста. +- [x] Добавить настройки промо: включение, список промо-роликов, poster, fallback-текст, mute и + громкость; проверять существование и допустимость локальных путей до сохранения. +- [x] Добавить экранный ввод для настроек: RU/EN/спецсимволы для текстовых полей, отдельную + цифровую клавиатуру для `SpinBox`, Shift, каретку, удаление/очистку и кнопку скрытия справа + сверху; автоматически поднимать активное поле над клавиатурой и применять число при выходе. +- [x] Оставить путь к внешнему DLC, `ReducedEffects`, журналирование, параметры окна, mock-режим, + COM-порт и соединение только в deployment-конфигурации, полностью исключив их из UI владельца. +- [x] Выделить аппаратную deployment-конфигурацию в отдельный + `user://config/technical_settings.toml`: основной порт, безопасные параметры связи, наличие + обоих хопперов, их входы/полярности и сервисная кнопка валидируются целиком и применяются только + после перезапуска; при повреждении пользовательского файла используется встроенный mock-профиль. +- [x] Не давать изменять тарифы, бонусы, способы оплаты, тему и аппаратные параметры во время + активной операции; открытая сессия всегда завершается со снимком настроек, с которыми началась. +- [x] Реализовать валидируемое автосохранение с debounce 0,5 с: промежуточный некорректный ввод + не записывается, ошибки остаются рядом с полями, а повторный фронт `IN8` сохраняет ожидающие + допустимые изменения и закрывает настройки. Экранная кнопка «Сохранить и выйти» в неподвижном + нижнем футере использует тот же безопасный путь завершения редактирования. +- [x] Сохранять `appsettings.json` атомарно через временный файл и замену, перед изменением держать + последнюю корректную резервную копию и автоматически восстанавливаться после повреждения. +- [x] Валидировать весь набор настроек до записи и показывать ошибки рядом с конкретным полем; + частичное применение некорректной конфигурации запрещено. +- [x] Разделить параметры на применяемые немедленно и требующие перезапуска; после автосохранения + показывать понятный статус и не выполнять самопроизвольный restart во время операции. +- [x] Добавить безопасный журнал изменения конфигурации: дата/время, роль, раздел и факт изменения без + старого/нового секретного значения, полного пути, платёжных данных и сырых кадров контроллера. +- [x] Покрыть нормализацию, граничные значения, round-trip JSON, миграцию версии, резервную копию, + бонусные правила и запрет изменения активной операции unit/integration-тестами. +- [x] Провести runtime-проверку редактора владельца на 1080×1920 и 720×1280: пять доступных вкладок, + отсутствие технических панелей, тач-действия, PIN-клавиатура и длинные/некорректные значения; + собственные текстовая и цифровая клавиатуры проверяются в fallback и внешней теме, а работа + пальцем и в перчатках остаётся физической приёмкой Этапа 8. + +Критерий готовности настроек: владелец может безопасно изменить звук, цену жетона, бонусы, +карточные суммы, доступность способов оплаты, таймауты, поддержку и промо; после +перезапуска значения сохраняются, повреждённый файл восстанавливается, а начатая операция никогда +не меняет тарифы или аппаратную конфигурацию посередине сценария. + +#### 6.2. Эксплуатационная надёжность + +- [x] Добавить очистку/ротацию старых логов и ограничение объёма `user://`. +- [x] Проверить восстановление после повреждения конфигурации, обрыва питания во время записи и + несовместимой версии файла без потери последней корректной резервной копии. +- [x] Добавить ускоренную модель 24 часов (1440 минут, 480 выдач), стресс 10 000 жизненных циклов + `SessionFlow` и процессный runner для 24-часового прогона; runner проверен минутным прогоном + 12/12 сэмплов, пик working set 217.73 МБ. Реальный 24-часовой прогон переносится в физическую + приёмку Этапа 8, поскольку целевой ПК пока отсутствует. + +### Этап 7. Производительность, UX и доступность — выполняется + +Цель: обеспечить стабильные 60 FPS и понятный интерфейс на целевом оборудовании. + +- [x] Локальный baseline FPS, CPU-времени, памяти и draw calls зафиксирован + (`docs/operations/PERFORMANCE_BASELINE.md`); повтор на автомате вынесен в раздел 4.1. +- [x] Проверить статический fallback-фон и актуальный `space-pixel` в полном/облегчённом режимах: + decoration переключается `1 → 0 → 1`, сохраняются 60 FPS, draw calls снижаются с 26 до 24. +- [x] Перевести production-темы на доверенный runtime: разрешить theme-owned GDScript и стандартные + Godot-узлы без прежнего decoration budget, лимитов узлов/кадров/FPS/скорости или размера PCK; + сохранить строгую проверку namespace, manifest, экранов, биндингов и запрет подмены ресурсов host. +- [x] Отключать обработку всех скрытых экранов через `ProcessMode.Disabled` и включать её только + для текущего экрана; переход Home → Settings проверен в runtime. +- [x] Добавить явную прокрутку Settings перетаскиванием одним пальцем и зажатой ЛКМ; + обработчик использует deadzone 12 px, не перехватывает короткое нажатие и не зависит от того, + передал ли вложенный Control drag штатному ScrollContainer. Физическая приёмка остаётся в 4.1. +- [x] Проверить контраст normal/pressed/disabled/error/success во fallback и `space-pixel`; + CheckButton дополнительно получил тёмный текст и встроенные крупные ON/OFF-индикаторы. +- [x] Убрать зависимость от hover и мелкие интерактивные элементы: все девять экранов пройдены + runtime-аудитом, цифровые клавиатуры имеют равные крупные колонки, логика не использует hover. +- [x] Синхронизировать runtime-композицию с девятью preview-сценами `space-pixel`: перевести host на + нативную сетку 720×1280, перенести геометрию панелей и подключить безопасные именованные visual slots. +- [x] Перевести DLC-контракт на manifest v2 с полными визуальными сценами всех девяти экранов, + app-owned контроллерами, стабильными element binding-id и обратно совместимым v1 fallback. +- [x] Реорганизовать `ExchangerThemeDlcBuilder` в `themes/example` и `themes/`, добавить + валидатор имён/типов/биндингов и preview-overlay, показывающий binding-id каждого элемента. +- [x] Адаптировать host к самодостаточным production-сценам Builder: проверять metadata, собственный + Theme/фон/decoration, единый режим всех девяти экранов и отсутствие дублирующих глобальных слоёв; + при `ReducedEffects` скрывать и отключать обработку только `BackgroundDecoration`, не ограничивая + остальную доверенную runtime-логику темы. +- [x] Запретить host переоформлять самодостаточные сцены: Settings больше не назначает внешним + узлам `WhitePanel`/семантические variations, keypad-контроллеры не меняют их размеры и стили, + `ThemeManager.ApplyTo` оставляет Theme/геометрию полноэкранного view нетронутыми. +- [x] Убрать runtime-достраивание самодостаточных сцен: Home, карточные суммы и изменяемые списки + Settings работают с готовыми узлами и фиксированными слотами темы; host только подключает + события и передаёт функциональные значения, не добавляя и не удаляя Control-узлы. +- [x] Добавить в Settings theme-owned текстовую и цифровую клавиатуры: 57 новых биндингов, + состояния preview `OFF/TEXT/NUM`, неизменяемое визуальное дерево и общую C#-логику поля ввода; + каталог DLC расширен до 460 обязательных биндингов. +- [x] Добавить владельцу раздел «Сервис» с отдельным атомарным учётом остатка, ручным добавлением + через двойное подтверждение и списанием только фактически подтверждённых выдач. +- [x] Реализовать автоматический пересчёт прямыми командами `301/300` или `401/400`: считать + только `HOPPER1/2 PULSE=1`, не дублировать учёт по `INPUT`, завершать после 10 секунд тишины, позволять исправить результат + перед записью и безопасно останавливать мотор при отмене/закрытии. +- [x] Расширить self-contained theme-контракт сервисными и четырьмя состояниями индикатора запаса до 477 элементов; template + и `space-pixel` содержат готовые Service-панель и диалог, host меняет только значения и события. +- [x] Проверить деградацию при временной просадке FPS: таймауты используют монотонное реальное + время и завершаются корректно даже при единственном обновлении после скачка на 120 секунд. + +Программные ограничения, профили эффектов и локальный baseline реализованы. Проверка критерия +60 FPS, панели и декодера промо на автомате ведётся централизованно в разделе 4.1. + +### Этап 8. Тестирование и контроль качества — выполняется + +Цель: сделать регрессии воспроизводимыми до установки на автомат. + +- [x] Выбрать C# test runner: NUnit 4 для чистого доменного ядра и проверок файлов проекта. +- [x] Конфигурация, тарифы, валидация суммы, переходы `SessionFlow`, framing, parser и handshake покрыты unit-тестами. +- [x] Добавить интеграционные тесты `SessionFlow + IMachineController test double`; production `MockMachineController` дополнительно проверять в Godot runtime. +- [x] Добавить автоматическую проверку наличия/заголовков всех сцен, валидатор manifest DLC и runtime smoke-загрузку каждого экрана через Godot Editor. +- [x] Добавить тесты таймаутов с управляемым источником времени, без реального ожидания 120 секунд. +- [x] Проверить duplicate action, повторный `DISPENSE`, поздние события, disconnect/reconnect и неизвестные/malformed wire-ответы. +- [x] Проверить полные наличный и безналичный wire-сценарии от действия сессии до `ASK:*`, + выключения приёмников и выдачи; отдельно проверить пакет 515 жетонов как пять `30999` и один `30920`, подтверждённые соответствующим числом `HOPPER1 OK`. +- [x] Проверить отсутствие накопления подписок и стабильность многократных последовательных сессий. +- [x] Проверять C#-сборку и NUnit-набор после каждого завершённого блока. +- [x] Проверять Godot editor/game logs после изменений сцен и ресурсов. +- [x] Составить ручной чек-лист приёмки на физическом аппарате. +Физические проверки панели, SERVICE, дисплея и 24-часовой soak вынесены в раздел 4.1. + +### Этап 9. Сборка, установка и обновление Windows-версии — выполняется + +Цель: получить воспроизводимый устанавливаемый релиз. + +- [x] Создать export preset Windows x64 и воспроизводимый staging-сборщик. +- [x] Проверить включение self-contained .NET runtime, `GodotSharp.dll` и `System.IO.Ports.dll`. +- [x] Явно исключить `references/`, тесты, документацию, инструменты и dev-only addons из + production-экспорта; в проверенной сборке нет test DLL и addon-файлов. +- [x] Проверить `res://` и `user://` коротким headless smoke-run экспортированного EXE (exit code 0). +- [x] Исправить one-EXE runtime: встроенные JSON/TOML материализуются через Godot `FileAccess`, + `config/*.toml` включается в PCK, а runtime-autoload GodotxToast не удаляется export-фильтром. +- [x] Проверить итоговый one-file release: каталог `artifacts/windows/test_q` содержит ровно один + `Exchanger.exe` размером 190229328 байт; packaged mock и COM3 smoke завершились без ошибок. +- [x] Определить расположение пользовательской конфигурации и логов для сервисного персонала. +- [x] Добавить номер версии сборки в UI сервисного режима и журналы. +- [ ] Подготовить сценарий установки, обновления и отката. +- [~] Добавить цифровую подпись: текущий EXE подписан самоподписанным сертификатом `CN=Robotail` + с timestamp DigiCert; остаётся определить production-модель доверия и установить доверенный корень + на целевые устройства либо использовать сертификат доверенного CA. +- [ ] Зафиксировать контрольную версию конфигурации контроллера и приложения. + +Чистая установка и проверка релиза на целевом устройстве вынесены в раздел 4.1. + +### Этап 9.1. Linux x86_64 для Debian 13 — выполняется + +Цель: перенести desktop runtime на Debian без изменения UI, бизнес-логики и wire-протокола. + +- [x] Добавить Godot export preset `Linux x86_64 (Debian 13)` с production-фильтрами Windows-пресета. +- [x] Встроить PCK и managed build outputs; актуальный self-contained ELF x86_64 имеет размер + 155351952 байта, RID `linux-x64` и native `System.IO.Ports`. +- [x] Проверить заголовок артефакта: ELF64, AMD64/x86_64. +- [x] Разрешить в технической конфигурации `/dev/ttyUSB*`, `/dev/ttyACM*` и стабильные + `/dev/serial/by-id/*`, сохранив строгую валидацию Windows COM-портов. +- [x] Собрать отдельный Linux Debug ELF с расширенной безопасной диагностикой UART и handshake, + не перезаписывая release-артефакт. +- [ ] Подготовить udev/dialout и доступ сервисного пользователя к USB-UART. +- [ ] Подготовить Linux kiosk/autostart/watchdog и процедуру обновления/отката. +Физический запуск и приёмка на Debian 13 вынесены в раздел 4.1. + +### Этап 10. Подготовка Android-порта после MVP + +Цель: заменить платформенный транспорт без переработки UI и бизнес-логики. + +- [ ] Выбрать и согласовать USB-Serial Android-плагин. +- [ ] Реализовать `UsbSerialHardware` за существующим `IHardwarePort`. +- [ ] Добавить запрос USB permission и обработку переподключения устройства. +- [ ] Проверить ограничения Android kiosk/lock task mode. +- [ ] Адаптировать пути конфигурации/логов и жизненный цикл pause/resume. + +Физическая Android-приёмка целевого ARM64-устройства вынесена в раздел 4.1. + +## 8. Сквозные требования к реализации + +- Все новые скрипты по возможности пишутся на C#. +- Скрипты Godot Node/Resource объявляются как `partial class`. +- Комментарии в C# ведутся единообразно; для проекта выбран русский язык документации и пояснений сложной логики. +- Экраны не открывают порт, не парсят аппаратные строки и не управляют потоками. +- Ресурсы экранов и компонентов хранятся атомарно в соответствующих папках. +- Пути тем и экранов централизованы в реестрах/конфигурации. +- Сигналы и подписки освобождаются при завершении жизненного цикла узла. +- Таймауты и переходы состояний должны быть детерминированы и тестируемы. +- Новые внешние зависимости и NuGet-пакеты добавляются только при фактической необходимости; разрешение владельца на необходимые NuGet-пакеты получено, назначение и версия каждой зависимости фиксируются в документации. +- После существенных изменений обновляются этот ROADMAP, документация и `agentmemory`. + +## 9. Основные риски и меры снижения + +| Риск | Последствие | Мера снижения | +| --- | --- | --- | +| Неопределённый протокол контроллера | Переделка транспорта и сценария выдачи | Зафиксировать протокол и реальные примеры обмена до интеграции COM | +| Повтор `DISPENSE` после обрыва | Двойная выдача жетонов | Transaction ID/статус операции; запрет слепого retry | +| Поздний ответ от старой сессии | Выдача не тому сценарию | Идентификатор и поколение сессии, сброс входного контекста | +| UI обращается к Godot из COM-потока | Падения и гонки | Queue/CallDeferred, строгая граница транспорта | +| Слабый GPU | Просадки FPS и задержки тача | Compatibility, лимиты эффектов, fallback-фон, профилирование | +| Ожидание, что Godot заблокирует Alt+Tab | Выход пользователя из киоска | Настройка Windows Assigned Access/Shell Launcher | +| Несовместимый или повреждённый DLC темы | UI не может загрузить внешние ресурсы | Версионированный `.pck`, строгий manifest и программная fallback-тема | +| Неограниченные логи | Заполнение диска | Ротация, лимит размера и срока хранения | +| Android-зависимости проникают в UI | Дорогой порт | `IHardwarePort` и platform-specific composition | +| Неясный результат операции при аварии | Финансовая/операционная ошибка | Журнал транзакций, запрос статуса, безопасный сервисный сценарий | +| Текущий UI остаётся ландшафтным | Несоответствие реальному корпусу | Первым шагом Этапа 2 перейти на 1080×1920 и провести визуальную QA 720×1280 | +| Промо-ролик декодируется всегда | Лишняя нагрузка и просадки FPS | Останавливать плеер вне HomeScreen, ограничить формат/разрешение, иметь постер | +| Референсные цифры приняты за спецификацию | Неверные тарифы и бонусы | Хранить всё в конфигурации и запросить подтверждение владельца | +| Референсные ассеты попали в релиз без прав | Лицензионный риск | `references/` в `.gitignore`; исключить каталог в export preset и использовать только подтверждённые production-исходники | + +## 10. Вопросы для владельца продукта + +- [?] Подтвердить цену жетона: 10 рублей в референсе или другое production-значение. +- [?] Подтвердить таблицу бонусов, включая пример «100 + 50 в подарок». +- [?] Подтвердить карточные пресеты 10/50/100/150/200/300/400/500 рублей и предел другой суммы. +- [?] Есть ли выдача сдачи/возврат наличных и что происходит при отмене наличной операции? +- [?] Что именно запускает кнопка «Выдать» на домашнем и наличном экранах? +- [?] Кто является источником подтверждения оплаты и в каком формате приходит событие? +- [?] Может ли контроллер подтвердить фактический результат выдачи, включая частичную выдачу? +- [?] Поддерживает ли протокол идентификатор транзакции и запрос статуса последней операции? +- [?] Что должен делать автомат после подтверждённой оплаты и частичной/неуспешной выдачи? +- [?] Нужны ли возврат средств или обращение к оператору, и кто их выполняет? +- [?] Требуется ли локальное хранение истории операций и каков срок хранения? +- [?] Нужны ли удалённая диагностика, телеметрия или выгрузка логов? +- [x] Сервисный вход открывается по аппаратному `SERVICE`; опциональный единый PIN настраивается + в приложении при первом входе, матрица разрешений зафиксирована в `docs/operations/SETTINGS_ACCESS_MATRIX.md`. +- [?] Подтвердить финальные бренд, логотип, телефон, персонажа и права на референсные материалы. +- [?] Уточнить форматы промо-роликов, плейлист, звук и способ обновления контента. +- [?] Требуется ли локализация кроме русского языка? +- [?] Какой максимально допустимый простой и кто отвечает за автоматический перезапуск? + +## 11. Ближайший рабочий пакет + +Этапы 0–6 закрыты. Этапы 7, 8, 9 и 9.1 остаются в работе. Все проверки, требующие +физического автомата, собраны в разделе 4.1. Ближайший программный пакет: + +1. Подготовить установку, обновление и откат Windows-релиза. +2. Определить production-модель доверия цифровой подписи. +3. Зафиксировать контрольную пару версий приложения и прошивки. +4. Подготовить udev/dialout и доступ сервисного пользователя к USB-UART в Debian 13. +5. Подготовить Linux kiosk/autostart/watchdog и процедуру обновления/отката. + +Аппаратная очередь не дублируется здесь и полностью ведётся в разделе 4.1. + +## 12. Журнал прогресса + +### 2026-09-07 — Формат «К ВЫДАЧЕ» унифицирован для наличной и карточной оплаты + +- Готовая и ручная карточная сумма показывают базовые жетоны слева и бонус отдельно справа: + `+ N ЖЕТОНОВ\nВ ПОДАРОК` либо `БЕЗ БОНУСА`; длинная объединённая строка больше не используется. +- Заголовок `БАЛАНС ЖЕТОНОВ` на экране наличной оплаты заменён на `К ВЫДАЧЕ`. +- Для отдельного бонуса CardAmount добавлен supplemental runtime binding с побиндинговым fallback; + immutable JSON-каталог сохраняет 481 ID и прежний SHA-256. Документация Theme Builder и обе + внешние темы синхронизированы отдельно. +- Debug-сборка проходит без предупреждений, 487/487 NUnit-тестов, встроенная тема и свежие PCK + проходят headless `PaymentRewardFormattingSmoke` на mock-оборудовании без обращения к COM/UART. +- Предыдущий установленный `space-pixel` также проходит compatibility-smoke: отсутствующий новый + CardAmount Bonus подключается как один встроенный fallback binding без отказа всего DLC. +- Builder contract/validator/preview/PCK smoke и визуальный QA `720×1280` прошли для обеих тем. + Новые пакеты: `example.pck` — 464876 байт, SHA-256 + `02B8505FB7F0EF4F4E9C2905D97E8F8751A1DDE86DDF460AFC958CCE6AF51994`; + `space-pixel.pck` — 1436988 байт, SHA-256 + `4D9AA00FE2096794331B348916D1766B47A45D9EDFEE60BEAB0E424ED4761A67`. Пользовательский + `active_theme.pck` не заменялся. + +### 2026-09-07 — Учёт жетонов и ограничение покупки разделены + +- В разделе «Сервис» появились два включённых по умолчанию переключателя: ведение точного учёта + и независимый запрет покупки сверх остатка с учётом бонуса. При отключении самого учёта + скрываются точные остатки, кнопки пересчёта/добавления и приблизительное число на Home; + сохранённый файл остаётся для последующего восстановления режима. +- Если учёт включён, а ограничение выключено, остатки остаются видимыми и продолжают списываться, + но не блокируют оплату. При включённом ограничении карточная сумма отклоняется до запроса + терминалу, наличная — до команды выдачи; пресеты и ручной ввод показывают тот же лимит. +- Выключенный режим не списывает сохранённый остаток; `DualHopperAuto` использует hopper 1 и + сохраняет последовательное разбиение по 99 без автоматического failover. +- Конфигурация повышена до версии 23. Новые элементы темы оформлены в Builder как supplemental + runtime bindings; immutable JSON-каталог остаётся на 481 ID с прежним SHA-256. +- Debug/Release проходят 483/483 NUnit-теста. Встроенная тема и предыдущие `example.pck`/ + `space-pixel.pck` прошли отдельный runtime-smoke без реального COM/UART; проверка на автомате + добавлена в раздел 4.1. Старые PCK получают новый переключатель побиндинговым fallback. +- Свежие Builder-пакеты прошли contract/validator/preview/PCK smoke, визуальную проверку + `720×1280` и host runtime-smoke без fallback-подстановок: `example.pck` — `464268` байт, + SHA-256 `AC03334354D285E36A25BFB81D60880F829700F083AF5D728F10AB15C764B63D`; + `space-pixel.pck` — `1436492` байта, SHA-256 + `166660916913E4766FC91437155BB8B78A405150B3A599CF401CD78A83DFB727`. Установленный + пользовательский `active_theme.pck` не заменялся. + +### 2026-09-07 — Упрощён раздел общего текста в настройках + +- Поле «Название» скрыто, «Короткий текст» переименован в «Свой текст», отдельный + branding-preview удалён из отображения раздела «Общие». +- `Branding.ApplicationName` сохранён в модели и JSON для обратной совместимости, но больше не + редактируется и не может скрытой ошибкой заблокировать сохранение формы владельца. +- Binding ID, пути, типы и fallback не менялись: legacy-узлы остаются скрытыми контрактными + слотами, поэтому версия и SHA-256 binding-каталога не изменяются. +- Встроенная сцена, `example` и `space-pixel` синхронизированы. Debug/Release unit-наборы прошли + по `460/460`; host runtime-smoke прошёл для встроенной темы и нового `space-pixel.pck`, а обе + DLC-темы прошли Builder contract/validator/preview/PCK smoke и визуальную проверку `720×1280`. +- Новые пакеты: `example.pck` — `463324` байта, SHA-256 + `25E90059652EC26BD1779F7D6761F1CD1248A458F8C93F8E242596D3988FDE9F`; + `space-pixel.pck` — `1435548` байт, SHA-256 + `E5941A4E7437BA996945E85551714F8B6E11F77A64808C68B29A8B88F66629AB`. Активная + пользовательская тема автоматически не заменялась. + +### 2026-09-04 — Сниженная высота питомца оставлена только для sitting + +- Theme-owned компонент `space-pixel` сохраняет локальную поправку `(0,0)` для `sitting` и + применяет `(0,-24)` ко всем другим анимациям. Root, navigation, hit box и + `GROUND_OFFSET=(64,96)` не меняются. +- Builder verifier подтвердил переход `(0,0) → (0,-24) → (0,0)` и неподвижность root; contract, + validator, preview smoke, build и PCK verifier прошли. Preview `720×1280` учитывает union-envelope + состояний и подтвердил Nearest без clipping/пересечения с заголовком. +- Полный host `InteractivePetBehaviorSmoke` с явным новым PCK и mock-оборудованием прошёл: + drag/drop, поверхности и production-loader сохранили прежнее поведение. +- Новый PCK: 1435452 байта, SHA-256 + `390C9E3F83B026304F0E75E5A6AAD4458684BBCDFC847FFB542B6CFB1AC278E9`; активная пользовательская + тема автоматически не заменялась. + +### 2026-09-04 — Питомец space-pixel увеличен на 30% + +- Theme-owned `RUNTIME_SCALE` изменён с `0.65` на `0.845`; host-код и сцены Exchanger не + переделывались. Точка лап и hit-area масштабируются существующей общей формулой. +- Builder contract/test/validator/preview smoke/build и PCK verifier прошли; preview `720×1280` + подтвердил Nearest без clipping. Новый PCK: 1435004 байта, SHA-256 + `60E41BA7C1043348AB7C3FEED72C352AE3FBFA58BDACB00F4036F1CD0EB56088`. +- Production-loader Exchanger и полный `InteractivePetBehaviorSmoke` с явным новым PCK прошли на + mock-оборудовании: drag/drop, поверхности, смена сцен и четыре танца сохранены. + +### 2026-09-04 — Физическая сервисная кнопка сохранена поверх клавиатуры + +- Блокировка «Сохранить и выйти» ограничена её экранным обработчиком и GUI hit-test футера. + Аппаратный `ServiceRequested` по-прежнему напрямую вызывает `TryFinishEditing()`. +- Повторное физическое нажатие при открытой клавиатуре закрывает её, завершает сохранение и + возвращает Home по прежнему маршруту; незавершённые сервисные операции всё ещё блокируют выход. +- Runtime-smoke воспроизводит физическое нажатие через общий debug-action при открытой клавиатуре + на встроенной и установленной DLC-темах. Debug/Release без предупреждений, NUnit — 459/459. + +### 2026-09-04 — Футер больше не блокирует нижний ряд экранной клавиатуры + +- Установлено, что `Button.Disabled` не исключает кнопку и родительскую панель из hit-test, поэтому + перекрывающая геометрия фиксированного футера перехватывала физические нажатия нижнего ряда. +- Пока клавиатура открыта, футер и «Сохранить и выйти» используют `MouseFilter.Ignore`; после её + закрытия восстанавливаются исходные фильтры, а обработчик выхода остаётся защищён отдельно. +- Runtime-smoke проверяет реальный GUI hit-test нижних клавиш обеих панелей и координатный клик + текстовой клавиши. Встроенная и установленная DLC-темы прошли; Debug/Release без предупреждений, + NUnit — 458/458. + +### 2026-09-04 — Ввод экранной клавиатуры применяется без задержки + +- Исправлена рассинхронизация, при которой вставленный экранной клавиатурой текст был виден в + `LineEdit`, но не попадал в рабочую копию Settings до первого удаления. +- Каждая операция вставки, удаления, очистки и замены выделения теперь формирует ровно одно + уведомление `TextChanged`; числовое поле дополнительно немедленно применяет значение `SpinBox`. +- Runtime-smoke контролирует событие после первой буквы и после каждой введённой цифры на + встроенной и установленной DLC-темах. Debug/Release: 0 предупреждений, NUnit — 458/458. + +### 2026-09-04 — Выход из Settings заблокирован поверх экранной клавиатуры + +- `OnScreenKeyboardController` сообщает об открытии и закрытии любой своей панели; фиксированная + кнопка «Сохранить и выйти» отключается синхронно с этим состоянием. +- Обработчик выхода отдельно проверяет фактическую видимость клавиатуры и игнорирует программное + нажатие, даже если состояние `Button.Disabled` было обойдено. +- Runtime-smoke проверяет текстовую, обычную цифровую и сервисную цифровую клавиатуры на встроенной + и установленной DLC-темах. Debug/Release собраны без предупреждений, NUnit — 458/458. + +### 2026-09-04 — Переподключение платы переведено на технический интервал 30 секунд + +- Подтверждено, что авторитетный параметр уже находился в + `[controller].reconnect_interval_seconds`; шаблон и активная локальная конфигурация изменены + с 5 на 30 секунд, остальные монтажные параметры не затронуты. +- При отсутствии платы после первой немедленной попытки порт повторно открывается каждые 30 секунд. + После обрыва работавшего транспорта отсчёт начинается заново от момента обнаружения обрыва, + поэтому устаревший стартовый дедлайн больше не вызывает немедленный reconnect. +- Планировщик повторно ставит дедлайн после каждой неудачной попытки; оплату и выдачу не повторяет. + Оба сценария покрыты детерминированными unit-тестами без COM/UART. +- Debug/Release собраны без предупреждений, NUnit — 458/458; headless mock подтвердил фактическую + загрузку `reconnectSeconds=30` из текущего пользовательского TOML. + +### 2026-09-04 — Ручной ввод суммы получил однозначное удаление цифры + +- Левая кнопка нижнего ряда CardCustomAmount переименована из «ОТМЕНА»/«СБРОС» в «СТЕРЕТЬ» и + удаляет только последнюю введённую цифру; после удаления последней цифры экран показывает `0`. +- Legacy binding `clear_button` сохранён ради совместимости, а отдельный обязательный + `backspace_button` скрыт, чтобы в интерфейсе не было двух одинаковых действий. +- Runtime-smoke подтвердил последовательность `12 → 1 → 0` на старом установленном PCK; + Debug/Release собраны без предупреждений, NUnit — 455/455. +- Обе темы прошли Builder validator/preview/build/PCK verify. В `space-pixel` надпись полностью + помещается при 720×1280; новый PCK прошёл production-loader приложения на mock-оборудовании. + +### 2026-09-04 — В Settings добавлен фиксированный футер сохранения + +- Кнопка «Сохранить и выйти» вынесена из прокручиваемого содержимого в закреплённый нижний футер; + drag по футеру не прокручивает список, а нижний зазор позволяет показать последние поля над ним. +- Кнопка завершает ожидающее атомарное автосохранение через общий `TryFinishEditing()` и возвращает + Home только после успеха; физическая сервисная кнопка сохраняет прежнее поведение. +- Пока открыта текстовая или цифровая экранная клавиатура, кнопка отключена; обработчик также + отклоняет программное нажатие, чтобы клавиатура не могла случайно инициировать выход. +- Для новых DLC добавлены supplemental bindings футера, кнопки и нижнего зазора. Старые PCK + получают только эти отсутствующие элементы из встроенной темы-заглушки. +- Встроенная тема, ранее установленный PCK и новый полный `space-pixel.pck` прошли runtime-smoke + на mock-оборудовании; Debug/Release собраны без предупреждений, NUnit — 454/454. + +### 2026-09-04 — Добавлена побиндинговая обратная совместимость DLC-тем + +- Отсутствующий обязательный binding больше не отключает весь DLC: runtime сначала принимает + совместимый узел старой темы по каноническому `FallbackPath`, а при его отсутствии переносит + готовый элемент встроенной темы-заглушки вместе с её оформлением. +- Если точечно собрать экран невозможно, встроенным становится только этот экран; остальные + корректные сцены внешней темы сохраняются. Неизвестные ID, дубли, неверные типы, root и + повреждённый контракт по-прежнему отклоняются. +- Реальный ранее установленный `space-pixel.pck` принят без пересборки: Home восстановил один, + Settings — четыре новых биндинга. Запуск прошёл на mock без обращения к COM/UART. +- Release-сборка прошла без ошибок и предупреждений, NUnit — 452/452. + +### 2026-09-04 — В сервис добавлено скрытие элементов домашнего экрана + +- В новой панели «Скрытие элементов меню» независимо управляются учётный остаток жетонов, + theme-owned персонаж справа и весь промо-блок; старые настройки мигрируют с показом всех трёх. +- Изменения автосохраняются и применяются к уже созданному Home без перезапуска приложения. +- Host меняет только видимость готовых узлов fallback/DLC. Скрытые остаток и промо исключаются + вместе с маршрутами питомца, поэтому он не садится на невидимые поверхности. +- Обе темы прошли Builder validator/preview-smoke и PCK verifier; новый `space-pixel.pck` + дополнительно загружен production loader приложения на mock-оборудовании без ошибок. +- Release-сборка прошла без ошибок и предупреждений, NUnit — 448/448. + +### 2026-09-03 — Debug-сборка получила расширенную диагностику подключения платы + +- Добавлен компилируемый только в Debug уровень `[DEBUG]`; Release не содержит вызовов и строк + расширенной диагностики. +- Журнал фиксирует платформу и параметры UART, открытие устройства, reset DTR/RTS, запуск и + завершение worker, безопасную причину транспортной ошибки, reconnect и переходы handshake. +- Сырые кадры, AES challenge/response, ключи и платёжные payload не выводятся; показываются только + тип этапа, состояние, длина и безопасные счётчики. +- Runtime summary в разделе «Диагностика» Debug-сборки показывает transport/auth state. +- Debug и Release собраны без ошибок и предупреждений, обе конфигурации прошли NUnit 444/444; + Debug headless-smoke на mock подтвердил фактическую запись `[DEBUG]` в журнал. +- Собран отдельный Linux Debug ELF: 155630576 байт, SHA-256 + `A1FB92126D6ED753DF968180075D7409678E5F0A7C454CB6D2B954DC024682B6`. + +### 2026-09-03 — Последовательный порт адаптирован для Windows и Linux + +- Общая валидация выбирает правила по фактической ОС процесса: Windows принимает только + `COM1`…`COM256`, Linux — `/dev/ttyUSB*`, `/dev/ttyACM*` и `/dev/serial/by-id/*`. +- При `use_mock = true` имя порта не проверяется и безопасный общий шаблон с `COM3` остаётся + пригодным для mock-запуска Linux-сборки. +- `SerialPortHardware` остался единым desktop-транспортом на `System.IO.Ports`; сообщения + транспорта больше не привязаны к термину COM. +- Unit-тесты отдельно покрывают обе платформенные ветки и недопустимые Linux-пути. +- Release-сборка прошла без ошибок и предупреждений, NUnit — 444/444. +- Linux release повторно экспортирован одним ELF64 AMD64-файлом размером 155351952 байта, + SHA-256 `7312E79514842EB5EA3193604F71CAAE412654957640032B62D66E202802284C`. + +### 2026-09-02 — Экранная клавиатура подключена к ручному пополнению хоппера + +- При открытии диалога «Добавить в хоппер» поле количества после появления модального слоя + автоматически получает фокус, выделяет текущее значение и показывает цифровую клавиатуру. +- Контроллер клавиатуры учитывает, что сервисное поле находится вне основного ScrollContainer, + и не пытается прокручивать скрытый список настроек. +- Сцены темы не менялись: host использует существующие binding-id поля, диалога и готовой + theme-owned цифровой клавиатуры. +- Runtime-smoke открывает сервисный диалог, проверяет видимость клавиатуры и фокус поля, затем + закрывает оба слоя. Fallback и `space-pixel.pck` прошли с mock-оборудованием. +- Сборка прошла без ошибок и предупреждений, NUnit — 410/410; 18 hardware-тестов пропущены. + +### 2026-09-02 — Выдача двух хопперов переведена на строгий приоритет первого + +- Для запроса `N` план выдачи теперь всегда равен `H1=min(N, остаток H1)`, `H2=N-H1`: + второй хоппер используется только для недостающей разницы после первого. +- Удалён прежний выбор стартового хоппера по датчикам уровня и сравнительному остатку, из-за + которого выдача могла начинаться со второго хоппера. +- При недостаточном суммарном учётном остатке ни одна команда выдачи не отправляется. Аппаратная + ошибка во время уже начатой выдачи по-прежнему не вызывает автоматический retry/failover. +- Mock приведён к тому же правилу и больше не создаёт фиктивное подтверждение сверх остатка. +- Интеграционный тест подтверждает последовательность `H1=6`, `H2=20`, запрос `10`: + сначала `3096`, после шести `HOPPER1 OK` — `4094`, итоговый раздельный учёт `(6, 4)`. +- Для обоих хопперов отдельно закреплена последовательная пакетная выдача 205 жетонов: + `30999 → 30999 → 3097` либо `40999 → 40999 → 4097`. `APPEND=N` не запускает следующий пакет; + он отправляется только после всех 99 `OK`. Смешанный план 180 при остатках `(150, 50)` даёт + `30999 → 30951 → 40930`, не запуская второй хоппер раньше завершения первого. +- Сборка прошла без ошибок и предупреждений, NUnit — 409/409 (18 hardware-тестов пропущены), + runtime-smoke с `space-pixel.pck` и mock-оборудованием прошёл без binding-ошибок. + +### 2026-09-02 — Исправлено склонение слова «жетон» в пользовательском потоке + +- Добавлен единый форматтер русских окончаний: `1 жетон`, `2–4 жетона`, `5–20 жетонов`, включая + исключение `11–14` и повторяющиеся разряды (`21`, `22`, `111`, `124`). +- Исправлены тексты выбора суммы, наличной оплаты, произвольной карточной суммы, ожидания терминала, + прогресса выдачи и финального сообщения, в том числе количество подарочных жетонов. +- Внешние сцены не изменялись: host обновляет только динамический текст существующих Label. +- Сборка прошла без ошибок и предупреждений, NUnit — 395/395 (18 hardware-тестов пропущены), + runtime-smoke с `space-pixel.pck` и mock-оборудованием прошёл без binding-ошибок. + +### 2026-09-02 — Добавлен раздельный остаток жетонов по хопперам + +- Settings показывает точный общий остаток и отдельные значения для хоппера 1 и хоппера 2; + данные берутся из сохранённого `TokenInventorySnapshot` и обновляются после подтверждённой + выдачи, пересчёта и ручного добавления. +- Host использует существующие theme-owned `Hopper1Label`/`Hopper2Label`; геометрия и оформление + внешней темы приложением не меняются. +- В контракт добавлены два Label-binding: всего 481 биндинг, SHA-256 каталога — + `DDDC89118BEEA78A820561464001656136ED42AC1AD5710FB109D25ADAF44143`. +- Сборка прошла без предупреждений и ошибок, NUnit — 376/376 (18 hardware-тестов пропущены). + `example` и `space-pixel` прошли contract/validator/preview smoke; fallback и собранный + `space-pixel.pck` прошли host runtime-smoke с mock-оборудованием. Сервисная панель `space-pixel` + визуально проверена в Theme Builder при `720×1280` без наложений и обрезания текста. + +### 2026-09-02 — Windows Debug и Release разведены по отдельным пресетам + +- Неоднозначный `Windows x64` заменён на `Windows x64 Release` и `Windows x64 Debug` с разными + output-путями, custom features, console wrapper и настройками debug symbols/C# sources. +- `tools/export-windows.ps1` принимает `-Configuration Release|Debug`, по умолчанию собирает + Release и передаёт Godot соответствующий `--export-release` либо `--export-debug`. +- Release создаёт `Exchanger.exe`, Debug — `Exchanger.Debug.exe`; каталоги содержат конфигурацию + и timestamp, поэтому варианты не перезаписывают друг друга. +- Оба режима фактически экспортированы официальным Godot 4.7.1 Mono и прошли packaged headless + smoke с mock-оборудованием: Debug содержит основной EXE и console wrapper, Release — один EXE. + Контрольные файлы не подписаны; Authenticode остаётся отдельным release-шагом. + +### 2026-09-02 — Разделены таймауты наличной и безналичной оплаты + +- Конфигурация v20 получила независимые `CashPaymentSeconds` и `CashlessPaymentSeconds`; + прежний `PaymentSeconds` мигрируется без потери значения, а наличный таймаут наследует прежний + `SessionIdleSeconds`. +- `SessionFlow` использует наличный таймаут на экране приёма денег и продлевает его при активности + или изменении баланса; ожидание карточного терминала использует отдельный безналичный таймаут. +- В Settings добавлены два самостоятельных поля с отдельной валидацией. Fallback, `example` и + `space-pixel` содержат готовые theme-owned элементы; C# только подключает их по биндингам. +- Host-контракт синхронизирован до 479 биндингов и одновременно закрыл прежний блокер + `card_terminal.content.top_bar.back_button`; SHA-256 каталога — + `B33F34A50837560AF8C3589B3E0AA19BB03B7B534AF6A27001C4FA19DE4155BF`. +- Release/Debug собираются без предупреждений, NUnit — 372/372. Обе темы прошли contract, + validator и preview smoke; установленный `space-pixel` прошёл Exchanger headless smoke с + mock-оборудованием без binding-ошибок и без доступа к реальному COM. + +### 2026-09-02 — CardTerminal «Назад» возвращает к выбору суммы + +- Host подключает существующий binding верхней кнопки `BackButton`, не изменяя сцену внешней темы. +- Перед возвратом из `CardTerminalWait` вызывается `CancelActiveOperation()`, поэтому Вендист + выключается и предыдущий результат оплаты игнорируется вне состояния ожидания терминала. +- Красная кнопка «ОТМЕНА» сохраняет прежнее поведение: завершает карточную сессию и возвращает Home. +- `kiosk_back` теперь соответствует верхней кнопке «Назад»; добавлен регрессионный тест перехода. +- Release-сборка прошла с 0 ошибок/0 предупреждений, NUnit — 367/367; headless Godot smoke + с `--mock-hardware=true` загрузил актуальную `space-pixel` без исключений и без обращения к COM3. + +### 2026-09-01 — Этапы 4 и 5 закрыты, физическая приёмка централизована + +- Этап 4 закрыт по готовности COM-транспорта, worker-потока, reconnect и at-most-once; + оставшиеся действия с реальным контроллером перенесены в раздел 4.1. +- Этап 5 закрыт по фактической безопасной политике UI: кнопки повторной выдачи нет, ошибки ведут + домой, к другому способу оплаты либо в поддержку, а `UnknownAfterRestart` не запускает retry. +- Все актуальные проверки панели, производительности, платежей, обоих хопперов, пересчёта, + USB-reconnect, soak и целевых платформ собраны в «4.1. Проверки на автомате» и удалены из этапов. +- Ближайший рабочий пакет теперь содержит только программные и эксплуатационные задачи. + +### 2026-09-01 — Дорожная карта синхронизирована с one-file export и текущим контроллером + +- Удалено устаревшее утверждение, что плата отключена: последний packaged Windows smoke успешно + авторизовал COM3, однако новые аппаратные действия по-прежнему требуют отдельного разрешения. +- Зафиксированы one-file Windows release, исправления embedded PCK/TOML/autoload и текущее состояние подписи. +- Добавлен отдельный этап Linux x86_64 для Debian 13: export готов, целевой runtime, serial-path, + udev/dialout, kiosk и физическая приёмка остаются открытыми. +- Ближайший рабочий пакет синхронизирован с фактическими задачами Этапов 5, 7, 8, 9 и 9.1. + +### 2026-08-31 — Включён полноценный учёт и выдача двух хопперов + +- Временный запрет второго хоппера отменён: целевой профиль `DualHopperAuto` использует `30X` и `40X`, подтверждения принимаются только от активного канала. +- Точный остаток хранится отдельно для каждого хоппера; ручное добавление и автоматический пересчёт доступны раздельно, а подтверждённая выдача списывается с фактически сработавшего канала. +- Покупателю на главном экране справа от полоски запаса показывается только приблизительный общий остаток: + `<100`, шаг 100 до 1000 включительно и шаг 500 выше 1000. +- Владельцу в разделе «Сервис» показывается точный учётный остаток с человекочитаемым склонением + слова «жетон»; приблизительные диапазоны из интерфейса настроек удалены. +- Главная индикация получила четыре состояния: пустая полоска «нет жетонов», красная 25% «мало», красная 50% «достаточно», зелёная 100% «много». Состояние вычисляется совместно по общему учёту и active-low датчикам `IN1/IN4`. +- Внешний DLC-контракт дополнен предсозданными визуалами четырёх состояний; приложение только переключает их видимость и не перестраивает сцену темы. +- Конфигурация поднята до версии 18 и мигрирует старые одноканальные профили в `DualHopperAuto`. +- Обычный набор расширен тестами двух остатков, округления, правил индикации, `40X`, второго пересчёта и двух датчиков. Аппаратные тесты и COM не запускались. + +### 2026-08-31 — Интегрирован протокол новой прошивки первого хоппера + +> Историческая запись промежуточного состояния. Ограничение одного хоппера отменено записью выше. + +- На тот момент разводка: `IN8` — сервисная кнопка; `IN1/IN24` — запас и физическая выдача первого хоппера; `IN4` — запас второго. Вход выдачи второго хоппера пока неизвестен. +- До исправления прошивки второго канала runtime работает только в `Hopper1Auto`, отправляет только `30X` и отклоняет `Hopper2Auto` без записи `40X` в COM. +- Выдача использует `309N`, типизированные ответы `HOPPER1 APPEND=N`, `HOPPER1 OK`, `HOPPER1 ERROR`, `HOPPER1 CREDIT=N` и запрос остатка `3090`. Ошибка не защёлкивает хоппер до перезапуска и не вызывает автоматический повтор команды. +- Подтверждено ограничение одной команды: N = 1–99; `309100` возвращает `ERROR:30:invalid count (0-99)`. Runtime использует общую константу 99 и разбивает крупную выдачу на последовательные пакеты. +- Для будущего второго канала сохранён симметричный контракт `409100 → ERROR:40:invalid count (0-99)`; симулятор и тесты его знают, но runtime продолжает запрещать любые `40X`. +- Автоматический пересчёт запускается `301`, считает только строки `HOPPER1 PULSE=1` и останавливает мотор командой `300` после 10 секунд тишины. +- Вендиста поддерживается командой `161` в idle/card-состоянии с интервалом 120 секунд, то есть заведомо чаще требуемых прошивкой 180 секунд; на время наличной оплаты и выдачи используется `162`. +- Конфигурация поднята до версии 17 и мигрирует прежний целевой `Hopper2Auto` на `Hopper1Auto`; на том этапе второй датчик выдачи сохранялся как `-1`, позднее владелец подтвердил его привязку к `IN25`. +- Код, симулятор, unit-тесты, аппаратный runner и документация синхронизированы. После фиксации предела пакета обычный набор прошёл 323/323, решение собрано без предупреждений и ошибок. Аппаратные тесты и любые обращения к COM не выполнялись, потому что плата отключена. + +### 2026-08-31 — Авторизация синхронизирована с актуальным plate_config_app + +- После открытия COM-порта выполняется аппаратный reset: очистка буферов, DTR=false, RTS=true на 100 мс, затем RTS=false. +- Контроллер должен прислать точный startup-баннер `periphery controller ver_`; после паузы 2000 мс выполняется `07 → CHAL → 08 → RAES`. +- Корректный `RAES`, `AUTH_PC_OK` и `AUTH_CNT_OK` являются промежуточными стадиями. Рабочие команды разрешаются только после точного кадра `READY!`. +- [x] Синхронизировать таймауты с актуальным `plate_config_app`: startup-баннер — 20 с, обязательная пауза — 2000 мс, `CHAL` и `RAES` — по 2000 мс, финальный `READY!` — 5 с. Конфигурация v19 переводит только старое стандартное значение 5000 мс на 2000 мс и сохраняет явно заданные пользовательские значения. +- Входящие `CHAL` и `RAES` разбираются совместимо с `plate_config_app`: поддерживаются слитный HEX-payload, пробел или двоеточие после префикса. +- Симулятор, unit/integration-тесты и безопасный аппаратный probe приведены к тому же контракту. +- Решение собирается без предупреждений; программный NUnit-набор проходит 310/310. +- Физический auth-probe на COM3 прошёл 1/1; `Safe` прошёл 8/9. Новый handshake, `91`/`IN1`, + `140`, `150`, `409?`, `99` и три reconnect-цикла подтверждены. +- Единственный открытый аппаратный результат — отсутствие ответа на `160` в двух независимых + запусках. Это не блокирует авторизацию, но требует проверки подключения/режима Вендиста. + +### 2026-08-28 — Исправлена пакетная выдача второго хоппера + +- Реальный обмен показал формат прошивки: `40910` ставит в очередь 10 жетонов, после чего плата отвечает `HOPPER2 queued 10 prizes` и десять раз `HOPPER2 OK`. +- `Hopper2Auto` переведён с ошибочной схемы «одна `409` → опрос `IN25`» на `409N → N × HOPPER2 OK`; короткие импульсы `IN25` больше не могут быть пропущены периодическим опросом и не дублируют подтверждения платы. +- Пакеты ограничены 99 жетонами; выдача 515 жетонов детерминированно разбивается на пять `40999` и один `40920`, следующий пакет отправляется только после завершения предыдущего. +- Parser типизирует `HOPPER2 queued N prizes`, симулятор воспроизводит реальный порядок кадров. Обычный набор прошёл 289/289; 17 аппаратных тестов безопасно пропущены без явного разрешения на запуск мотора. + +### 2026-08-27 — Целевой хоппер исправлен на второй + +- Владелец уточнил фактическую разводку: `IN1` и `IN25` принадлежат второму хопперу, а `IN2/IN24` — будущему первому. +- Добавлен режим `Hopper2Auto` и типизированные `HOPPER2 OK/ERROR`. Первоначальная трактовка одиночной `409` и подсчёта `IN25` позднее заменена подтверждённым пакетным форматом `409N`; актуальное поведение описано в записи от 2026-08-28. +- Status-запрос аппаратного runner переведён с исторического `309?` на `409?` для второго хоппера; формат ответа ещё нужно подтвердить безопасным прогоном COM3. +- Конфигурация версии 15 автоматически мигрирует прежний `Hopper1Auto` на `Hopper2Auto`, если он использовал целевую пару `IN1/IN25`; локальный COM3-профиль уже обновлён. +- Регрессии того блока покрывали прежнюю интерпретацию `409`/`IN25`; после проверки прошивки они заменены тестами `409N`, `HOPPER2 queued` и `HOPPER2 OK`. Актуальный набор и результаты указаны выше. + +### 2026-08-27 — Платёжные действия повторно сверены с протоколом платы + +- Для наличной ветки зафиксирована и протестирована последовательность `162 → 141 → 151`, + обязательные `ASK:COINS/BILL`, а перед выдачей/при отмене — `142 → 152`. +- Для безналичной ветки выбор способа не включает терминал до подтверждения суммы; подтверждение + отправляет `142 → 152 → 161 → 163`, `MONEY:CASHLESS` сначала получает обязательный + `ASK:CASHLESS`, затем терминал выключается `162`. Несовпадающая сумма выдачу не запускает. +- Платёжные каналы стали явно взаимоисключающими, а повторные Cancel/End не добавляют одинаковые + команды в последовательную очередь платы. +- Последующее уточнение разводки показало, что `IN1/IN25` относятся ко второму хопперу; поэтому прежняя реализация `309`/`Hopper1Auto` для целевого автомата была заменена на `409`/`Hopper2Auto` в следующем блоке работ. +- Полные cash/card сценарии и пакет 515 жетонов прошли через настоящий parser, authenticator, + `PeripheryMachineController`, `SessionFlow` и wire-симулятор. Набор: 283/283 unit/integration; + 17 аппаратных тестов по-прежнему требуют явных флагов, реальные деньги и мотор не запускались. +- После изменений безопасная аппаратная группа повторно запущена на CP210x/COM3: 9/9, включая + handshake, `INPUT`, активный `IN1 → Low`, `140`, `150`, `160`, `309?`, `99` и три reconnect-цикла. + Отчёт: `artifacts/board-tests/board-safe-20260827-161454.trx`. Реальные деньги и мотор не + запускались; один краткий `UnauthorizedAccessException` при переоткрытии восстановлен retry. + +### 2026-08-27 — Настраиваемый короткий текст в речевом bubble + +- Добавлена отдельная настройка `Branding.ShortText` с понятным названием «Короткий текст», лимитом 48 символов, автосохранением, валидацией и preview. +- `HomeScreen` подставляет значение только в авторский Label речевого bubble по биндингу `home.scroll.content.speech_text`; старый `Subtitle` и его биндинги не возвращаются. +- Конфигурация поднята до версии 14: существующий профиль получает безопасный текст по умолчанию и атомарно сохраняется с резервной копией. +- Theme Builder добавил новый HOME-биндинг и три SETTINGS-биндинга `short_text`; актуальный контракт содержит 460 ID и имеет SHA-256 `1FA54C9B9A0A7DFF71A5FAD38A5E9036E6C2D8F3D0BD298F003524A3E752FA10`. + +### 2026-08-26 — Исправлена полярность датчика запаса IN1 + +- Подтверждено по протоколу платы и утилите тестирования входов: цифровые входы используют pull-up, поэтому активный сигнал на `IN1` сбрасывает бит маски. +- Production-сопоставление исправлено на `IN1 bit 0 → Low` и `IN1 bit 1 → Enough`; обновлены defaults, аппаратные runner/tests и документация. +- Конфигурация поднята до версии 13: профиль с подтверждённым входом `IN1` автоматически мигрирует с ошибочной active-high полярности на active-low, а прежний JSON сохраняется в `.bak`. +- На подключённой плате COM3 безопасная группа прошла 9/9; текущий активный IN1 был интерпретирован как `Low`. Модульные тесты прошли 262/262. + +### 2026-08-26 — Короткое описание полностью удалено + +- Удалено поле короткого описания из модели `BrandingSettings`, нормализации, валидации, настроек владельца, preview и HOME. +- Конфигурация поднята до версии 12: старое JSON-поле `Subtitle` игнорируется и удаляется при автоматической миграции с сохранением предыдущего файла в `.bak`. +- Из контракта DLC и обеих тем были удалены четыре HOME/SETTINGS-биндинга короткого описания; на этом шаге контракт содержал 456 обязательных биндингов и имел SHA-256 `E77F754AB2C3913928B7DF18DD3D8F3205000D1531C414CC5B621E21CDF03ECF`. + +### 2026-08-26 — Экранные клавиатуры настроек + +- В `src/ui/OnScreenKeyboard` добавлен общий C#-контроллер: русский и английский алфавиты, + Shift, 33 спецсимвола, каретка, пробел, очистка/удаление и отдельный цифровой режим. +- Все `LineEdit` и `SpinBox` Settings, включая динамические fallback-строки и фиксированные слоты + внешней темы, регистрируются автоматически; native virtual keyboard отключён, числовой ввод + подтверждается через `SpinBox.Apply()`, а активное поле поднимается над нижней панелью. +- Fallback и обе темы содержат заранее созданные текстовую и цифровую панели с кнопкой скрытия + справа сверху. Runtime не создаёт и не перестраивает их Control-узлы. +- Theme Builder получил общий компонент, preview-состояния `KEYBOARD: OFF/TEXT/NUM` и 57 новых + metadata binding-id. Контракт расширен с 403 до 460 биндингов; SHA-256 каталога: + `4552F55F78E744DF90DC4D8153330D4A6A6C156673C12B384E828D99AA93CE3A`. +- NUnit-набор расширен до 262 тестов; fallback Settings импортируется и запускается headless без + ошибок. Отдельный runtime smoke подтвердил ввод букв и числа, показ и скрытие обеих панелей как + во fallback, так и в установленной внешней теме. Ручная проверка пальцем и в перчатках остаётся + частью физической приёмки Этапа 8. +- Установлен `space-pixel.pck` размером 672840 байт, SHA-256: + `752710CB91BD7D4A5FCC60A80B427671B2E98CE937203CD24A5648943008399A`. Предыдущий пакет сохранён + как `active_theme.pre-onscreen-keyboard.pck` (634888 байт, SHA-256: + `22359A8D488352BA3E2C5E6E294C6822EEDEA853BD66ADF429C861D6C7B00DD8`). +- У бонусного `SpinBox` удалена приписка «жет.» во fallback и во всех 16 фиксированных слотах + обеих тем: многозначное количество дополнительных жетонов теперь показывается полностью. + Установлен исправленный `space-pixel.pck` размером 672520 байт, SHA-256: + `5CC976A4B8EB07A15571F00DCB74BD7D46F1CBC8BDEAF97E1A994131763321E7`; предыдущий пакет сохранён + как `active_theme.pre-bonus-suffix-fix.pck`. + +### 2026-08-26 — Host адаптирован к самодостаточным сценам Theme Builder + +- Поддержана новая структура `themes/example`, `themes/space-pixel` и `themes/`; + production-сцены теперь сами содержат Theme, статический `ThemeBackground` и + `BackgroundDecoration` с metadata `exchanger_self_contained_visuals = true`. +- Loader проверяет структуру каждой сцены, запрещает смешивать два режима внутри одного PCK и + отклоняет глобальные background/decoration пути, которые дублировали бы экранную композицию. +- `ReducedEffects` теперь скрывает и полностью останавливает decoration внутри текущего экрана; + единый лимит узлов, CanvasItem, анимаций и кадров применяется и к самодостаточной decoration. +- Устранено runtime-переоформление готовых сцен: прежний проход Settings принудительно назначал + панелям `WhitePanel` и менял внешний вид относительно preview; теперь визуальные семантики и + размеры keypad применяются только к встроенному fallback, а self-contained view сохраняется. +- Root внешней сцены больше не переименовывается в `ThemeView` и не получает повторный layout + preset; бюджет decoration стал чистой проверкой без изменения FPS/`speed_scale` ресурса. +- Удалены семь зон runtime-достраивания: запас, связь и промо Home, кнопки карточных сумм, правила + бонусов, суммы оплаты и список промо Settings. На этом шаге контракт был расширен до 403 + обязательных биндингов; + самодостаточная тема заранее содержит все визуальные элементы и фиксированные слоты. +- Актуальный `space-pixel.pck` размером 632992 байта установлен в стандартный `user://`; SHA-256: + `122A6F16ED727080AC1F8EC407E94CD5D9E6CDBDF0A0465F27E1AF6C26ADAF6E`. Предыдущий пакет сохранён + рядом как `active_theme.pre-binding-only.pck`; более ранняя копия также сохранена как + `active_theme.pre-self-contained.pck`. +- Solution собирается без предупреждений; 254 unit/integration-теста проходят, 17 физических + hardware-тестов безопасно пропущены без явного запуска на плате. + +### 2026-08-25 — Завершён полносценовый DLC-контракт v2 + +- Все девять C#-контроллеров экранов отделены от визуального дерева: внешний DLC заменяет только + `SafeMargin` на собственный `ThemeView`, а оплата, навигация, настройки и оборудование остаются + в основном приложении. +- Зафиксированы шаблон имён `screen_.tscn`, root-имена `ThemeScreen_`, metadata + `exchanger_screen_binding_id` и `exchanger_binding_id`; расположение элементов внутри темы + больше не влияет на привязку. +- В host добавлен закреплённый SHA-256 каталога из 187 обязательных биндингов. До активации PCK + проверяются девять сцен, ID, Godot-типы, полнота, отсутствие неизвестных биндингов, дубли и + полный запрет скриптов. +- Обратная совместимость manifest v1 сохранена как стилевой режим с единственной встроенной + fallback-темой. +- `ExchangerThemeDlcBuilder` реорганизован в `themes/_template` и `themes/space_pixel`; preview + использует реальные production-сцены, показывает 9 вкладок и overlay binding-id с live reload. +- `_template` и `space_pixel` проходят full-scene validator. Итоговый PCK размером 407832 байта + установлен в стандартный `user://`; SHA-256 пакета: + `CB1EC8F6C6F908139CD6B602E5A7A401E271F8AD5F69BF5C3943B4FD6D10FF47`. +- Runtime smoke подтвердил внешний `ThemeView` у всех девяти контроллеров, отсутствие app-owned + Timer/AudioStreamPlayer внутри темы и чистый журнал Godot. Solution собирается без + предупреждений; 247 unit/integration-тестов проходят, 17 физических hardware-тестов безопасно + пропущены без явного запуска на плате. + +### 2026-08-25 — Runtime-интерфейс синхронизирован с preview темы + +- Логический viewport приложения переведён с 1080×1920 на нативные для theme-builder 720×1280; + пиксельный текст больше не проходит через промежуточное уменьшение 2/3. +- Главная, наличная и карточная ветки, терминал, успех, ошибка и сервисный вход получили геометрию, + панели, кнопки и общий footer из соответствующих preview-сцен `space_pixel`. +- DLC manifest v1 обратно совместимо расширен именованными `VisualSlots` для пассивной графики + `home`, `cash`, `card` и `result`; host сохраняет поверх них собственные тексты и бизнес-логику. +- Для decoration добавлен явный `BackgroundDecorationScale`; текущий фон 1080×1920 масштабируется + до нативной сетки коэффициентом 0.666667 без влияния на screen-specific слоты. +- Настройки владельца пересчитаны в нативные координаты 720×1280, при этом пять разрешённых вкладок + и автоматическое сохранение сохранены; технические разделы не возвращались. +- Актуальный `space_pixel` PCK собран и установлен. Сборка без предупреждений; 234/234 модульных + теста прошли, 17 аппаратных тестов безопасно пропущены без явного запуска на плате. + +### 2026-08-25 — Настройки переориентированы на владельца автомата + +- Из навигации `SettingsScreen` удалены вкладки «Тема», «Оборудование» и «Диагностика»; в шапке оставлен только короткий заголовок «НАСТРОЙКИ» без ролей и поясняющего подзаголовка. +- Убраны внешний DLC и путь `.pck`, сводка применения темы, технический итог промо, COM/mock/reconnect, окно/FPS, состояние приложения, предупреждения, журналирование и тестовая выдача. +- Владельцу оставлены пять разделов: «Общие», «Звук», «Промо», «Тарифы» и «Оплата», включая PIN, оформление главного экрана, цены, бонусы, способы оплаты и время ожидания. +- Скрытые deployment-параметры исключены из валидации формы владельца и больше не могут заблокировать автосохранение доступных полей. +- Runtime QA на 720×1280 подтвердила пять вкладок, понятные формулировки и отсутствие всех технических панелей; сборка без предупреждений, 228/228 модульных тестов прошли, 17 аппаратных безопасно пропущены. +- Удалены избыточные пояснения о назначении проверочного звука и общем диапазоне карточных сумм; высота соответствующих карточек и шапки уменьшена без пустых зон. +- Тексты всех доступных владельцу разделов и экрана ввода PIN переписаны простым языком: убраны термины `fallback`, «таймаут», «порог», «конфигурация» и технические формулировки автосохранения; пример тарифа теперь показывает готовое количество жетонов с правильным склонением. +- В `space_pixel` и встроенной резервной теме полностью отключены тени текста и обводка кнопок; светлый текст переведён в чистый белый, а текст на светлых и зелёных поверхностях — в более тёмный контрастный оттенок. Обновлённый PCK собран и установлен в `user://theme_dlc/active_theme.pck`. +- Исторические записи ниже описывают прежний инженерный UI на момент его реализации и считаются заменёнными этой записью. + +### 2026-08-24 — PIN перенесён в настройки приложения + +- Удалена зависимость сервисного входа от `EXCHANGER_SERVICE_OPERATOR_PIN` и `EXCHANGER_SERVICE_ENGINEER_PIN`. +- На вкладке «Общие» добавлены включение защиты и сброс PIN; изменения по-прежнему сохраняются автоматически. +- Первый вход после включения или сброса предлагает дважды ввести 4–12 цифр, затем открывает инженерные настройки; последующие входы проверяют PIN и блокируются на 30 секунд после пяти ошибок. +- В конфигурации версии 11 сохраняются только случайная 16-байтовая соль, PBKDF2-SHA256-хеш длиной 32 байта и 210000 итераций; открытый PIN не попадает в JSON, audit или логи. +- Одинаковая политика применяется к физическому IN0 и debug-действию F10; при выключенной защите они открывают настройки напрямую. +- Runtime-проверка прошла полный цикл создания, подтверждения и повторной проверки PIN; тестовая пользовательская конфигурация после проверки восстановлена. Сборка без предупреждений, 225/225 модульных тестов прошли, 17 аппаратных тестов безопасно пропущены без явного профиля запуска. + +### 2026-08-24 — Цифровые входы привязаны к хопперу + +- Добавлена именованная production-разводка: `IN0` — active-low сервисная кнопка, активный `IN1` (`бит 0`) — мало жетонов, `IN25` — active-low импульс выдачи. Позднее владелец уточнил, что эта пара относится ко второму хопперу; `IN2/IN24` зарезервированы для первого. +- `IN0` публикует одно событие только при переходе в активный уровень; debug-сборка открывает `Settings` напрямую, release-сборка использует защищённый путь `ServiceAccess → Settings`, а следующий фронт закрывает настройки после автосохранения. При настроенном входе IN0 дублирующий кадр `SERVICE` игнорируется, поэтому один физический нажим не выполняет два перехода. +- `IN1` обновляет `Enough/Low` только при реальном изменении и никогда не создаёт числовой остаток. +- `IN25` считает один жетон на active-low фронт только во время активной выдачи. В целевом `Hopper2Auto` кадры `HOPPER1` игнорируются; без исходного снимка выдача блокируется безопасной ошибкой. +- Быстрые входы резервно опрашиваются командой `91` каждые 100 мс; индексы, полярности и интервал вынесены в конфигурацию. Конфигурация версии 13 исправляет production-полярность на active-low: `IN1 bit 0 → Low`, `IN1 bit 1 → Enough`. +- Безопасная проверка COM3 прошла 9/9; текущий `IN1=0` корректно преобразован в `Enough`. Мотор, платёжные приёмники и банковский терминал не запускались. +- Сборка завершилась с 0 предупреждений и ошибок; модульный набор прошёл 212/212. + +### 2026-08-24 — Handshake сверен с Unity, Python и реальной платой + +- На дату записи Unity использовался как источник криптографической проверки `RAES`. Позднее актуальный `plate_config_app` стал источником обязательной startup-последовательности с баннером, паузой и `READY!`; AES-проверка Exchanger при этом сохранена. +- Exchanger теперь восстанавливает ключ как Unity. Контрольная пара спецификации `8C70…0F7A → 99ED…B0E1` воспроизводится точно. +- Probe на COM3 подтвердил `RAES == AES-256-ECB-Encrypt(07)`. Исторический переход в Ready сразу после `RAES` впоследствии отменён записью от 2026-08-31: актуальный контракт требует точный `READY!`. +- Реальный ответ цифровых входов имеет вид `INPUT` без обязательного пробела; parser принимает оба варианта и защищён регрессионными тестами. +- Безопасная аппаратная группа прошла 8/8: handshake, `91`, `140`, `150`, `160`, `309?`, `99` и три reconnect-цикла. Ни оплата, ни выдача не запускались. +- Сборка завершилась без предупреждений и ошибок; модульный набор прошёл 204/204. + +### 2026-08-24 — Первый безопасный прогон реальной платы + +- Windows определила контроллер как Silicon Labs CP210x на COM3; порт 115200 8N1/None открывается стабильно. +- Первый запуск обнаружил реальный Windows edge case: `SerialPort.Read` при штатном закрытии бросает `OperationCanceledException`. Worker теперь безопасно завершает поток; добавлены 6 регрессионных проверок, общий NUnit-набор вырос до 203/203. +- Первые восемь production-попыток стабильно получили `CHAL` и `RAES`, но завершились до `Ready`: обфусцированный массив ошибочно использовался как эффективный AES-ключ. Причина устранена последующей сверкой с Unity. +- Добавлен изолированный `HardwareProbe`: случайный `07`, ответ `08` через production AES-256 ECB/NoPadding, классификация `RAES` без сохранения сырых блоков. +- Первый probe подтвердил отсутствие `AUTH_CNT_OK` и несовпадение при ошибочном прямом ключе. После XOR `0x37` повторный probe подтвердил корректный `RAES`, а Safe прошёл 8/8 без обхода авторизации. +- Следующий аппаратный шаг: отдельно выполнить Interactive/Payment/Dispense/Cable с явными подтверждениями и физической подготовкой стенда. + +### 2026-08-24 — Завершён Этап 6 + +- Release-профиль получил borderless fullscreen, скрытый курсор, восстановление окна после focus/display/resolution change; `F10` жёстко ограничен debug-сборкой и состоянием Home. +- Добавлены Windows watchdog, установка/удаление задачи автозапуска и эксплуатационная инструкция; PowerShell разобран без ошибок, installer проверен через `-WhatIf`, watchdog — одноразовым процессным запуском. +- Первоначально реализованы физический `SERVICE` → PIN-клавиатура → роли Operator/Engineer, пять попыток и 30-секундная блокировка; последующая запись выше заменила environment-PIN единым PIN приложения. +- `SettingsScreen` завершён восемью вкладками, полной валидацией, инженерными COM/window настройками, safe reset, подтверждением dirty-exit, отдельным повторным подтверждением restart-only сохранения и итогом без автоматического restart/reconnect. +- Диагностика показывает версию 0.6.0, тему, безопасное состояние порта/соединения/запаса, последние очищенные предупреждения и тестовую выдачу одного жетона с двойным подтверждением. +- Добавлены безопасный audit конфигурации, уровни/лимиты журналирования, очистка по сроку и общему объёму; пути, значения, PIN, платёжные данные и сырые протокольные кадры не записываются. +- Ускоренный soak моделирует 1440 минут, 480 подтверждённых выдач и 10 000 циклов `SessionFlow`; process-runner прошёл 12/12 пятиисекундных сэмплов с пиком working set 217.73 МБ, CSV дополнительно исправлен и повторно проверен под русской локалью. +- Runtime QA пройдена на 720×1280 и 1080×1920: роли, Equipment/Diagnostics, field validation, discard/continue, test dispense и двухэтапное restart-only сохранение. Тестовые изменения пользовательской конфигурации восстановлены; game/editor logs чистые. +- Контрольная сборка завершилась с 0 ошибками и 0 предупреждениями; 197/197 NUnit-тестов прошли, 15 hardware-тестов безопасно пропущены без подключённой платы. +- Реальный 24-часовой wall-clock soak, проверка собственной экранной клавиатуры на физической + панели и поведение дисплея перенесены в аппаратную приёмку Этапа 8 и явно отмечены как внешняя + зависимость, а не незавершённая программная задача Этапа 6. + +### 2026-08-21 — Подтверждён профиль AES платы + +- Рабочая реализация владельца подтвердила `AES-256`, `CipherMode.ECB`, `PaddingMode.None` и шифрование одного 16-байтового блока через `TransformFinalBlock`. +- Существующий `Aes256EcbBlockCipher` уже полностью соответствовал этой реализации; `ControllerAesMode: "ECB"` включён по умолчанию. +- Конфигурация повышена до версии 6; старые пользовательские настройки с пустым AES-режимом автоматически мигрируют на `ECB`. +- Позднейшая сверка с Unity показала, что сохранённый массив нужно декодировать XOR `0x37`; после исправления старый `RAES`-пример и реальная плата совпали. + +### 2026-08-21 — Handshake приведён к фактическому порядку платы + +- На основании предоставленного тогда рабочего метода порядок был уточнён до `07 → CHAL → 08 → RAES`. Эта историческая схема заменена 2026-08-31 строгим startup-контрактом `banner → 2000 ms → 07/CHAL/08/RAES → READY!`. +- Добавлены состояния ожидания `CHAL` и доказательства платы; обязательное ожидание `AUTH_CNT_OK` впоследствии удалено по фактической трассе. +- Реализованы быстрый CHAL-timeout `min(1200, max(250, timeout/4))`, общий настраиваемый timeout и отмена ожидания при disconnect. +- Конфигурация обновлена до версии 5 с `HandshakeTimeoutMilliseconds: 5000`. +- Wire-симулятор и интеграционные тесты переведены на новый порядок; набор расширен до 98 тестов, включая закрытие порта при неверном доказательстве платы. + +### 2026-08-21 — Завершён Этап 3 + +- Документированный профиль протокола 2.3.5 закрыт: framing, parser, double handshake, платежи, обязательные `ASK:*`, Вендист, `SERVICE`, `INPUT` и legacy-хоппер отделены от транспорта и Godot Node. +- Добавлен `PeripheryControllerSimulator`, который проходит настоящий handshake и воспроизводит card success, malformed-кадр, бинарный датчик, полную и частичную выдачу без COM-порта. +- Протокольный адаптер игнорирует бизнес-кадры до криптографически подтверждённого `RAES`, подавляет повторный `DISPENSE`, не выполняет автоматический retry и блокирует legacy-хоппер после аппаратной ошибки. +- Добавлены типизированные команды status-запросов `140`, `150`, `160`, `99`; неизвестные форматы ответов остаются безопасно неподдерживаемыми. +- Внешние неопределённости AES, силового канала и физической распиновки вынесены в аппаратную проверку следующих этапов и не подменены предполагаемыми командами. +- Набор расширен до 91 теста; проверены все результаты card-сессии, несовпадение суммы, pre-auth-фильтрация, service/error, malformed recovery, границы параметров, at-most-once и partial hopper failure. + +### 2026-08-21 — Фиктивный числовой остаток полностью удалён + +- Аппаратная граница использует только `MachineStockLevel`: `Enough`, `Low` или технический `Unknown`. +- Числовой остаток, `MachineStockSnapshot`, `ExactCount`, `Empty`, `Pricing.InitialStock` и пороги удалены из real/mock-контроллеров, сессии, UI и конфигурации. +- Добавлен parser ответа `INPUT`/`INPUT `, polling командой `91` и конфигурация номера входа/полярности датчика. +- UI и mock работают только с «МНОГО»/«МАЛО»; успешная выдача не изменяет уровень без нового сигнала датчика. +- `Unknown` блокирует начало оплаты, `Low` разрешает работу без ложной проверки точного остатка. +- Тестовый набор расширен до 77 тестов, включая polling датчика и сброс уровня в `Unknown` при disconnect. + +### 2026-08-21 — Добавлен предоставленный ключ контроллера + +- 32-байтовый `AesEncryptedKey` добавлен в `PeripheryControllerSecurity` и документацию протокола. +- Переменная `EXCHANGER_CONTROLLER_AES_KEY` сохранена как необязательное переопределение для другой ревизии платы. +- Позднее выяснилось, что массив является обфусцированным: после XOR `0x37` AES-256 ECB/NoPadding воспроизводит пример `RAES` и обмен с реальной платой. + +### 2026-08-21 — Начата интеграция периферийного контроллера 2.3.5 + +- Добавлен `System.IO.Ports` 8.0.0 и реальный Windows-транспорт 115200 8N1 без flow control. +- COM-чтение/запись выполняются одним worker-потоком; события передаются в Godot через очереди и главный `_Process`. +- Реализован ASCII-фреймер `CR`/`LF`, timeout 100 мс, лимит кадра и безопасное восстановление после мусора/переполнения. +- Добавлены parser/formatter команд `READY`, handshake, `MONEY:*`, `ASK:*`, `SERVICE`, Вендиста и legacy-хоппера. +- Реализован double-handshake state machine и AES-256 ECB cipher; на этом шаге активация ещё ожидала подтверждения режима, которое владелец предоставил позднее. +- `PeripheryMachineController` управляет smart-монетником, купюроприёмником, Вендистом, keep-alive и обязательными подтверждениями платежей. +- Приём оплаты блокируется, пока не настроен безопасный production-способ выдачи; автоматический retry выдачи отсутствует. +- Добавлен периодический reconnect COM-порта и повторная авторизация после подключения. +- Тестовый набор расширен до 72 тестов, включая framing, команды, handshake, AES-вектор, проверку встроенного ключа, платежи, keep-alive, disconnect во время выдачи и блокировку небезопасной выдачи. + +### 2026-08-21 — Добавлен безопасный контекст и журнал операций + +- Каждая cash/card-сессия получает уникальный локальный `OperationId`; начало и единственный итог публикуются типизированными снимками. +- Добавлены `SessionErrorCode`, безопасные пользовательские тексты и рекомендации `ReturnHome`/`TryAnotherPaymentMethod`/`ContactSupport`; сырая ошибка оборудования не попадает в UI. +- Отдельный JSONL-журнал `user://logs/operations.jsonl` хранит только безопасные поля и при старте закрывает незавершённые записи как `UnknownAfterRestart`, не повторяя оплату или выдачу. +- `IMachineController` и `MockMachineController` поддерживают событие потери связи; потеря во время выдачи приводит к `DispenseStatusUnknown` и запрещает предполагать результат. +- Debug-панель карточного сценария позволяет вручную воспроизвести успех, отказ, полную/частичную ошибку выдачи и потерю связи. +- Правила восстановления и ручная приёмка зафиксированы в `docs/operations/RECOVERY_AND_MOCK_QA.md`. +- Набор расширен до 45 тестов; проверены уникальность идентификаторов, единственный финальный исход, typed errors, очистка подписок и восстановление JSONL. + +### 2026-08-21 — Автоматизировано тестирование mock-среза + +- Подключены NUnit 4.6.1, NUnit3TestAdapter 6.2.0 и Microsoft.NET.Test.Sdk 18.9.0 в отдельном `Exchanger.Tests`. +- Бизнес-логика вынесена из Godot-узла в чистый `SessionFlow`; `SessionController` остался тонким адаптером `_Process` и журналирования. +- Добавлен `IMonotonicClock`, благодаря которому таймауты 45/120 секунд проверяются мгновенно управляемыми часами. +- `PricingPolicy` отделяет проверку суммы и расчёт базовых/бонусных жетонов от UI и Godot. +- Набор из 37 тестов покрывает конфигурацию, тарифы, cash/card success, decline, timeout, неподтверждённое состояние запаса, duplicate/late events, частичную выдачу, сброс данных и утечки подписок. +- Автоматически проверяется наличие восьми сцен и четырёх ресурсов тем; семь пользовательских экранов отдельно прошли runtime smoke-загрузку через `godot-ai`. +- В тот момент mock временно проверял выбранный пакет против числового запаса; позже это поведение удалено после уточнения, что датчик сообщает только «много/мало». +- `MockMachineController` получил настраиваемую задержку и детерминированные сценарии полной/частичной ошибки выдачи; полный отказ runtime-проверен до корректного `ErrorScreen`. +- Итоговые `dotnet test`, запуск проекта и Godot editor/game logs проходят без ошибок и предупреждений. + +### 2026-08-21 — Завершён Этап 2 + +- Добавлена типизированная аппаратная граница `IMachineController` и `MockMachineController` для баланса, запаса, карточного результата и подтверждения выдачи без предположений о wire-протоколе. +- Реализован `SessionController` с явными cash/card состояниями, монотонными таймаутами, сбросом временных данных и защитой от повторных команд. +- Добавлены `CardCustomAmountScreen`, `CardTerminalScreen`, `SuccessScreen` и `ErrorScreen`; все экраны подключены через `ScreenRegistry`. +- Наличная ветка получила debug-ввод купюр и явное подтверждение выдачи; карточная ветка — debug-результаты терминала. +- Реализован автономный `AdvertisementPlayer`: локальный плейлист, постер/текстовый fallback, беззвучный режим по умолчанию и остановка декодирования вне `HomeScreen`. +- Runtime пройдены cash success, card success, card decline и custom amount; проверены выдача только после подтверждения, отображение запаса и возвраты на Home. +- Визуальная QA 720×1280 при логическом viewport 1080×1920 выявила и устранила неравномерную цифровую клавиатуру; финальная сетка состоит из трёх равных колонок. +- Контрольная C#-сборка и Godot runtime-логи чистые; новые NuGet-зависимости не потребовались. + +### 2026-08-20 — Первый пакет Этапа 2 + +- Логический viewport переведён на 1080×1920, debug-window — на 720×1280; добавлена миграция пользовательской конфигурации до версии 2. +- Добавлены Input Actions `kiosk_back` и `debug_cycle_theme`. +- Реализованы Autoload `ScreenManager`, централизованный `ScreenRegistry`, общий `ScreenHost` и UI fade-переходы. +- После runtime-теста добавлен `TransitionInputBlocker`, устраняющий случайный выбор элемента под координатой отпущенного тача на новом экране. +- Удалён ландшафтный `StartScreen`; созданы `HomeScreen`, `CashPaymentScreen` и `CardAmountScreen`. +- Добавлены конфигурируемые тарифы, бонусы, карточные пресеты, брендинг, настройки промо и `TokenStockStatus`. +- Космическая тема переведена с фиолетового прототипа на тёмно-синюю/салатовую палитру референса. +- Визуально и через runtime UI проверены Home → Cash → Home → CardAmount → Home на 720×1280 при логическом viewport 1080×1920. +- Разрешение на необходимые NuGet-пакеты получено; в текущем пакете новые зависимости не потребовались. + +### 2026-08-20 — Завершён Этап 0 + +- Инициализирован локальный Git-репозиторий без назначения remote и создания первого коммита. +- `.agents/AGENTS.md` признан проектным файлом и исключён из списка игнорирования. +- Создан `docs/architecture/decisions.md` с базовыми архитектурными решениями. +- До появления целевого оборудования принята универсальная, конфигурируемая стратегия без привязки к конкретному ПК, GPU, DPI или тач-контроллеру. +- Реализация wire-протокола и COM перенесена в Этапы 3–4; входом станет документация и список команд, которые владелец позднее добавит в `references/`. +- Зафиксировано, что все аппаратные данные поступают ПК от контроллера и преобразуются внутри приложения в типизированные события. + +### 2026-08-20 — Инициализация дорожной карты + +- Изучено исходное ТЗ и текущее состояние проекта. +- Исторически был зафиксирован Compatibility renderer вместо противоречащего ему Forward+; текущий режим — Mobile/Vulkan для Native Video. +- Сформирована архитектура тем, навигации, сессии и аппаратного слоя. +- Определены этапы разработки, критерии приёмки, риски и вопросы к владельцу продукта. + +### 2026-08-20 — Завершён Этап 1 + +- Исторически были настроены viewport 1920×1080, Compatibility, production fullscreen и debug-window профиль; текущий рендерер — Mobile/Vulkan. +- Созданы `App`, `StartScreen`, `TouchInputGuard`, `AppSettings` и журнал с ротацией. +- Реализованы `VendingThemeDefinition`, Autoload `ThemeManager`, базовая и космическая темы. +- Добавлен анимированный shader-фон, космические частицы и статический fallback для облегчённого режима. +- Созданы `IHardwarePort`, рабочая mock-реализация и безопасные Windows/Android каркасы. +- Проверены C#-сборка без предупреждений, main scene, runtime-логи, смена тем, кнопка «Начать», mock PING и создание пользовательской конфигурации. +- Визуально проверены 1280×720, 1024×768 и borderless fullscreen 2560×1440. +- Подтверждено, что для реального Windows SerialPort потребуется предварительно согласованный NuGet-пакет `System.IO.Ports`. + +### 2026-08-20 — Исправлена корневая документация + +- `README.md` полностью заменён документацией Exchanger на русском языке. +- Добавлены описание продукта, текущее состояние, запуск, конфигурация, журналы, архитектура тем и аппаратного слоя. +- Удалён случайно установленный корневой `LICENSE` GodotX Toast. +- Лицензии сторонних компонентов в `addons/` и `godot-ai-LICENSE.txt` сохранены. +- Зафиксировано отсутствие объявленной собственной лицензии Exchanger. + +### 2026-08-20 — Учтены визуальные референсы аппарата + +- `references/` добавлен в `.gitignore` как локальный источник концептов, не предназначенный для production. +- Проанализированы семь макетов UI 720×1280, рендер корпуса и видео 1080×1920/50 FPS длительностью 32,16 секунды. +- Целевая ориентация изменена с ландшафтного технического прототипа на портретную 9:16. +- Зафиксированы домашний экран, наличная ветка, карточные суммы/клавиатура/терминал, отказ оплаты, запас жетонов, бонусы, промо-блок и поддержка. +- План Этапов 2, 3, 5 и 7 переработан с учётом реального корпуса и пользовательского потока. +- Подробный разбор сохранён в `docs/REFERENCE_ANALYSIS.md`. + +### 2026-08-20 — Фон приведён к референсам + +- `AnimatedBackground` заменён на `StaticBackground`. +- Из активной сцены и `VendingThemeDefinition` удалены фоновые shader-материалы и частицы. +- Удалены ставшие ненужными shader/particle-ресурсы обеих тем. +- Сохранена поддержка статической текстуры фона и отдельной `PackedScene` с анимированными спрайтами. +- Промо-блок отделён в архитектуре от фонового слоя приложения. + +### 2026-08-21 — Завершена программная часть Этапа 4 + +- В `IMachineController` добавлено безопасное состояние соединения `Disconnected/Authenticating/Ready/Faulted`, одинаковое для mock и реального протокольного адаптера. +- Потеря связи переводит бинарный запас в `Unknown`, блокируя начало новой оплаты без вымышленного остатка. +- Добавлен атомарный `ConnectionStatusIndicator`: в production он не занимает внимание при `Ready`, но показывает авторизацию, обрыв и ошибку; debug также показывает штатное подключение. +- Интеграционный тест выполняет 200 reconnect-циклов с обрывом во время выдачи и подтверждает отсутствие автоматического повтора и позднего завершения операции. +- Полный набор расширен до 100 тестов; сборка без предупреждений, Godot 4.7.1 runtime и журналы чистые, индикатор визуально проверен на 720×1280. +- Физический длительный прогон и отключение USB-кабеля остаются внешней приёмкой до появления контроллера. + +### 2026-08-21 — Подготовлена аппаратная приёмка платы + +- Добавлен отдельный проект `Exchanger.HardwareTests` из 15 NUnit-проверок production-пути `SerialPortHardware → ControllerAuthenticator → PeripheryMachineController`. +- Безопасная группа проверяет COM 115200 8N1, production AES-handshake, `INPUT`, status-команды, закрытие и повторную авторизацию. +- Ручные группы покрывают SERVICE, монетник, купюроприёмник и оба бинарных состояния датчика; отсутствующую периферию можно пропустить независимо. +- Реальная карточная операция, физическая выдача и отключение USB требуют разных явных подтверждений и не могут стартовать из обычного `dotnet test`. +- PowerShell-runner создаёт локальный TRX-отчёт в `artifacts/board-tests/`; сырые кадры, AES-данные и секреты в отчёт не попадают. +- Полная инструкция запуска и порядок приёмки сохранены в `docs/hardware/BOARD_ACCEPTANCE_TESTS.md`. + +### 2026-08-21 — Разработка тем полностью вынесена из Exchanger + +- Каталог `themes/`, встроенные `.tres`-темы и debug-переключение удалены из основного проекта. +- Exchanger содержит только программную fallback-тему и runtime-контракт одного внешнего DLC; списка тем и горячего переключения больше нет. +- Конфигурация версии 7 читает `Themes.ExternalDlcPath` из пользовательского `appsettings.json`; по умолчанию используется `user://theme_dlc/active_theme.pck`. +- Реализован формат `ExchangerThemeDlc` v1: `.pck` до 512 МиБ, обязательный manifest и `Theme`, необязательные статическая текстура и `PackedScene` анимированных спрайтов. +- Пакет монтируется с `replace_files=false`; пути ограничены `res://exchanger_theme_dlc/`, повреждённый DLC безопасно оставляет fallback. +- В соседнем `../ExchangerThemeDlcBuilder` создан независимый Godot 4.7-проект с manifest, примером темы, статическим фоном и PowerShell-сборщиком/установщиком. +- Реальный `.pck` успешно собран и загружен Exchanger через production loader; fallback отдельно визуально проверен в Godot на 720×1280. +- Набор расширен до 105 автоматических тестов плюс 15 отключённых по умолчанию аппаратных проверок; solution собирается без предупреждений. + +### 2026-08-21 — Создана первая внешняя тема `space_pixel` + +- В независимом `../ExchangerThemeDlcBuilder` обработаны предоставленные 46 PNG, статический фон 1080×1920, кириллический pixel-font и восемь покадровых последовательностей. +- Оригиналы сохранены в `themes_src/space_pixel/`; runtime-копии получили стабильные ASCII-пути и не зависят от основного проекта. +- Реализованы `ui_theme.tres`, статический фон и пассивная decoration-сцена мерцающих звёзд и пролетающих НЛО без скриптов, шейдеров, частиц и видео. +- В manifest v1 добавлен обратно совместимый флаг `UseNearestTextureFilter`; `space_pixel` включает nearest, остальные DLC сохраняют стандартную фильтрацию. +- Экспорт текстовых `.tres/.tscn` в бинарный формат отключён, поэтому переносимый PCK загружается по стабильным путям без cross-project UID-предупреждений. +- `build/active_theme.pck` собран и независимо проверен production-загрузчиком Exchanger: тема активируется, приложение завершает smoke-run без ошибок и предупреждений. +- Контекстные анимации оплаты подготовлены в builder, но остаются не подключёнными до появления именованных screen-specific слотов в следующей версии DLC-контракта. +- В локальный игнорируемый каталог `themes_src/space_pixel/references/` скопированы восемь JPG и видео интерфейса; reference-медиа не экспортируются в PCK. +- После просмотра всех макетов и 64 кадров видео тема получила семантические вариации `ScreenTitle`, `PanelTitle`, `PanelText`, `SupportText`, `PrimaryButton`, `CompactButton`, `BackButton` и `WhitePanel`. +- Preview перестроен по наличному экрану референса в 720×1280; runtime-декорация при этом сохраняет координаты host-приложения 1080×1920 и масштабируется только внутри preview. +- Для полного reference-look основному Exchanger позднее потребуется назначить semantic `theme_type_variation`, вынести общий footer и добавить screen-specific слоты анимаций; точный список узлов зафиксирован в builder `docs/SPACE_PIXEL.md`. +- Builder-preview расширен до переключаемой галереи всех семи пользовательских экранов темы: Home, Cash, CardAmount, CardCustom, CardTerminal, Success и Error. +- В builder-preview добавлен live reload: сохранённые изменения Theme, изображений и preview-сцен автоматически появляются в запущенной галерее без ручного перезапуска и без сброса выбранной вкладки; preview-инструмент не экспортируется в DLC. +- Layout всех семи preview-сцен приведён к общему правилу: после зелёной шапки сохраняется заметный белый отступ, кнопки не прилипают к заголовкам, а изображения и экранные анимации центрируются относительно внутренней области `WhitePanel`. + +### 2026-08-24 — Начата реализация сервисных настроек + +- Конфигурация повышена до версии 8 и получила `AudioSettings`: master volume, master mute и отдельную громкость промо-ролика. +- Добавлен чистый C# `SettingsService` с изолированной рабочей копией и неизменяемым активным снимком, атомарной записью через временный файл, `.bak` предыдущей корректной версии и восстановлением после повреждения JSON. +- `App` загружает настройки через новый сервис и применяет master volume к Godot audio bus; `AdvertisementPlayer` отдельно применяет громкость промо-ролика, сохраняя существующий ad mute. +- Миграция реального пользовательского файла 7 → 8 проверена в runtime: создана резервная версия 7, временный файл удалён, домашний экран и журналы Godot чистые. +- NUnit-набор расширен до 119 тестов: добавлены аудиограницы, working-copy isolation, round-trip сохранения, backup, восстановление из backup/defaults, защита от конфигурации будущей версии, безопасный запуск при невозможности записи и smoke-проверка новой сцены. +- Добавлен атомарный `SettingsScreen` для звука: рабочая копия, live-preview, сохранение через `SettingsService`, отмена с восстановлением активного снимка и безопасный синусоидальный тестовый сигнал. +- Master и промо разведены по отдельным Godot audio buses; bus промо-ролика отправляется в Master и меняется независимо без двойного пересчёта громкости в проигрывателе. +- Вход по `F10` возможен только из Home и только при `OS.IsDebugBuild()`; production-вход остаётся закрытым до реализации отдельной авторизации сервисного персонала. +- Экран и действия сохранения/отмены проверены в runtime на 1080×1920 и 720×1280; повторный тестовый сигнал и оба аудиоканала не оставляют ошибок в Godot game/editor logs. +- `SettingsScreen` расширен вкладкой «Тарифы и бонусы»: цена жетона, динамические строки порог → бонус, добавление, удаление, сортировка перед сохранением и preview типовых сумм через production `PricingPolicy`. +- В интерфейсе явно показано правило расчёта: из подходящих строк берётся один наибольший бонус, строки не суммируются. +- Добавлен чистый `PricingSettingsValidator`: блокирует нулевую/чрезмерную цену, цену выше максимальной суммы, пороги вне диапазона, отрицательные/чрезмерные бонусы и дубли порогов; ошибки цены и каждой строки показываются рядом с полем. +- Сохранённые тарифы безопасно применяются только из Home: заново настраиваются `SessionController`, наличный, карточный и ручной экраны, после чего восстанавливаются stock/connection state; активную операцию редактор открыть не может. +- NUnit-набор расширен до 126 тестов; тарифный UI проверен в runtime на 720×1280 и 1080×1920, включая add/remove, duplicate validation, disabled Save, preview, Cancel и сохранение без ошибок Godot. +- Конфигурация повышена до версии 9 и получила отдельный блок `Payments`; runtime-миграция реального файла 8 → 9 создала корректную резервную версию 8 без оставшегося временного файла. +- В `SettingsScreen` добавлена вкладка «Оплата»: независимое включение наличной и карты, максимальная карточная сумма, шаг ручного ввода, динамический редактор пресетов и три пользовательских таймаута с пояснениями безопасных диапазонов. +- Карточные пресеты сортируются, проверяются на диапазон, кратность шагу и дубли. Пустой список разрешён, поскольку карточная ветка сохраняет действие «Другая сумма». +- `PaymentSettingsValidator` запрещает отключение обоих способов оплаты и проверяет таймауты; `PricingSettingsValidator` дополнен проверкой максимума, шага и каждой строки пресета. +- `SessionFlow` отклоняет отключённый способ до начала операции и обращения к контроллеру, а `HomeScreen` сразу блокирует соответствующую кнопку вместе с существующей блокировкой по запасу. +- Настройки безопасно применяются только из Home; runtime-проверка временно отключила наличную оплату, подтвердила блокировку кнопки и восстановила исходную конфигурацию. +- NUnit-набор расширен до 137 тестов; 15 тестов физической платы по-прежнему безопасно пропускаются без явного флага. +- Экран «Оплата», add/remove, ошибки способов оплаты, диапазонов и disabled Save проверены в Godot 4.7.1 на 720×1280 и 1080×1920; финальные game/editor logs чистые. +- `SettingsScreen` получил стартовую вкладку «Общие» с четырёхкнопочной навигацией, однострочными полями названия, подзаголовка и контакта техподдержки, ограничениями длины и отдельным preview домашнего экрана. +- Добавлен чистый `BrandingSettingsValidator`: обязательность, максимальная длина и запрет управляющих символов проверяются до записи; runtime-нормализация сворачивает пробелы и безопасно ограничивает текст из внешнего JSON. +- Сохранение общих данных проверено сквозным runtime-сценарием до `HomeScreen`; тестовые значения после проверки заменены исходными, пользовательская конфигурация версии 9 не оставила временного файла. +- NUnit-набор расширен до 146 тестов; вкладка «Общие», пустое поле, disabled Save, живой preview и сохранение проверены в Godot 4.7.1 на 720×1280 и 1080×1920, журналы чистые. +- `SettingsScreen` получил пятую вкладку «Промо»: включение блока, отдельный mute промо-роликов, fallback-текст, необязательный poster, динамический OGV-плейлист до 12 строк и сводный preview состояния. +- Новый `AdvertisementSettingsValidator` принимает только `res://`, `user://` или абсолютные локальные пути, запрещает traversal/сетевые URL, проверяет форматы PNG/JPG/JPEG/WEBP и OGV, существование файлов, дубли и длины до сохранения. +- Отключённое промо намеренно позволяет сохранить временно недоступные пути: `AdvertisementPlayer` в этом режиме не загружает poster, не создаёт видеопоток и показывает «ПРОМО ОТКЛЮЧЕНО». +- `AdvertisementPlayer` дополнен загрузкой внешнего raster-постера через `Image` и локального OGV через `VideoStreamTheora`; диагностическое предупреждение больше не раскрывает полный путь файла. +- Runtime-проверка покрыла пустой fallback, отсутствующий poster, пустой/отсутствующий промо-ролик, add/remove, disabled Save и безопасное сохранение отключённого блока; после теста исходные настройки промо восстановлены. +- NUnit-набор расширен до 157 тестов; вкладка «Промо» визуально проверена в Godot 4.7.1 на 720×1280 и 1080×1920, game/editor logs чистые. +- `SettingsScreen` получил шестую вкладку «Тема»: включение единственного внешнего DLC, путь к `.pck`, статус доступности пакета и облегчённый режим эффектов. +- Новый `ThemeSettingsValidator` принимает только `user://` либо абсолютный локальный путь к `.pck`, запрещает traversal и управляющие символы; отсутствие будущего пакета не мешает сохранить корректный путь и безопасно оставить fallback-тему. +- В UI и runtime зафиксирована граница применения: `ReducedEffects` переключается сразу и откатывается кнопкой «Отменить», а включение DLC и путь применяются только при следующем запуске без самопроизвольной перезагрузки темы. +- NUnit-набор расширен до 166 тестов; неверный путь, отключённый DLC, live-preview/откат и внешний вид вкладки проверены в Godot 4.7.1 на 720×1280 и 1080×1920, пользовательские настройки восстановлены, game/editor logs чистые. + +### 2026-08-24 — Начат Этап 7 и синхронизирован host-контракт тем + +- Все девять runtime-экранов получили семантические `theme_type_variation`; встроенная тема + регистрирует их как безопасные наследники базовых Godot-классов, поэтому fallback не изменился. +- Динамически создаваемые строки настроек также используют `PanelText` и `CompactButton`, при этом + `CheckButton` и `OptionButton` сохраняют собственные базовые типы. +- `ScreenManager` отключает processing скрытого экрана и включает его только перед показом нового; + runtime-переход Home → Settings подтвердил один активный экран и восемь отключённых. +- Зафиксирован debug-baseline на 720×1280 и 1080×1920: стабильные 60 FPS, до 37 draw calls и + менее 1,4 мс process time; условия и ограничения записаны в + `docs/operations/PERFORMANCE_BASELINE.md`. +- Визуально проверены fallback Home 720×1280 и Settings 1080×1920 после внедрения семантических + типов: элементы читаемы, панели и кнопки не пропали, наложений не обнаружено. +- Solution собирается без предупреждений; 223 unit/integration-теста проходят, 17 физических + hardware-тестов остаются безопасно пропущенными без явных разрешающих флагов. +- Decoration внешнего DLC получила жёсткий runtime-бюджет узлов/спрайтов/кадров и частоты; текущая + `space_pixel` занимает лишь 5 узлов, 4 CanvasItem, 1 AnimatedSprite2D и 2 кадра при 1 FPS. +- Runtime-аудит всех девяти экранов устранил неравные колонки цифровых клавиатур и подтвердил + отсутствие мелких пользовательских кнопок и логики, зависящей от hover. +- Соседний Theme Builder синхронизирован с девятью экранами и восемью разделами Settings, + расширенными variations, hot reload и export-аудитом; PCK установлен в стандартный `user://`. +- `space_pixel` загружен production loader без UID-предупреждений; визуально проверены Home, + ServiceAccess и Settings/Equipment на 720×1280, а full/reduced профиль сохраняет 60 FPS. +- После дополнительного host-QA исправлен контраст CheckButton; финальный PCK (167280 байт, + 30 entries) установлен в `user://`, все 8 Settings-разделов и SERVICE проходят runtime smoke. + +### 2026-08-24 — Начат Этап 9: воспроизводимый Windows export + +- Добавлен preset `Windows x64` и `tools/export-windows.ps1`, который собирает release из + очищенной staging-копии, не меняя рабочий проект и не включая editor-autoload. +- Из PCK исключены `references/`, тесты, docs, tools, artifacts, agent-файлы и все addons; + проверенный каталог не содержит test DLL или addon-файлов. +- Первая self-contained сборка 0.6.0 успешно создана: 189 файлов, 180,8 МиБ, внутри присутствуют + `Exchanger.dll`, `GodotSharp.dll` и `System.IO.Ports.dll`. +- Экспортированный `Exchanger.exe` прошёл headless smoke-run с exit code 0; порядок повторной + сборки и pre-release проверки записан в `docs/operations/WINDOWS_EXPORT.md`. +- Финальный export после semantic/touch-правок повторно собран в + `artifacts/windows/Exchanger-0.6.0-20260824-163811`: 189 файлов, 180,8 МиБ, exit code 0. +### 2026-09-07 — Составные действия интерактивного питомца переданы теме + +- Добавлен обратно совместимый optional composite contract: тема владеет последовательностью + клипов и визуальных преобразований, а Exchanger передаёт scoped runtime для проверенного движения + anchor, политик ввода/границ/опор и посадки на доступную поверхность. +- `space-pixel` реализует `interact`: условный поворот, `come_closer` с scale ×2, повтор `action`, + вычисляемый проход `falling` через низ/верх экрана без промежуточных опор, `landing` на самой + высокой опоре и возврат в `idle`; reduced-effects получает сокращённую ветку. +- Runtime автоматически инвалидируется при смене экрана/темы, drag и конфликтующем действии; + темы без нового API сохраняют прежний одиночный `interact` fallback. +- NUnit и полный `InteractivePetBehaviorSmoke` проверяют выбор верхней опоры, PCK-контракт, + scale ×2, вертикальный wrap, точный порядок клипов и сохранение прежних drag/drop, маршрутов, + смены экранов и четырёх циклов празднования. + +### 2026-09-07 — Host синхронизирован с актуальными документами и PCK темы + +- Подтверждён актуальный контракт: 481 immutable binding + 17 обязательных supplemental ID; + `Sync-HostBindingContract.ps1` теперь явно исключает supplemental-набор из JSON-генерации, а + `Test-PackagedBindingContract.ps1` защищает все 17 ID от случайного попадания в каталог. +- Зафиксирован trusted runtime без устаревшего decoration budget. `space-pixel` публикует + 22 анимации/414 кадров и новые имена walking start/stop через semantic mapping; app-код не + привязывается к конкретным именам клипов темы. +- Свежий `space-pixel.pck` 1658512 байт, SHA-256 + `76518563591159EC4B8087911D2BB29924BC29C12AAA4FF1544D97ED01648E91`, прошёл полный + `InteractivePetBehaviorSmoke` по явному пути на mock-оборудовании. +- `PaymentRewardFormattingSmoke` больше не сохраняет пользовательские Settings и сравнивает + наличный/карточный формат на фактическом пресете и бонусном правиле вместо жёсткого ожидания + нулевого бонуса. + +### 2026-09-08 — Приземление и простой питомца включены в обычное поведение + +- После падения при перетаскивании или смене экрана host проигрывает цепочку + `falling → landing → idle`; `landing` выполняется один полный цикл, а `idle` остаётся состоянием + ожидания до следующего автономного действия. +- Старые темы без анимации `landing` продолжают сразу переходить в `idle`. +- Запрошенные во время падения четыре цикла `dancing` начинаются только после завершения + приземления. +- Runtime-smoke с актуальным `space-pixel.pck` и mock-оборудованием подтвердил touch drag, + смену экранов, `falling → landing → idle`, отложенный танец и composite action. Debug и Release + прошли по 488/488 NUnit-тестов; 18 аппаратных тестов в каждой конфигурации пропущены. + +### 2026-09-08 — Вероятностный простой после ходьбы питомца + +- После завершения маршрута host с вероятностью 35% выбирает `idle` на 3–5 секунд, а в остальных + случаях — `sitting` на 1,5–3,5 секунды. Темы без `sitting` безопасно используют `idle`. +- `InteractivePetBehaviorSmoke` допускает оба корректных результата маршрута и продолжает + проверять `falling → landing → idle`. Unit-тесты фиксируют границу вероятности. +- Godot 4.7.1 начал штатно добавлять `unique_id` в заголовки узлов `.tscn`; хрупкая проверка + фиксированного футера Settings адаптирована к дополнительным атрибутам без изменения сцены. +- Debug и Release прошли по 496/496 NUnit-тестов; 18 аппаратных тестов в каждой конфигурации + пропущены. Runtime-smoke с новым `space-pixel.pck` на mock-оборудовании завершился успешно. + +### 2026-09-09 — Действие питомца во время подъёма и спуска + +- На каждом ненулевом ребре подъёма или спуска host выбирает случайную точку между 20% и 80% + пути, останавливает перемещение и выполняет `climbing_action_start → climbing_action → + climbing_action_stop`; средний клип проигрывается один полный цикл. +- После stop возобновляется исходная анимация направления и продолжается тот же маршрут. Для + старых тем возможность включается только при наличии всех трёх действий, поэтому частичная + последовательность не возникает. +- Reduced-effects теперь действительно исключает автономный подъём сразу после landing, но не + блокирует явно запрошенные маршруты и их climbing-action. +- Debug и Release прошли по 529/529 NUnit-тестов. Полный `InteractivePetBehaviorSmoke` с явным + актуальным `space-pixel.pck` и mock-оборудованием подтвердил порядок клипов, неподвижность + anchor во время sequence, продолжение маршрута, смены экранов и составное взаимодействие. diff --git a/addons/godot_ai/LICENSE b/addons/godot_ai/LICENSE new file mode 100644 index 0000000..7806d22 --- /dev/null +++ b/addons/godot_ai/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Godot AI contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/addons/godot_ai/README.md b/addons/godot_ai/README.md new file mode 100644 index 0000000..f8a730d --- /dev/null +++ b/addons/godot_ai/README.md @@ -0,0 +1,53 @@ +# Godot AI + +Connect AI assistants to a live Godot editor via the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). + +Godot AI bridges Claude Code, Codex, Antigravity, DeepSeek Harness, and other MCP clients with your editor — inspect scenes, create nodes, modify properties, run tests, search project files, and more, all from a prompt. + +## Quick Start + +1. Copy `addons/godot_ai/` into your project's `addons/` folder +2. Enable the plugin: **Project > Project Settings > Plugins > Godot AI** +3. Pick your MCP client in the **Godot AI** dock and press **Configure** + +The plugin auto-starts the MCP server and connects over WebSocket. No manual configuration required. + +## Requirements + +- Godot 4.5+ (4.7+ recommended) +- [uv](https://docs.astral.sh/uv/) (used to install the Python server) +
+ Install uv + + **macOS / Linux:** + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + + **Windows (PowerShell):** + ```powershell + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` + + **Homebrew (macOS / Linux):** + ```bash + brew install uv + ``` + + **pipx:** + ```bash + pipx install uv + ``` + + See the [uv install docs](https://docs.astral.sh/uv/getting-started/installation/) for more options. + +
+- An MCP client ([Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [Codex](https://openai.com/index/codex/) | [Antigravity](https://www.antigravity.dev/)) + +## Documentation + +Full documentation, contributing guide, and source code: [github.com/hi-godot/godot-ai](https://github.com/hi-godot/godot-ai) + +## License + +[MIT](LICENSE) diff --git a/addons/godot_ai/client_configurator.gd b/addons/godot_ai/client_configurator.gd new file mode 100644 index 0000000..58ae129 --- /dev/null +++ b/addons/godot_ai/client_configurator.gd @@ -0,0 +1,1879 @@ +@tool +class_name McpClientConfigurator +extends RefCounted + +## Public facade for the MCP client configuration system. +## +## Per-client logic lives in clients/*.gd (one descriptor per client) and is +## dispatched through clients/_registry.gd. This file: +## - owns server-side identifiers (SERVER_NAME, HTTP/WS port helpers) +## - registers the EditorSettings port overrides and resolves the live +## port/URL via `http_port()` / `ws_port()` / `http_url()` +## - keeps server-launch discovery (.venv → uvx → system godot-ai) +## - exposes string-id wrappers around configure / check_status / remove / +## manual_command so callers don't need to touch the registry directly +## +## To add a new client: drop a file in clients/, then preload it in +## clients/_registry.gd. No edits required here. + +const Client := preload("res://addons/godot_ai/clients/_base.gd") +const ClientRegistry := preload("res://addons/godot_ai/clients/_registry.gd") +const JsonStrategy := preload("res://addons/godot_ai/clients/_json_strategy.gd") +const TomlStrategy := preload("res://addons/godot_ai/clients/_toml_strategy.gd") +const YamlStrategy := preload("res://addons/godot_ai/clients/_yaml_strategy.gd") +const DshStrategy := preload("res://addons/godot_ai/clients/_dsh_strategy.gd") +const CliStrategy := preload("res://addons/godot_ai/clients/_cli_strategy.gd") +const ManualCommand := preload("res://addons/godot_ai/clients/_manual_command.gd") +const CliFinder := preload("res://addons/godot_ai/clients/_cli_finder.gd") +const WindowsPortReservation := preload("res://addons/godot_ai/utils/windows_port_reservation.gd") +const PortResolver := preload("res://addons/godot_ai/utils/port_resolver.gd") + +const SERVER_NAME := "godot-ai" + +## Fallback ports. Live port selection goes through `http_port()` / `ws_port()`, +## which read overrides from EditorSettings first. Users on Windows whose 8000 +## is grabbed by Hyper-V / WSL2 / Docker can pick a different port in +## Editor Settings > Plugins > godot_ai without touching code. See #146 for +## the Windows-reservation diagnostics this is the escape hatch for. +const DEFAULT_HTTP_PORT := 8000 +const DEFAULT_WS_PORT := 9500 +const STARTUP_TRACE_ENV := "GODOT_AI_STARTUP_TRACE" +const MIN_PORT := 1024 +const MAX_PORT := 65535 +## Cap on `can_bind_local_port` probes per `suggest_free_port` call so a +## pathological run of occupied ports can't stall the (cold-path) caller. +## 64 localhost binds are sub-millisecond; finding a free port realistically +## takes one or two probes, so this only bounds the worst case. +const SUGGEST_PORT_MAX_PROBES := 64 +const SETTING_WS_PORT := "godot_ai/ws_port" +const SETTING_STARTUP_TRACE := "godot_ai/log_startup_timing" +const SETTING_KEEP_SERVER_ON_EXIT := "godot_ai/keep_server_on_exit" +## External cwd the user can set when an MCP client (Pi, code-server, …) reads +## project-tier config files from a directory this editor can't see. The +## merge-tier strategies include it as an extra `_project_candidate_paths` root +## so project overrides there are detected instead of silently shadowed by a +## global-tier write. Codex-review finding F1. +const SETTING_EXTERNAL_CLIENT_CWD := "godot_ai/external_client_cwd" +const _DISCOVERY_TIMEOUT_MS := 3000 +## Codex launches Windows console-subsystem MCP commands in a visible terminal. +## A GUI-subsystem Python keeps the bridge attached to Codex's redirected MCP +## pipes without allocating a console, then starts console launchers such as +## uvx with CREATE_NO_WINDOW. Keep stdin/stdout/stderr explicit: pythonw can use +## its own inherited pipes, but subprocess defaults do not reliably forward +## them to a child when no console exists. +## This string is a wire format written verbatim into user config `args`. +## Whitespace or formatting changes make every existing Windows entry report +## CONFIGURED_MISMATCH, so changing it is a deliberate migration decision, not +## a refactor. The inline `-c` script is required because the uvx and system +## tiers resolve a system interpreter where `godot_ai` is not importable. +const _WINDOWS_STDIO_BOOTSTRAP := ( + "import subprocess,sys; " + + "raise SystemExit(subprocess.call(sys.argv[1:], stdin=sys.stdin, stdout=sys.stdout, " + + "stderr=sys.stderr, creationflags=0x08000000))" +) + + +## Active HTTP port: user override (if in range) or `DEFAULT_HTTP_PORT`. +static func http_port() -> int: + return _read_port_setting(McpSettings.SETTING_HTTP_PORT, DEFAULT_HTTP_PORT) + + +## Active WebSocket port: user override (if in range) or `DEFAULT_WS_PORT`. +static func ws_port() -> int: + return _read_port_setting(SETTING_WS_PORT, DEFAULT_WS_PORT) + + +static func http_url() -> String: + return "http://127.0.0.1:%d/mcp" % http_port() + + +## Read a URL already captured on the main thread without evaluating the +## EditorSettings-backed fallback unless the snapshot is genuinely incomplete. +static func server_url_from(launch_context: Dictionary) -> String: + if launch_context.has("server_url"): + return str(launch_context["server_url"]) + return http_url() + + +static func _read_port_setting(key: String, default_port: int) -> int: + var es := EditorInterface.get_editor_settings() + if es == null or not es.has_setting(key): + return default_port + var value: int = int(es.get_setting(key)) + if value < MIN_PORT or value > MAX_PORT: + return default_port + return value + + +## Register the port overrides in EditorSettings so they show up in the +## editor's Settings > Plugins section with a range hint. Called once from +## `plugin.gd._enter_tree` before `_start_server` so spawn args see the +## configured values. Safe to call repeatedly — `add_property_info` is +## idempotent and `set_initial_value` only seeds the default. +static func ensure_settings_registered() -> void: + var es := EditorInterface.get_editor_settings() + if es == null: + return + _register_port_setting(es, McpSettings.SETTING_HTTP_PORT, DEFAULT_HTTP_PORT) + _register_port_setting(es, SETTING_WS_PORT, DEFAULT_WS_PORT) + _register_bool_setting(es, SETTING_STARTUP_TRACE, false) + _register_bool_setting(es, SETTING_KEEP_SERVER_ON_EXIT, false) + _register_client_scope_setting(es) + _register_string_setting(es, SETTING_EXTERNAL_CLIENT_CWD, "") + + +static func _register_port_setting(es: EditorSettings, key: String, default_port: int) -> void: + if not es.has_setting(key): + es.set_setting(key, default_port) + es.set_initial_value(key, default_port, false) + es.add_property_info({ + "name": key, + "type": TYPE_INT, + "hint": PROPERTY_HINT_RANGE, + "hint_string": "%d,%d,1" % [MIN_PORT, MAX_PORT], + }) + + +## Surface the CLI registration scope as an enum in Settings > Plugins so it is +## discoverable without hand-editing editor_settings-4.tres. Kept at `user` by +## default; `project` writes the entry into /.mcp.json instead. +static func _register_client_scope_setting(es: EditorSettings) -> void: + var key := McpSettings.SETTING_CLIENT_SCOPE + if not es.has_setting(key): + es.set_setting(key, McpSettings.DEFAULT_CLIENT_SCOPE) + es.set_initial_value(key, McpSettings.DEFAULT_CLIENT_SCOPE, false) + es.add_property_info({ + "name": key, + "type": TYPE_STRING, + "hint": PROPERTY_HINT_ENUM, + "hint_string": ",".join(PackedStringArray(McpSettings.CLIENT_SCOPES)), + }) + + +static func _register_bool_setting(es: EditorSettings, key: String, default_value: bool) -> void: + if not es.has_setting(key): + es.set_setting(key, default_value) + es.set_initial_value(key, default_value, false) + es.add_property_info({ + "name": key, + "type": TYPE_BOOL, + }) + + +static func _register_string_setting(es: EditorSettings, key: String, default_value: String) -> void: + ## Same idempotent set-then-hint dance as the bool helper; `PROPERTY_HINT_NONE` + ## leaves the editor's plain text-input widget in place (the cwd string is + ## freeform). The hint-string slot is required by the API even when empty. + if not es.has_setting(key): + es.set_setting(key, default_value) + es.set_initial_value(key, default_value, false) + es.add_property_info({ + "name": key, + "type": TYPE_STRING, + "hint": PROPERTY_HINT_NONE, + "hint_string": "", + }) + + +static func startup_trace_enabled() -> bool: + ## env_lookup + _editor_setting_lookup for the same worker-thread + ## reason as mode_override (#691). + var raw := McpPathTemplate.env_lookup(STARTUP_TRACE_ENV).strip_edges().to_lower() + if raw == "1" or raw == "true" or raw == "yes" or raw == "on": + return true + var setting: Variant = _editor_setting_lookup(SETTING_STARTUP_TRACE) + if setting != null: + return bool(setting) + return false + + +## keep_server_on_exit (#800): when enabled, editor teardown detaches from +## the managed server instead of killing it, and the spawn env opts the +## server out of both self-reap paths (owner-PID watchdog, session-idle +## backstop) — so MCP clients connected over HTTP stay served across editor +## sessions, and the next editor start adopts the survivor. Off by default: +## "server dies with the editor" stays the shipped behavior. Read via +## _editor_setting_lookup for the same worker-thread reason as +## startup_trace_enabled (#691). +static func keep_server_on_exit() -> bool: + var setting: Variant = _editor_setting_lookup(SETTING_KEEP_SERVER_ON_EXIT) + if setting != null: + return bool(setting) + return false + + +## #691: EditorSettings counterpart of McpPathTemplate.env_lookup. The #678 +## startup walk's discovery worker reaches mode_override() (via +## get_server_command) and EditorInterface / EditorSettings are not +## thread-safe objects. Main thread: live read + mutex-guarded snapshot +## refresh. Worker thread: snapshot only — a never-warmed key reads as +## null (unset), never a live EditorInterface call. Warmed alongside the +## env snapshot in warm_env_snapshot(), which runs on the main thread +## before any worker dispatch. +static var _setting_snapshot := {} +static var _setting_snapshot_mutex := Mutex.new() +## The aggregate MCP status command runs on a worker thread. Keep the same +## main-thread-only LaunchContext contract used by dock workers by publishing a +## deep snapshot whenever capture_launch_context() runs on the main thread. +static var _launch_context_snapshot := {} +static var _launch_context_snapshot_mutex := Mutex.new() + + +static func _editor_setting_lookup(key: String) -> Variant: + if OS.get_thread_caller_id() == OS.get_main_thread_id(): + var live: Variant = null + if Engine.is_editor_hint(): + var es := EditorInterface.get_editor_settings() + if es != null and es.has_setting(key): + live = es.get_setting(key) + _setting_snapshot_mutex.lock() + _setting_snapshot[key] = live + _setting_snapshot_mutex.unlock() + return live + _setting_snapshot_mutex.lock() + var cached: Variant = _setting_snapshot.get(key, null) + _setting_snapshot_mutex.unlock() + return cached + + +## Read the `godot_ai/excluded_domains` EditorSetting as a canonicalized +## comma-separated list (sorted, deduplicated, whitespace-stripped). Returns +## "" when the setting is missing or resolves to an empty set — callers can +## skip appending the flag in that case so older servers that don't know +## `--exclude-domains` don't see an empty argument. +## +## Unknown domain names (e.g. a domain removed since the setting was last +## written) are dropped here, at the single chokepoint both the startup +## flag builder (plugin.gd) and the dock display read — the server's +## `parse_exclude_list` hard-fails on unknown names, so a stale setting +## would otherwise block server startup. +static func excluded_domains() -> String: + var es := EditorInterface.get_editor_settings() + if es == null or not es.has_setting(McpSettings.SETTING_EXCLUDED_DOMAINS): + return "" + return _canonicalize_excluded_domains(str(es.get_setting(McpSettings.SETTING_EXCLUDED_DOMAINS))) + + +## Pure canonicalizer shared by the main-thread LaunchContext capture and +## tests. Unknown domains are dropped for the same startup-safety reason as +## `excluded_domains()` above. +static func _canonicalize_excluded_domains(raw: String) -> String: + var parts := PackedStringArray() + for p in raw.split(","): + var t := p.strip_edges() + if t.is_empty() or parts.find(t) != -1: + continue + if not McpToolCatalog.is_excludable_domain(t): + continue + parts.append(t) + parts.sort() + return ",".join(parts) + + +## Snapshot every EditorSettings-backed value needed to render or verify an +## attach launch command. Main-thread calls refresh the snapshot; worker calls +## return that snapshot without touching EditorInterface (#691). Warm it on the +## main thread before dispatching a worker. +static func capture_launch_context() -> Dictionary: + if OS.get_thread_caller_id() != OS.get_main_thread_id(): + _launch_context_snapshot_mutex.lock() + var cached := _launch_context_snapshot.duplicate(true) + _launch_context_snapshot_mutex.unlock() + return cached + var captured_http_port := http_port() + var context := { + "http_port": captured_http_port, + "ws_port": ws_port(), + "excluded_domains": excluded_domains(), + "plugin_version": get_plugin_version(), + "allow_dev_venv": mode_override() != "user", + "platform": OS.get_name(), + "server_url": "http://127.0.0.1:%d/mcp" % captured_http_port, + "project_roots": capture_project_roots(), + ## The opt-out must ride the attach argv: the client spawns the bridge + ## (and the bridge its backend) with no editor in the loop, so the + ## env-injection path in server_lifecycle.gd never runs for them. + "telemetry_enabled": McpSettings.telemetry_enabled(), + } + _launch_context_snapshot_mutex.lock() + _launch_context_snapshot = context.duplicate(true) + _launch_context_snapshot_mutex.unlock() + return context + + +## Resolve roots used by cwd-relative client project config tiers while the +## engine singletons are safe to access. Workers receive this immutable snapshot. +static func capture_project_roots() -> PackedStringArray: + var current_access := DirAccess.open(".") + var current_root := "" if current_access == null else current_access.get_current_dir().simplify_path() + var project_root := ProjectSettings.globalize_path("res://").simplify_path() + # Codex F1: when the user sets `godot_ai/external_client_cwd` we probe that + # directory in addition to the two guessed roots. The setter / setter-snapshot + # pathway is the same as the existing EditorSettings (warm_env_snapshot + # pre-warms this key so worker-thread callers see the snapshot, not the live + # EditorInterface). Empty string is filtered out by `_canonicalize_roots_for_test`. + var external_cwd := str(_editor_setting_lookup(SETTING_EXTERNAL_CLIENT_CWD)) + return _canonicalize_roots_for_test(PackedStringArray([current_root, project_root, external_cwd])) + + +## Canonicalize a list of root paths to one filesystem representation per +## directory and deduplicate. `ProjectSettings.globalize_path` maps any +## `res://` / `user://` form to the absolute path and is idempotent on an +## already-absolute path, so a `res://`-form candidate and its absolute twin +## collapse to the same entry. Without this pass, `_project_candidate_paths` +## would probe `/.pi/mcp.json` against both representations of the same +## directory and `manual_target_details` would mis-report a single project +## override as multiple tiers (codex-review finding F4). Public-ish seam +## (named `_..._for_test`) so the clients suite can pin the behaviour without +## having to mock `DirAccess.open(".")`. +static func _canonicalize_roots_for_test(raws: PackedStringArray) -> PackedStringArray: + var seen := {} + var roots := PackedStringArray() + for raw in raws: + var s := str(raw).strip_edges() + if s.is_empty(): + continue + var canon := ProjectSettings.globalize_path(s).simplify_path() + if canon.is_empty() or seen.has(canon): + continue + seen[canon] = true + roots.append(canon) + return roots + + +static func _project_roots_from_context(context: Dictionary) -> PackedStringArray: + var roots = context.get("project_roots", PackedStringArray()) + return roots if roots is PackedStringArray else PackedStringArray() + + +## Read the `godot_ai/allow_remote_hosts` EditorSetting as a canonicalized +## comma-separated list of CIDRs / bare IPs (#507). Returns "" when the +## setting is missing or empty — callers skip appending `--allow-host` in +## that case so spawns stay byte-for-byte identical to the loopback-only +## default (and compatible with pre-#421 servers). Mirrors +## `excluded_domains()` above. +static func allow_hosts() -> String: + var es := EditorInterface.get_editor_settings() + if es == null or not es.has_setting(McpSettings.SETTING_ALLOW_HOSTS): + return "" + return McpAllowHosts.normalize(str(es.get_setting(McpSettings.SETTING_ALLOW_HOSTS))) + + +## Suggest a port the caller can actually switch to. Walks +## `candidate`..`candidate+span-1` and returns the first port that is both +## (a) NOT inside a Windows winnat reservation range (Hyper-V / WSL2 / Docker +## grab these; bind fails with WinError 10013 and netstat shows nothing) and +## (b) actually bindable right now on 127.0.0.1. The bind probe is what makes +## "free" honest on macOS/Linux, where the reservation table is empty but the +## next port up may still be occupied — the same suggestion feeds the dock +## crash body, the port-picker spinbox, and the non-recoverable INCOMPATIBLE +## log line. Falls back to the clamped candidate if nothing in the window +## clears both checks (caller surfaces it as a best-effort hint; the user can +## retry or pick another). Best-effort by nature: a TOCTOU window remains +## between the probe and the caller actually binding the port. The bind probe +## is bounded to `SUGGEST_PORT_MAX_PROBES` attempts so this cold path can't +## stall on a pathological run of occupied ports. +static func suggest_free_port(start: int, span: int = 2048) -> int: + var candidate := clampi(start, MIN_PORT, MAX_PORT - span + 1) + var limit := mini(candidate + span - 1, MAX_PORT) + var p := candidate + var probes := 0 + while p <= limit and probes < SUGGEST_PORT_MAX_PROBES: + ## Jump past a whole Windows-reserved range in one step (no-op on + ## POSIX: returns `p` unchanged), so we don't probe port-by-port + ## through the large adjacent ranges those services reserve. The + ## jump itself runs no bind probes, so it doesn't count against the cap. + var not_reserved := WindowsPortReservation.suggest_non_excluded_port(p, limit - p + 1, MAX_PORT) + if not_reserved < p or not_reserved > limit: + break + p = not_reserved + probes += 1 + if PortResolver.can_bind_local_port(p): + return p + p += 1 + return candidate + + +# --- Client operations (string id) --------------------------------------- + +static func client_ids() -> PackedStringArray: + return ClientRegistry.ids() + + +static func has_client(id: String) -> bool: + return ClientRegistry.has_id(id) + + +static func client_display_name(id: String) -> String: + var c := ClientRegistry.get_by_id(id) + return c.display_name if c != null else id + + +## Pass an explicit `url` when calling from a worker thread: `http_url()` +## reads `EditorInterface.get_editor_settings()`, which is main-thread-only. +## Empty defaults to the live server URL — appropriate for MCP-tool callers +## that always run on main. +static func configure(id: String, url: String = "", launch_context: Dictionary = {}) -> Dictionary: + if ClientRegistry.stale_session_detected(): + return {"status": "error", "message": ClientRegistry.RESTART_TO_FINISH_UPDATE} + var client := ClientRegistry.get_by_id(id) + if client == null: + return {"status": "error", "message": "Unknown client: %s" % id} + var path_error := _config_path_resolution_error(client) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + ## Capture `url` once so a port flip in EditorSettings between write and + ## verify can't trigger a spurious CONFIGURED_MISMATCH against an entry + ## that just landed correctly. + if url.is_empty(): + url = http_url() + var context := launch_context + if client.command_shape != Client.CommandShape.NONE and context.is_empty(): + if OS.get_thread_caller_id() != OS.get_main_thread_id(): + return { + "status": "error", + "message": "Cannot configure %s without a main-thread launch snapshot; retry from the dock." % client.display_name, + } + context = capture_launch_context() + var launch := ( + resolve_attach_launch(context) + if client.command_shape != Client.CommandShape.NONE + else {} + ) + var result := _dispatch_configure(client, url, launch, context) + ## Trust-but-verify: a strategy may report ok and have actually written the + ## file, yet the entry is missing/stale on the read-back path — most often + ## because the user's installed client is reading a different file than + ## `path_template` resolves to (issue #201). Re-read the live state and + ## surface a clear error before the dock reports a bogus green dot. + return _verify_post_state(client, result, Client.Status.CONFIGURED, url, "configure", launch, context) + + +static func check_status(id: String) -> Client.Status: + if ClientRegistry.stale_session_detected(): + return Client.Status.ERROR + var client := ClientRegistry.get_by_id(id) + if client == null: + return Client.Status.NOT_CONFIGURED + var context := capture_launch_context() if client.command_shape != Client.CommandShape.NONE else {} + return _dispatch_check_status(client, http_url(), context) + + +static func check_status_for_url_with_cli_path( + id: String, url: String, cli_path: String, launch_context: Dictionary = {} +) -> Client.Status: + return check_status_details_for_url_with_cli_path(id, url, cli_path, launch_context).get("status", Client.Status.NOT_CONFIGURED) + + +## True when 's stored entry verifies EXACTLY against the launch this +## editor would have rendered at `from_version` — same ports, exclusions, +## telemetry flag, command shape; nothing differs but the version pin. This +## is the post-update auto-repin gate: only such entries are provably "what +## Configure wrote before the update", so rewriting them to the current +## version restores the user's own prior intent. Anything else — entries +## pointing at another editor's ports (the smoke-fixture blast radius that +## motivated this gate), hand-edits, changed settings — stays untouched for +## the drift banner's human click. An empty `from_version` (marker written +## by a pre-gate runner) fails closed. +## +## The version-substituted context is safe to resolve and cache: +## `plugin_version` is part of both the attach-launch resolution +## (`_resolve_attach_launch_uncached`) and its cache key. +static func entry_drift_is_version_pin_only( + id: String, from_version: String, launch_context: Dictionary = {} +) -> bool: + var pinned_from := from_version.strip_edges() + if pinned_from.is_empty(): + return false + ## Never shell out from this gate — it runs on the MAIN thread from the + ## dock's sweep-completion callback (#890 review P2). The cli-descriptor + ## probe paths run a subprocess with a multi-second timeout (`claude mcp + ## get` is 6s), which would freeze the editor; those clients fail closed + ## to the drift banner's click flow, whose fan-out already runs on + ## worker threads. Every path left after these guards is a bounded + ## config-file read plus cached launch discovery (worst case one CLI + ## lookup on a cold CliFinder cache — the same bounded one-shot the + ## dock's `_reprobe_uv_if_negative` accepts on this thread). + var client := ClientRegistry.get_by_id(id) + if client == null: + return false + if client.config_type == "cli": + if client.command_shape == Client.CommandShape.NONE: + return false + if not client.has_json_fallback(): + return false + if _scope_diverges_from_json_fallback(client): + return false + var context := launch_context if not launch_context.is_empty() else capture_launch_context() + var old_context := context.duplicate(true) + old_context["plugin_version"] = pinned_from + ## Same URL under both versions: the URL carries the port, not the + ## version, so URL-mode entries can never be version-pin-only drift and + ## correctly fail this check. + var url := str(context.get("server_url", http_url())) + var status := check_status_for_url_with_cli_path(id, url, "", old_context) + return status == Client.Status.CONFIGURED + + +## Detailed variant used by the dock refresh worker. Returns +## `{"status": Status, "error_msg": String}` so the worker can surface +## "probe timed out" on the row instead of silently flipping it to +## NOT_CONFIGURED. Callers that only need the status can use the simpler +## helper above. +static func check_status_details_for_url_with_cli_path( + id: String, + url: String, + cli_path: String, + launch_context: Dictionary = {}, + resolved_launch: Dictionary = {}, +) -> Dictionary: + ## One comprehensible line per row beats a wall of per-field type errors — + ## the dock keeps painting, every row names the same repair (restart). + if ClientRegistry.stale_session_detected(): + return {"status": Client.Status.ERROR, "error_msg": ClientRegistry.RESTART_TO_FINISH_UPDATE} + var client := ClientRegistry.get_by_id(id) + if client == null: + return {"status": Client.Status.NOT_CONFIGURED, "error_msg": ""} + # A cli client with no resolved binary normally reads as NOT_CONFIGURED. + # Skip that shortcut when the client has a JSON fallback (#463): the + # dispatch below reads its config file directly so the status dot reflects + # a fallback-configured entry instead of always showing red. + if client.config_type == "cli" and cli_path.is_empty() and not client.has_json_fallback(): + return {"status": Client.Status.NOT_CONFIGURED, "error_msg": ""} + var path_error := _config_path_resolution_error(client) + if not path_error.is_empty(): + return {"status": Client.Status.ERROR, "error_msg": path_error} + if client.command_shape != Client.CommandShape.NONE and launch_context.is_empty(): + return { + "status": Client.Status.ERROR, + "error_msg": "Missing launch-context snapshot; retry the status refresh.", + } + return _dispatch_check_status_with_cli_path_details( + client, url, cli_path, launch_context, resolved_launch + ) + + +## #691: main-thread pre-warm of McpPathTemplate's env snapshot, covering +## the base vars plus every descriptor-declared config-file/config-home env +## (OPENCODE_CONFIG, CLAUDE_CONFIG_DIR, CODEX_HOME, …), so worker-thread config-path +## resolution never calls OS.get_environment concurrently with the spawn +## window's setenv/unsetenv. Also warms the EditorSettings snapshot for +## the mode/trace overrides so worker-thread mode_override() / +## startup_trace_enabled() never touch EditorInterface. Idempotent; +## called from plugin _enter_tree and before each dock worker dispatch. +static func warm_env_snapshot() -> void: + var extras := PackedStringArray() + for id in client_ids(): + var client := ClientRegistry.get_by_id(String(id)) + if client == null: + continue + ## Reflected get(): after an in-session self-update these fields can + ## read as Nil on stale instances, and String(Nil) is a hard error (#850). Skipping just degrades env-override + ## resolution until the restart the registry is already asking for. + for env_name in [client.get("config_file_env"), client.get("config_home_env")]: + if env_name is String and not env_name.is_empty() and not extras.has(env_name): + extras.append(env_name) + McpPathTemplate.warm_env_snapshot(extras) + _editor_setting_lookup(MODE_OVERRIDE_SETTING) + _editor_setting_lookup(SETTING_STARTUP_TRACE) + _editor_setting_lookup(SETTING_KEEP_SERVER_ON_EXIT) + _editor_setting_lookup(SETTING_EXTERNAL_CLIENT_CWD) + McpSettings.warm_client_scope() + # Publish the complete launch context while EditorInterface access is safe; + # worker callers of capture_launch_context() read this snapshot only. + capture_launch_context() + + +static func client_status_probe_snapshot(id: String) -> Dictionary: + var client := ClientRegistry.get_by_id(id) + if client == null: + return {} + var cli_path := "" + var installed := false + if client.config_type == "cli": + cli_path = CliStrategy.resolve_cli_path(client) + # #463: a JSON-fallback cli client (Claude Code as a VS Code extension) + # is "installed" when its fallback config exists, even with no binary. + installed = not cli_path.is_empty() or client.is_installed() + else: + installed = client.is_installed() + return {"id": id, "cli_path": cli_path, "installed": installed} + + +## Force lazy GDScript bytecode swaps to complete before a client-status +## worker reaches the registry and strategies. Pure-memory only: callers can +## run this on the handler thread without performing CLI or config probes. +static func warm_status_worker_bytecode() -> void: + var ids := client_ids() + if ids.is_empty(): + return + var any_client := ClientRegistry.get_by_id(String(ids[0])) + if any_client != null: + JsonStrategy.verify_entry(any_client, {}, "") + DshStrategy.command_launch_error(any_client, {}) + TomlStrategy.format_body(PackedStringArray(), "") + CliStrategy.format_args(PackedStringArray(), "", "") + # Compile the aggregate worker entry point on main as well. After a plugin + # reload, first-dereferencing this function from Thread can hang in Godot's + # lazy bytecode swap even when every strategy it calls was already warmed. + run_client_status_sweep({}, true) + + +## Worker entry point for the MCP aggregate status command. Every filesystem, +## CLI, and launch-discovery probe stays inside this function; the WebSocket +## handler only schedules it and returns the deferred sentinel. +static func run_client_status_sweep( + fallback_launch_context: Dictionary = {}, warm_only: bool = false +) -> Dictionary: + if warm_only: + return {} + var clients := [] + var launch_context := capture_launch_context() + if launch_context.is_empty(): + launch_context = fallback_launch_context.duplicate(true) + if launch_context.is_empty(): + return {"worker_error": "Client status launch context was not warmed on the main thread."} + var server_url := server_url_from(launch_context) + var resolved_launch := resolve_attach_launch(launch_context) + for client_id in client_ids(): + var probe := client_status_probe_snapshot(client_id) + var details := check_status_details_for_url_with_cli_path( + client_id, + server_url, + str(probe.get("cli_path", "")), + launch_context, + resolved_launch, + ) + clients.append(_client_status_sweep_entry( + client_id, details, bool(probe.get("installed", false)) + )) + return {"data": {"clients": clients}} + + +static func _client_status_sweep_entry( + client_id: String, details: Dictionary, installed: bool +) -> Dictionary: + var status = details.get("status", Client.Status.NOT_CONFIGURED) + var entry := { + "id": client_id, + "display_name": client_display_name(client_id), + "status": Client.status_label(status), + "installed": installed, + } + var error_msg := str(details.get("error_msg", "")) + if not error_msg.is_empty(): + entry["error"] = error_msg + return entry + + +## Pass an explicit `url` when calling from a worker thread — see +## `configure()` above for why. The url is only used to format the +## verify-after-write diagnostic message; the remove itself doesn't need it. +static func remove(id: String, url: String = "", launch_context: Dictionary = {}) -> Dictionary: + if ClientRegistry.stale_session_detected(): + return {"status": "error", "message": ClientRegistry.RESTART_TO_FINISH_UPDATE} + var client := ClientRegistry.get_by_id(id) + if client == null: + return {"status": "error", "message": "Unknown client: %s" % id} + var path_error := _config_path_resolution_error(client) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if url.is_empty(): + url = http_url() + var context := launch_context + if client.command_shape != Client.CommandShape.NONE and context.is_empty(): + if OS.get_thread_caller_id() != OS.get_main_thread_id(): + return { + "status": "error", + "message": "Cannot remove %s without a main-thread launch snapshot; retry from the dock." % client.display_name, + } + context = capture_launch_context() + var launch := ( + resolve_attach_launch(context) + if client.command_shape != Client.CommandShape.NONE + else {} + ) + var result := _dispatch_remove(client, context) + return _verify_post_state(client, result, Client.Status.NOT_CONFIGURED, url, "remove", launch, context) + + +## Resolve config-backed path errors before attach-launch discovery. This both +## gives ambiguity precedence over unrelated launcher failures and avoids +## spending the status worker's command budget on a Configure action that must +## fail closed regardless. CLI clients keep their existing CLI/fallback dispatch. +static func _config_path_resolution_error(client: Client) -> String: + if client.config_type == "cli": + return "" + return str(client.resolved_config_path_details().get("error", "")) + + +# --- Strategy dispatch + verify (testable seam) -------------------------- + +static func _dispatch_configure( + client: Client, url: String, launch: Dictionary = {}, launch_context: Dictionary = {} +) -> Dictionary: + launch = launch_for_client(client, launch) + match client.config_type: + "json": + return JsonStrategy.configure(client, SERVER_NAME, url, launch, _project_roots_from_context(launch_context)) + "toml": + return TomlStrategy.configure(client, SERVER_NAME, url, launch) + "yaml": + return YamlStrategy.configure(client, SERVER_NAME, url, launch) + "dsh": + return DshStrategy.configure(client, SERVER_NAME, url, launch) + "cli": + # #463: fall back to writing the config file directly when the CLI + # binary isn't on PATH (Claude Code as a VS Code/Cursor extension). + if client.has_json_fallback() and CliStrategy.resolve_cli_path(client).is_empty(): + return _note_unhonoured_scope( + client, JsonStrategy.configure(client, SERVER_NAME, url, launch, _project_roots_from_context(launch_context)) + ) + return CliStrategy.configure(client, SERVER_NAME, url, launch) + return {"status": "error", "message": "Unknown config_type for %s: %s" % [client.id, client.config_type]} + + +static func _dispatch_remove(client: Client, launch_context: Dictionary = {}) -> Dictionary: + match client.config_type: + "json": + return JsonStrategy.remove(client, SERVER_NAME, _project_roots_from_context(launch_context)) + "toml": + return TomlStrategy.remove(client, SERVER_NAME) + "yaml": + return YamlStrategy.remove(client, SERVER_NAME) + "dsh": + return DshStrategy.remove(client, SERVER_NAME) + "cli": + # #463: mirror the configure fallback so Remove also works without + # the CLI binary — otherwise a fallback-written entry is unremovable. + if client.has_json_fallback() and CliStrategy.resolve_cli_path(client).is_empty(): + return JsonStrategy.remove(client, SERVER_NAME, _project_roots_from_context(launch_context)) + return CliStrategy.remove(client, SERVER_NAME) + return {"status": "error", "message": "Unknown config_type for %s: %s" % [client.id, client.config_type]} + + +static func _dispatch_check_status( + client: Client, url: String, launch_context: Dictionary = {} +) -> Client.Status: + return _dispatch_check_status_with_cli_path(client, url, "", launch_context) + + +static func _dispatch_check_status_with_cli_path( + client: Client, url: String, cli_path: String, launch_context: Dictionary = {} +) -> Client.Status: + return _dispatch_check_status_with_cli_path_details(client, url, cli_path, launch_context).get("status", Client.Status.NOT_CONFIGURED) + + +static func _dispatch_check_status_with_cli_path_details( + client: Client, + url: String, + cli_path: String, + launch_context: Dictionary = {}, + resolved_launch: Dictionary = {}, +) -> Dictionary: + match client.config_type: + "json": + var launch := {} + if client.command_shape != Client.CommandShape.NONE: + launch = _resolved_or_discovered_launch(client, resolved_launch, launch_context) + return JsonStrategy.check_status_details(client, SERVER_NAME, url, launch, _project_roots_from_context(launch_context)) + "toml": + var launch := {} + if client.command_shape != Client.CommandShape.NONE: + launch = _resolved_or_discovered_launch(client, resolved_launch, launch_context) + return TomlStrategy.check_status_details(client, SERVER_NAME, url, launch) + "yaml": + var yaml_launch := {} + if client.command_shape != Client.CommandShape.NONE: + yaml_launch = _resolved_or_discovered_launch(client, resolved_launch, launch_context) + return YamlStrategy.check_status_details(client, SERVER_NAME, url, yaml_launch) + "dsh": + var dsh_launch := {} + if client.command_shape != Client.CommandShape.NONE: + dsh_launch = _resolved_or_discovered_launch(client, resolved_launch, launch_context) + return DshStrategy.check_status_details(client, SERVER_NAME, url, dsh_launch) + "cli": + # Command-shape CLI clients register through their CLI, but the entry + # lands in the same file the JSON fallback reads (`claude mcp add + # --scope user` writes mcpServers in ~/.claude.json). Reading that + # file gives exact launch-drift detection — a changed port, version + # pin, or exclusion list — which scanning `mcp list` stdout cannot, + # so it is preferred even when the CLI binary resolves. + # #872: ...but only while the selected scope is still the one + # `path_template` points at — see _scope_diverges_from_json_fallback. + if ( + client.command_shape != Client.CommandShape.NONE + and client.has_json_fallback() + and not _scope_diverges_from_json_fallback(client) + ): + var command_launch := _resolved_or_discovered_launch(client, resolved_launch, launch_context) + return JsonStrategy.check_status_details(client, SERVER_NAME, url, command_launch, _project_roots_from_context(launch_context)) + var resolved_cli := cli_path if not cli_path.is_empty() else CliStrategy.resolve_cli_path(client) + # #463: with no CLI binary, read the JSON fallback config so a + # fallback-configured entry reports CONFIGURED instead of red. + if resolved_cli.is_empty() and client.has_json_fallback(): + var fallback_launch := {} + if client.command_shape != Client.CommandShape.NONE: + fallback_launch = _resolved_or_discovered_launch(client, resolved_launch, launch_context) + return JsonStrategy.check_status_details(client, SERVER_NAME, url, fallback_launch, _project_roots_from_context(launch_context)) + var cli_launch := {} + if client.command_shape != Client.CommandShape.NONE: + cli_launch = _resolved_or_discovered_launch(client, resolved_launch, launch_context) + # #872: at a scope `path_template` can't see, a plain listing probe + # cannot tell our entry from a leftover one in another scope. When + # the descriptor offers a scope-aware probe, use it — same single + # subprocess, but it reports which scope actually resolved. + if ( + not client.cli_scope_status_template.is_empty() + and CliStrategy.uses_scope_token(client) + ): + return CliStrategy.check_scope_status_details( + client, SERVER_NAME, url, resolved_cli, cli_launch, McpSettings.client_scope() + ) + return CliStrategy.check_status_details(client, SERVER_NAME, url, resolved_cli, cli_launch) + return {"status": Client.Status.NOT_CONFIGURED, "error_msg": ""} + + +## #872: the #463 JSON fallback writes the user-scope file whatever +## `godot_ai/mcp_client_scope` says — that file IS `path_template`, and +## `clients/_path_template.gd` has no project-relative token to aim it +## elsewhere. Returning a bare "configured" would hide that the requested +## scope was not honoured, so say so in the message. +## +## Deliberately a message and not a status. `_verify_post_state` compares the +## post-write status against CONFIGURED and replaces the ok with an error on +## any mismatch (pinned by test_verify_post_state_treats_drift_as_failure_ +## after_configure), so reporting this write as NOT_CONFIGURED or MISMATCH +## would turn a *successful* configure into a user-facing failure — the same +## false-error class #872's blocker was about, just moved onto the fallback +## path. The entry is genuinely written and genuinely works; only its scope +## differs from the request, and that is a caveat, not a failure. +static func _note_unhonoured_scope(client: Client, result: Dictionary) -> Dictionary: + if result.get("status") != "ok": + return result + if not CliStrategy.uses_scope_token(client): + return result + var scope := McpSettings.client_scope() + if scope == McpSettings.DEFAULT_CLIENT_SCOPE: + return result + var noted := result.duplicate(true) + noted["message"] = ( + "%s — wrote %s scope, not %s: the %s CLI wasn't found, and the file fallback can only write %s" + % [ + str(result.get("message", "")), + McpSettings.DEFAULT_CLIENT_SCOPE, + scope, + client.display_name, + client.resolved_config_path(), + ] + ) + return noted + + +## True when this client's CLI writes its entry somewhere `path_template` +## cannot see, so reading that file would describe the wrong thing (#872). +## +## `claude mcp add --scope project` writes /.mcp.json and `--scope local` +## writes a per-project block inside ~/.claude.json — neither is the top-level +## `mcpServers` map `path_template` + `server_key_path` resolve to. Reading it +## anyway makes `_verify_post_state` turn every successful project-scope +## Configure into "configure ok but verification still reads Not configured", +## and pins the dock row red (or green, describing a stale user-scope entry). +## +## Diverging sends status down the CLI probe instead: `mcp list` is +## scope-agnostic and inherits the same cwd the register ran in, so read-back +## and write agree by construction. The cost is losing exact launch-drift +## detection — a stdout scan sees the command, not the full argv — which is the +## documented trade for a status that is merely coarse instead of wrong. +## +## Deliberately says nothing about whether the CLI resolves (#879). An earlier +## version walked PATH here and returned false for an unresolvable binary, on +## the reasoning that configure would then have taken the #463 JSON fallback — +## which writes user scope whatever the setting says — so the file was the +## right thing to read again. That extra clause could not change any outcome: +## this is only consulted from the one call site below, already guarded on +## `has_json_fallback()`, and when the CLI does not resolve the very next +## branch (`resolved_cli.is_empty() and client.has_json_fallback()`) takes the +## fallback read anyway. All it bought was a second full `McpCliFinder.find` +## sweep per status check, on top of the one that immediately follows. +static func _scope_diverges_from_json_fallback(client: Client) -> bool: + if not CliStrategy.uses_scope_token(client): + return false + return McpSettings.client_scope() != McpSettings.DEFAULT_CLIENT_SCOPE + + +static func _resolved_or_discovered_launch( + client: Client, resolved_launch: Dictionary, launch_context: Dictionary +) -> Dictionary: + var launch := ( + resolved_launch + if not resolved_launch.is_empty() + else resolve_attach_launch(launch_context) + ) + return launch_for_client(client, launch) + + +## After a configure/remove returns ok, re-read the live status. If it doesn't +## match `expected`, replace the result with an error that names the actual +## status and the resolved config path so the user can self-diagnose. The +## strategy's own error path is left untouched — already actionable. +static func _verify_post_state( + client: Client, + result: Dictionary, + expected: Client.Status, + url: String, + action: String, + resolved_launch: Dictionary = {}, + launch_context: Dictionary = {}, +) -> Dictionary: + if result.get("status") != "ok": + return result + var details := _dispatch_check_status_with_cli_path_details( + client, url, "", launch_context, resolved_launch + ) + var actual := details.get("status", Client.Status.NOT_CONFIGURED) + if actual == expected: + return result + var path_hint := _post_state_path_hint(client, str(details.get("resolved_scope", ""))) + return { + "status": "error", + "message": "%s reported %s ok but verification still reads %s (expected %s).%s" % [ + client.display_name, action, + Client.status_label(actual), Client.status_label(expected), + path_hint, + ], + } + + +## Where to send the user when verification finds an entry that should not be +## there. `resolved_config_path()` is `path_template` — right only for the +## default user scope. Naming ~/.claude.json for a project-scope survivor sends +## them to a file with nothing in it, which is worse than naming no file at all +## (#879). The scope probe supplies `resolved_scope`; `path_template` has no +## project-relative token (see `_note_unhonoured_scope`), so the project case is +## described rather than resolved to a path. +static func _post_state_path_hint(client: Client, resolved_scope: String) -> String: + match resolved_scope: + "project": + return ( + " The surviving entry is project-scoped: inspect the .mcp.json in the" + + " directory the editor was launched from and remove the godot-ai entry" + + " by hand if needed." + ) + "local": + var local_path := client.resolved_config_path() + if local_path.is_empty(): + return "" + return ( + " The surviving entry is local-scoped: inspect the block for the" + + " directory the editor was launched from in %s and remove the" + + " godot-ai entry by hand if needed." + ) % local_path + _: + var path := client.resolved_config_path() + if path.is_empty(): + return "" + return " Inspect %s and remove the godot-ai entry by hand if needed." % path + + +## #877: Configure's first act is the all-scope pre-cleanup — it deletes the +## `godot-ai` entry from every scope the descriptor can write to, including a +## `.mcp.json` resolved against the CLI's working directory, which need not be +## this project's folder. The manual-command panel that spells those removes +## out is only shown when Configure FAILS (`mcp_dock.gd`), so on the success +## path — the one where the sweep actually ran — this note is its only +## disclosure. Empty for descriptors without a scope token: their single +## implicit pass removes exactly the entry the register is about to rewrite, +## which needs no warning (the same rule `_sweep_caveat` applies). +## +## "attempted", not "cleared": `CliStrategy.configure` discards every +## pre-cleanup result, and `mcp remove` exits non-zero for an absent entry as +## well as for a real failure, so a timed-out or failed remove leaves the scope +## untouched while the register still returns ok. The note names what ran, +## not what it can prove. +static func configure_sweep_note(id: String) -> String: + var client := ClientRegistry.get_by_id(id) + if client == null or client.config_type != "cli": + return "" + if client.cli_unregister_template.is_empty() or not CliStrategy.uses_scope_token(client): + return "" + return "attempted to clear %s from %s" % [ + SERVER_NAME, ", ".join(CliStrategy.cleanup_scopes(client)), + ] + + +static func manual_command(id: String) -> String: + var client := ClientRegistry.get_by_id(id) + if client == null: + return "" + var path_resolution := client.resolved_config_path_details() + var path_error := str(path_resolution.get("error", "")) + if not path_error.is_empty(): + return "Config path unavailable: %s" % path_error + var context := capture_launch_context() if client.command_shape != Client.CommandShape.NONE else {} + var launch := ( + launch_for_client(client, resolve_attach_launch(context)) + if client.command_shape != Client.CommandShape.NONE + else {} + ) + var cmd := ManualCommand.build( + client, + SERVER_NAME, + server_url_from(context), + str(path_resolution.get("path", "")), + launch, + _project_roots_from_context(context), + ) + if cmd.is_empty(): + return cmd + ## #507: when the allow-host opt-in names a non-loopback range, also + ## surface the LAN URL so the user can copy-paste the right address into + ## a remote agent. Informational only — configure/remove still WRITE the + ## loopback URL above; nothing about the config-file contract changes. + var note := McpAllowHosts.lan_url_note(allow_hosts(), IP.get_local_addresses(), http_port()) + if not note.is_empty(): + cmd += "\n\n" + note + return cmd + + +static func config_path(id: String) -> String: + var client := ClientRegistry.get_by_id(id) + return client.resolved_config_path() if client != null else "" + + +## Resolve the highest-precedence config tier that actually contains the server +## entry. For Pi-style merge clients, returns the tier path the entry lives in +## (e.g. `~/.pi/agent/.mcp.json`) instead of the lowest-tier `path_template` +## `config_path()` returns. Falls back to `path_template` when no entry is +## found anywhere. Empty `launch_context` is allowed; command-shape clients +## synthesize one via `capture_launch_context()` so dock row construction can +## call this without first capturing launch state. +static func effective_config_path(id: String, launch_context: Dictionary = {}) -> String: + var client := ClientRegistry.get_by_id(id) + if client == null: + return "" + var resolution := client.resolved_config_path_details() + var fallback := str(resolution.get("path", "")) + var context := launch_context + if context.is_empty() and client.command_shape != Client.CommandShape.NONE: + context = capture_launch_context() + var roots := _project_roots_from_context(context) + var target := JsonStrategy.manual_target_details(client, SERVER_NAME, fallback, roots) + if bool(target.get("ok", false)): + return str(target.get("path", fallback)) + return fallback + + +## Path that `_check_status_merged` would consider authoritative for the +## server entry, or `path_template` when no entry is found anywhere. +## For Pi-style merge clients this is the latest project tier when one +## exists (matching the F2 last-wins status logic), falling back to the +## latest global tier, then to `path_template`. +## +## The dock uses this for Open/Reveal so the file the user inspects is +## the same file that drives the status check — `effective_config_path` +## fails closed (returns `path_template`) when there are multiple project +## tiers, which historically sent users to the wrong file (codex round 3, +## F-3-4). Splitting this from `effective_config_path` keeps the manual +## instructions fail-closed while letting the dock follow the +## authoritative tier. +static func effective_authoritative_path(id: String, launch_context: Dictionary = {}) -> String: + var client := ClientRegistry.get_by_id(id) + if client == null: + return "" + var resolution := client.resolved_config_path_details() + var fallback := str(resolution.get("path", "")) + var context := launch_context + if context.is_empty() and client.command_shape != Client.CommandShape.NONE: + context = capture_launch_context() + var roots := _project_roots_from_context(context) + var authoritative: String = JsonStrategy.authoritative_tier_path(client, SERVER_NAME, roots) + if not authoritative.is_empty(): + return authoritative + return fallback + + +static func is_installed(id: String) -> bool: + var client := ClientRegistry.get_by_id(id) + return client != null and client.is_installed() + + +# --- Server command discovery -------------------------------------------- +# +# Three-tier resolution: +# 1. .venv python — dev checkout, source code +# 2. uvx — user install, published package from PyPI +# 3. godot-ai CLI — system-wide pip/pipx/uv install + +static func get_plugin_version() -> String: + var cfg := ConfigFile.new() + if cfg.load("res://addons/godot_ai/plugin.cfg") == OK: + return cfg.get_value("plugin", "version", "0.0.1") + return "0.0.1" + + +## Strip PEP 440 local build metadata for PyPI pins: `3.0.2+local.1` → `3.0.2`. +## Pre-release segments (`3.1.0-rc1`) are preserved — only `+…` is removed. +static func _pypi_pin_version(version: String) -> String: + var v := version.strip_edges() + var plus := v.find("+") + if plus >= 0: + v = v.substr(0, plus) + return v + + +## Resolve the client-owned `godot-ai attach` command from a main-thread +## LaunchContext. Discovery itself is worker-safe: path/environment lookup is +## snapshot-backed and subprocess probes are wall-clock bounded. +## +## `discovery_override` is a data-only test seam. Supplying a key (including +## an empty value) bypasses that tier's live lookup; `system_version_result` +## bypasses the real `godot-ai --version` subprocess. +static func resolve_attach_launch( + launch_context: Dictionary, discovery_override: Dictionary = {} +) -> Dictionary: + ## Test overrides always bypass the session cache so fixture-controlled + ## discovery remains deterministic. Production results are keyed by every + ## setting that affects the rendered command; a port/domain/version change + ## therefore cannot reuse stale arguments. + if not discovery_override.is_empty(): + return _resolve_attach_launch_uncached(launch_context, discovery_override) + var cache_key := _attach_launch_cache_key(launch_context) + _attach_launch_cache_mutex.lock() + if _attach_launch_cache.has(cache_key): + var cached: Dictionary = _attach_launch_cache[cache_key].duplicate(true) + _attach_launch_cache_mutex.unlock() + return cached + ## Keep the cache lock through the bounded discovery probes. This cold path + ## runs at most once per distinct context and prevents simultaneous status + ## workers from repeating the same subprocess probes. Invalidation waits for + ## the in-flight result, then clears it, so stale work cannot repopulate a + ## freshly invalidated cache. + var resolved := _resolve_attach_launch_uncached(launch_context) + _attach_launch_cache[cache_key] = resolved.duplicate(true) + _attach_launch_cache_mutex.unlock() + return resolved + + +static func _resolve_attach_launch_uncached( + launch_context: Dictionary, discovery_override: Dictionary = {} +) -> Dictionary: + for key in ["http_port", "ws_port", "excluded_domains", "plugin_version", "allow_dev_venv", "platform"]: + if not launch_context.has(key): + return _attach_discovery_error("Launch context is missing `%s`; retry Configure." % key) + + var plugin_version := str(launch_context.get("plugin_version", "")).strip_edges() + if plugin_version.is_empty(): + return _attach_discovery_error("The bundled godot-ai version is unavailable; reinstall the plugin and retry Configure.") + + var common_args: Array[String] = [ + "attach", + "--port", str(int(launch_context.get("http_port", DEFAULT_HTTP_PORT))), + "--ws-port", str(int(launch_context.get("ws_port", DEFAULT_WS_PORT))), + ] + var exclusions := str(launch_context.get("excluded_domains", "")).strip_edges() + if not exclusions.is_empty(): + common_args.append_array(["--exclude-domains", exclusions]) + ## Default true when the key is absent (hand-built contexts in tests, stale + ## pre-upgrade snapshots) — matching the server's send-by-default posture. + ## Toggling the setting changes the rendered argv, so existing entries read + ## CONFIGURED_MISMATCH and the dock offers Reconfigure, like any other + ## launch-affecting value. + if not bool(launch_context.get("telemetry_enabled", true)): + common_args.append("--disable-telemetry") + + var venv_python := "" + if discovery_override.has("venv_python"): + venv_python = str(discovery_override["venv_python"]) + elif bool(launch_context.get("allow_dev_venv", true)): + venv_python = _cached_venv_python() + if bool(launch_context.get("allow_dev_venv", true)) and not venv_python.is_empty(): + var venv_args: Array[String] = ["-m", "godot_ai"] + venv_args.append_array(common_args) + return _finalize_attach_launch( + "dev_venv", venv_python, venv_args, launch_context, discovery_override + ) + + var uvx := "" + if discovery_override.has("uvx_path"): + uvx = str(discovery_override["uvx_path"]) + else: + ## Strict lookup for attach entries: never write a bare `uvx` command + ## that a GUI-launched client may be unable to resolve from its PATH. + uvx = find_uvx() + if not uvx.is_empty(): + var uvx_args: Array[String] = [ + "--link-mode", "copy", + "--from", "godot-ai==%s" % _pypi_pin_version(plugin_version), + "godot-ai", + ] + uvx_args.append_array(common_args) + return _finalize_attach_launch( + "uvx", uvx, uvx_args, launch_context, discovery_override + ) + + var system_cmd := "" + if discovery_override.has("system_path"): + system_cmd = str(discovery_override["system_path"]) + else: + system_cmd = _find_system_install() + if not system_cmd.is_empty(): + var probe: Dictionary + if discovery_override.has("system_version_result"): + probe = discovery_override["system_version_result"] as Dictionary + else: + probe = McpCliExec.run(system_cmd, ["--version"], _DISCOVERY_TIMEOUT_MS, false) + var version_check := _system_version_from_probe(probe) + if bool(version_check.get("ok", false)): + var found_version := str(version_check.get("version", "")) + if found_version == plugin_version: + return _finalize_attach_launch( + "system", system_cmd, common_args, launch_context, discovery_override + ) + return _attach_discovery_error( + "System godot-ai is version %s, but this plugin requires %s. Install uv or update the system package, then retry Configure." + % [found_version, plugin_version] + ) + if bool(probe.get("timed_out", false)): + return _attach_discovery_error( + "Timed out checking the system godot-ai version. Install uv or repair the system command, then retry Configure." + ) + return _attach_discovery_error( + "Could not verify the system godot-ai version. Install uv or repair the system command, then retry Configure." + ) + + return _attach_discovery_error( + "No compatible godot-ai launcher was found. Install uv (provides uvx), then retry Configure." + ) + + +## Return a launch shape that cannot allocate a visible console on Windows. +## The development tier can execute its sibling pythonw directly. uvx and the +## system entry point still need their own environments, so pythonw acts only +## as a stdio-preserving, CREATE_NO_WINDOW process bootstrap for those tiers. +static func _finalize_attach_launch( + tier: String, + command: String, + args: Array[String], + launch_context: Dictionary, + discovery_override: Dictionary, +) -> Dictionary: + if str(launch_context.get("platform", "")) != "Windows": + return {"ok": true, "tier": tier, "command": command, "args": args} + + var pythonw := _resolve_consoleless_python(command, tier, discovery_override) + if pythonw.is_empty(): + return _attach_discovery_error( + "Windows requires pythonw.exe to launch the MCP bridge without opening a terminal window. Repair this Python or uv installation, then retry Configure." + ) + + ## `console_command`/`console_args` carry the unwrapped console-subsystem + ## launch for clients that opt out of pythonw via + ## `needs_consoleless_launcher = false` (#863). Strategies only consume + ## `command`/`args`/`ok`; `launch_for_client` swaps the shapes per client. + if tier == "dev_venv": + return { + "ok": true, "tier": tier, "command": pythonw, "args": args, + "console_command": command, "console_args": args, + } + + var wrapped_args: Array[String] = ["-c", _WINDOWS_STDIO_BOOTSTRAP, command] + wrapped_args.append_array(args) + return { + "ok": true, "tier": tier, "command": pythonw, "args": wrapped_args, + "console_command": command, "console_args": args, + } + + +## Select the launch shape a specific client should see. Clients with +## `needs_consoleless_launcher = false` (Antigravity, #863) get the plain +## console command captured by `_finalize_attach_launch`; everyone else keeps +## the pythonw shape unchanged. Idempotent: the returned dict carries no +## console keys, so a second application is a no-op. +static func launch_for_client(client: Client, launch: Dictionary) -> Dictionary: + if client == null or client.needs_consoleless_launcher: + return launch + if not launch.has("console_command"): + return launch + var selected := launch.duplicate(true) + selected["command"] = selected["console_command"] + selected["args"] = selected["console_args"] + selected.erase("console_command") + selected.erase("console_args") + return selected + + +static func _resolve_consoleless_python( + command: String, tier: String, discovery_override: Dictionary +) -> String: + ## Data-only override keeps resolver tests independent of the host's Python. + if discovery_override.has("consoleless_python"): + return str(discovery_override["consoleless_python"]) + + ## Venv/system console-script launchers normally keep pythonw beside their + ## python.exe. The dev tier must use that exact interpreter so godot_ai is + ## imported from the selected checkout rather than some unrelated install. + var sibling := command.get_base_dir().path_join("pythonw.exe") + if FileAccess.file_exists(sibling): + return sibling + if tier == "dev_venv": + return "" + + ## uvx may be installed without a PATH-visible CPython. Ask its sibling uv + ## for the already-managed system interpreter; Godot AI's existing uvx + ## server launch ensures one normally exists before client configuration. + if tier == "uvx": + var uv := command.get_base_dir().path_join("uv.exe") + if not FileAccess.file_exists(uv): + uv = CliFinder.find(["uv.exe"]) + if not uv.is_empty(): + var probe := McpCliExec.run( + uv, ["python", "find", "--system"], _DISCOVERY_TIMEOUT_MS, false + ) + if int(probe.get("exit_code", -1)) == 0: + var python := str(probe.get("stdout", "")).strip_edges() + if not python.is_empty(): + var managed_pythonw := python.get_base_dir().path_join("pythonw.exe") + if FileAccess.file_exists(managed_pythonw): + return managed_pythonw + + ## A system Python GUI launcher is sufficient for the non-dev bootstrap; + ## it does not import godot_ai itself. + return CliFinder.find(["pythonw.exe"]) + + +static func _system_version_from_probe(probe: Dictionary) -> Dictionary: + if int(probe.get("exit_code", -1)) != 0: + return {"ok": false} + var output := str(probe.get("stdout", "")).strip_edges() + var pattern := RegEx.new() + if pattern.compile("^godot-ai\\s+([^\\s]+)(?:\\s|$)") != OK: + return {"ok": false} + var matched := pattern.search(output) + if matched == null: + return {"ok": false} + return {"ok": true, "version": matched.get_string(1)} + + +static func _attach_discovery_error(message: String) -> Dictionary: + return {"ok": false, "error": message} + + +## Override for the dev-vs-user heuristic. Accepted values: +## "dev" — force dev-checkout mode (skip update check + self-install) +## "user" — force user-install mode (run update check, allow self-install) +## as long as the data-safety guard (addons_dir_is_symlink) passes +## other / unset — "auto": fall back to the .venv-proximity heuristic +## +## Use `user` to test the AssetLib self-update flow from inside a dev +## checkout (there's a .venv nearby but `addons/godot_ai` is a plain copy — +## e.g. after unpacking a release zip into `test_project/`). +## +## Two ways to set it, resolved in priority order: +## 1. EditorSettings → `godot_ai/mode_override` — set manually via +## Editor Settings (no dock UI writes it today); persists +## per-editor-install and wins over the env var so an editor-side +## choice always takes effect without relaunching. +## 2. Env var `GODOT_AI_MODE` — useful for CLI launches and CI. +const MODE_OVERRIDE_ENV := "GODOT_AI_MODE" +const MODE_OVERRIDE_SETTING := "godot_ai/mode_override" + + +static func mode_override() -> String: + # 1. EditorSetting wins — the user explicitly set it via Editor Settings. + # _editor_setting_lookup handles the `Engine.is_editor_hint()` gate + # (no-op in the game subprocess; see CLAUDE.md "Game-side code") and + # serves worker threads from a main-thread-warmed snapshot — this + # runs on the #678 startup walk's discovery worker, and + # EditorInterface/EditorSettings are not thread-safe (#691). + var setting: Variant = _editor_setting_lookup(MODE_OVERRIDE_SETTING) + if setting != null: + var setting_val := str(setting).strip_edges().to_lower() + if setting_val == "dev" or setting_val == "user": + return setting_val + # 2. Env var fallback. env_lookup, not OS.get_environment: same + # worker-thread reason (#691). + var raw := McpPathTemplate.env_lookup(MODE_OVERRIDE_ENV).strip_edges().to_lower() + if raw == "dev" or raw == "user": + return raw + return "" + + +static func is_dev_checkout() -> bool: + match mode_override(): + "dev": + return true + "user": + return false + return not _find_venv_python().is_empty() + + +## Data-safety check for self-install: is `res://addons/godot_ai` a symbolic +## link? In a dev checkout this points at the canonical `plugin/` source +## tree, and writing files into it would clobber tracked source. This check +## is independent of `is_dev_checkout()` so a forced-user mode override +## still cannot extract a release zip over the symlink. +static func addons_dir_is_symlink() -> bool: + return _is_symlink(ProjectSettings.globalize_path("res://addons/godot_ai")) + + +## Mirrors the idiom used in `mcp_dock.gd::_resolve_plugin_symlink_target` — +## open the parent dir and ask Godot via `DirAccess.is_link()`, which +## handles symlinks on POSIX and reparse points on Windows natively. +static func _is_symlink(path: String) -> bool: + if path.is_empty(): + return false + var dir := DirAccess.open(path.get_base_dir()) + if dir == null: + ## This is a data-safety guard (a symlinked addons dir is a dev + ## checkout self-update must never write through). When the path + ## exists but its parent can't be opened, we can't PROVE it isn't + ## a link — fail closed and treat it as one (#711). + return DirAccess.dir_exists_absolute(path) or FileAccess.file_exists(path) + return dir.is_link(path) + + +## `refresh` forces uvx to re-fetch PyPI index metadata on spawn — used by +## `_start_server`'s one-shot retry when the first attempt exited fast with +## no pid-file on the uvx tier (stale-index-cache failure mode). No-op on +## other tiers: dev_venv and system resolve locally, so the flag has nowhere +## to go. See plugin.gd::_should_retry_with_refresh. +static func get_server_command(refresh: bool = false) -> Array[String]: + ## `mode_override() == "user"` skips the dev_venv tier even when a nearby + ## .venv exists — the override then becomes an actual workaround for + ## the "user venv misidentified as dev checkout" bug, not just a + ## cosmetic relabel. + if mode_override() != "user": + var venv_python := _cached_venv_python() + if not venv_python.is_empty(): + print("MCP | using dev venv: %s" % venv_python) + return [venv_python, "-m", "godot_ai"] + + var uvx := find_uvx() + if not uvx.is_empty(): + var version := get_plugin_version() + ## PEP 440 local build tags (e.g. 3.0.2+local.1) are not on PyPI. + ## Pin uvx to the public base version so the server still boots; + ## checkout-local extras need the dev_venv tier above + ## (symlink/junction → repo .venv). + var pypi_version := _pypi_pin_version(version) + ## Pin to the EXACT plugin version rather than `~=`. Under the + ## tilde form, uvx was happy to reuse a cached tool env that matched + ## the minor constraint — so an install that first spawned 1.2.0 kept + ## using 1.2.0 even after 1.2.1/1.2.2 landed. Exact pinning makes the + ## cache key version-specific: if the cached env matches, fast hit; + ## otherwise uvx installs the exact version fresh. Keeps plugin and + ## server version in lockstep without needing `--refresh-package` on + ## every spawn. See issue #133. + if pypi_version != version: + print( + "MCP | using uvx (godot-ai==%s; local plugin %s not on PyPI)%s" + % [pypi_version, version, " [refresh]" if refresh else ""] + ) + else: + print("MCP | using uvx (godot-ai==%s)%s" % [pypi_version, " [refresh]" if refresh else ""]) + var cmd: Array[String] = [uvx] + if refresh: + cmd.append("--refresh") + cmd.append_array(["--from", "godot-ai==%s" % pypi_version, "godot-ai"]) + return cmd + + var system_cmd := _find_system_install() + if not system_cmd.is_empty(): + print("MCP | using system install: %s" % system_cmd) + return [system_cmd] + + push_warning("MCP | no server found — install uv or run: pip install godot-ai") + return [] + + +## Which tier `get_server_command` would resolve to, without side-effects. +## Returned as a stable string so handshakes and session_list can expose it +## to MCP callers. Values track the `Literal` on the Python side. +static func get_server_launch_mode() -> String: + if mode_override() != "user" and not _cached_venv_python().is_empty(): + return "dev_venv" + if not find_uvx().is_empty(): + return "uvx" + if not _find_system_install().is_empty(): + return "system" + return "unknown" + + +## Wall-clock budget for the Configure-time pre-warm. Far above +## `McpCliExec.DEFAULT_TIMEOUT_MS` (8s) on purpose: this call is *expected* to +## take tens of seconds on a cold cache — downloading and unpacking the tool +## environment is the entire point — so the usual CLI-registry budget would +## kill it right when it is doing useful work. Still bounded so a wedged uv +## can't hold the worker thread forever. +const PREWARM_TIMEOUT_MS := 180000 + + +static func find_uvx() -> String: + return CliFinder.find(_uvx_cli_names()) + + +## Pre-build the uvx tool environment for `godot-ai==` in the +## background, so the FIRST spawn of that version is a warm cache hit. +## Fired when a self-update install starts: post-update the old backend is +## killed and the new one spawned, and a cold `uvx --from godot-ai==` +## resolve+install takes seconds — while an attach bridge pinned to the OLD +## version respawns its already-cached backend near-instantly, winning the +## port bind race every time (the INCOMPATIBLE dead end after every +## self-update with a live AI client). Warming the new env while the plugin +## zip downloads flips that race. +## +## `--version` makes the spawned process exit immediately after uv resolves +## and installs the env. Detached fire-and-forget: a failure only means the +## post-update spawn pays the cold cost it always used to. Returns the +## spawned PID, or -1 when skipped (no uvx on this machine — the dev-venv +## and system tiers have no per-version cache to warm — or no version). +static func prewarm_server_package(version: String) -> int: + var args := prewarm_server_package_argv(version) + if args.is_empty(): + return -1 + var uvx := find_uvx() + if uvx.is_empty(): + return -1 + var pid := OS.create_process(uvx, args) + if pid > 0: + print("MCP | pre-warming godot-ai==%s server package for the post-update restart" % version.strip_edges()) + return pid + + +## Pure argv builder for the pre-warm spawn, split out so tests can pin the +## exact command without spawning a process. Empty array when there is no +## version to pin, or when the version carries characters outside the PEP +## 440 alphabet — the value can originate from a GitHub release tag, and +## while OS.create_process argv can't be shell-injected, constraining the +## pin keeps a hostile tag from smuggling anything into the requirement +## spec uv parses (#890 review). +static func prewarm_server_package_argv(version: String) -> Array[String]: + var pinned := version.strip_edges() + if pinned.is_empty(): + return [] + ## No `*`: PEP 440 reserves it for prefix-match SPECIFIERS (`==3.2.*`), + ## not version identifiers — letting it through would turn the exact pin + ## into a prefix match (#890 CodeRabbit). + var re := RegEx.new() + if re.compile("^[A-Za-z0-9.+!-]+$") != OK or re.search(pinned) == null: + return [] + return ["--from", "godot-ai==%s" % pinned, "godot-ai", "--version"] + + +## Blocking sibling of `prewarm_server_package`, for the user-initiated +## Configure flow (#851, and the reconnect timeouts reported alongside it). +## +## Why Configure needs its own pre-warm: `prewarm_server_package` only fires +## on self-update and on server-lifecycle recovery. Neither covers the case +## that actually bites — the plugin ADOPTS an already-running server (no uvx +## spawn, so nothing warms the env), the user clicks Configure, and the first +## client launch is the one that pays for building the whole tool environment. +## That build is ~67 packages; a warm launch is ~0.1s. Two symptoms fall out +## of the cold path: a visible terminal window on Windows (#851), and a spawn +## that overruns the MCP client's default 30s connect timeout, which the user +## sees as the Godot AI tools silently disappearing. +## +## Why blocking, unlike the fire-and-forget server-side pre-warm: Configure is +## a deliberate click, so the cost is attributable and the dock can show it as +## progress rather than as an unexplained pause. Runs on the dock's client +## action worker thread — never the main thread — and `McpCliExec.run` bounds +## it, so a wedged uv cannot trap the worker. +## +## Best-effort by contract. The config file is already written and correct +## when this runs; a failure here only means the next client launch pays the +## cold cost it always used to. Callers must NOT downgrade a successful +## Configure because of this result. +## +## Returns the `McpCliExec.run` dict, plus `skipped` (true when there is no +## uvx tier to warm or no usable version pin). +static func prewarm_server_package_blocking( + version: String, + timeout_ms: int = PREWARM_TIMEOUT_MS, + cancel_check: Callable = Callable(), +) -> Dictionary: + var args := prewarm_server_package_argv(version) + if args.is_empty(): + return {"skipped": true, "reason": "no version pin"} + var uvx := find_uvx() + if uvx.is_empty(): + ## dev-venv and system tiers have no per-version cache to warm. + return {"skipped": true, "reason": "no uvx"} + var result := McpCliExec.run(uvx, args, timeout_ms, true, cancel_check) + result["skipped"] = false + return result + + +## Decide whether the freshly-written entry has an environment worth warming. +## +## Pure and side-effect free, split from the spawn below so tests can pin the +## decision without building a real uv environment — the same split +## `prewarm_server_package_argv` uses for the argv (#890). +## +## Warms only the `uvx` tier: dev-venv and system launches run an +## already-installed package and have no per-version environment to build. +## Resolving the tier here rather than in the dock keeps launcher knowledge in +## the configurator; the dock stays free of tier branching. +## +## Returns `{warm: bool, version: String, reason: String}`. +static func prewarm_attach_plan( + launch_context: Dictionary, discovery_override: Dictionary = {} +) -> Dictionary: + var launch := resolve_attach_launch(launch_context, discovery_override) + if not bool(launch.get("ok", false)): + return {"warm": false, "version": "", "reason": "launch discovery failed"} + var tier := str(launch.get("tier", "")) + if tier != "uvx": + return {"warm": false, "version": "", "reason": "tier %s has no env to warm" % tier} + var version := _pypi_pin_version(str(launch_context.get("plugin_version", ""))) + if version.is_empty(): + return {"warm": false, "version": "", "reason": "no version pin"} + return {"warm": true, "version": version, "reason": ""} + + +## Warm the environment the freshly-written entry will actually launch. +## Thin wrapper over `prewarm_attach_plan` + `prewarm_server_package_blocking`. +static func prewarm_attach_launch( + launch_context: Dictionary, + timeout_ms: int = PREWARM_TIMEOUT_MS, + discovery_override: Dictionary = {}, + cancel_check: Callable = Callable(), +) -> Dictionary: + var plan := prewarm_attach_plan(launch_context, discovery_override) + if not bool(plan.get("warm", false)): + return {"skipped": true, "reason": str(plan.get("reason", ""))} + return prewarm_server_package_blocking( + str(plan.get("version", "")), timeout_ms, cancel_check + ) + + +static func _uvx_cli_names() -> Array[String]: + var names: Array[String] = [] + names.append("uvx.exe" if OS.get_name() == "Windows" else "uvx") + return names + + +## Drop the `CliFinder` cache for the platform-specific uvx binary +## name. Pairs with `invalidate_uv_version_cache()` so the dock's +## `_on_install_uv` can refresh both caches with one call each. The +## OS-specific name matters: Windows caches under `uvx.exe`, every +## other platform under `uvx`; hard-coding `"uvx"` here would leave +## the CLI-path cache stale on Windows after a fresh install and the +## dock would keep showing "uv: not found" for the rest of the session. +static func invalidate_uvx_cli_cache() -> void: + for name in _uvx_cli_names(): + CliFinder.invalidate(name) + + +## Drop the entire `CliFinder` cache. Called from any explicit-user-action +## refresh path (`force=true` in `_request_client_status_refresh` — manual +## Refresh button, popup-open, compat wrapper, future external API) so a +## freshly-installed CLI (claude, codex, gemini, …) gets detected without +## an editor restart. Per-CLI invalidation (`invalidate_uvx_cli_cache`) is +## preferred when the dock knows which binary changed; this catch-all +## handles the "any CLI may have been installed since the last sweep" case. +## +## Thread safety: `CliFinder.invalidate()` guards `_cache` / `_searched` +## with a mutex so it can race safely against worker threads calling +## `find()` from `_run_client_action_worker`. The mutex is held only +## across the dictionary clear, never across the bounded subprocess lookup, +## so this call can never block the main thread on a subprocess. +static func invalidate_cli_cache() -> void: + CliFinder.invalidate() + + +static var _uv_version_cache: String = "" +static var _uv_version_searched: bool = false + + +## Cached for the editor session. The dock's `_refresh_setup_status` +## (called via `call_deferred` from `_build_ui`) calls this on the +## main thread in user mode, so the cold `uvx --version` probe is +## wall-clock bounded and cached. Subsequent calls (focus-in refresh, +## manual Refresh clicks) reuse the cached string. +## +## Invalidate via `invalidate_uv_version_cache()` when the user +## installs / reinstalls uv via the dock so the next refresh reflects +## the new install. The dock's `_on_install_uv` calls this alongside +## `CliFinder.invalidate("uvx")` to clear both the path cache and +## the version cache in one place. +static func check_uv_version() -> String: + if _uv_version_searched: + return _uv_version_cache + var uvx := find_uvx() + if uvx.is_empty(): + _uv_version_searched = true + _uv_version_cache = "" + return "" + var result := McpCliExec.run(uvx, ["--version"], _DISCOVERY_TIMEOUT_MS, false) + if int(result.get("exit_code", -1)) == 0: + var lines := PackedStringArray(str(result.get("stdout", "")).split("\n")) + _uv_version_cache = lines[0].strip_edges() if lines.size() > 0 else "" + else: + _uv_version_cache = "" + _uv_version_searched = true + return _uv_version_cache + + +static func invalidate_uv_version_cache() -> void: + _uv_version_searched = false + _uv_version_cache = "" + + +## True when a probe has run this session and came back empty — i.e. the +## dock is currently rendering "uv: not found". Lets callers decide when +## a re-probe is worth paying for (server-connect transition, manual +## Refresh) without ever re-probing once uv has been found. +static func uv_probe_negative() -> bool: + return _uv_version_searched and _uv_version_cache.is_empty() + + +## Drop both uv caches — the resolved uvx path AND the cached +## `uvx --version` output — so the next check_uv_version() re-runs the +## full detection. #739: a probe that fails once at editor startup +## (contended spawn, cold Defender scan, stale PATH under a +## Steam-launched editor) used to pin "uv: not found" for the whole +## session; the Install-uv click was the only invalidation path. Callers +## invoke this on events that suggest the failure was transient. +static func invalidate_uv_detection() -> void: + invalidate_uvx_cli_cache() + invalidate_uv_version_cache() + _attach_launch_cache_mutex.lock() + _attach_launch_cache.clear() + _attach_launch_cache_mutex.unlock() + + +static var _venv_python_cache: String = "" +static var _venv_python_searched: bool = false +## #678 worker threads write this cache while main-thread callers read +## it; same lock discipline as McpCliFinder (clients/_cli_finder.gd). +static var _venv_mutex: Mutex = Mutex.new() +static var _attach_launch_cache := {} +static var _attach_launch_cache_mutex := Mutex.new() + + +static func _attach_launch_cache_key(launch_context: Dictionary) -> String: + return JSON.stringify([ + launch_context.get("http_port", null), + launch_context.get("ws_port", null), + launch_context.get("excluded_domains", null), + launch_context.get("plugin_version", null), + launch_context.get("allow_dev_venv", null), + launch_context.get("platform", null), + launch_context.get("telemetry_enabled", null), + ]) + + +static func _cached_venv_python() -> String: + _venv_mutex.lock() + if not _venv_python_searched: + _venv_python_cache = _find_venv_python() + _venv_python_searched = true + var cached := _venv_python_cache + _venv_mutex.unlock() + return cached + + +## Absolute path to `res://addons/godot_ai`, resolving Windows junctions / +## POSIX symlinks via `DirAccess.read_link`. Unresolved globalize_path only +## walks the *logical* project path (e.g. MyGame/addons/godot_ai → MyGame) +## and never reaches a fork checkout's `.venv` (…/godot-ai/.venv). +static func resolve_addons_realpath() -> String: + var addons_path := ProjectSettings.globalize_path("res://addons/godot_ai").rstrip("/").rstrip("\\") + if addons_path.is_empty(): + return "" + var parent := addons_path.get_base_dir() + var dir := DirAccess.open(parent) + if dir != null and dir.is_link(addons_path): + var target := dir.read_link(addons_path) + if not target.is_empty(): + if target.is_relative_path(): + target = parent.path_join(target).simplify_path() + return target.rstrip("/").rstrip("\\") + return addons_path + + +static func _find_venv_python() -> String: + ## Optional hard override (junction edge cases / CI). + var env_py := McpPathTemplate.env_lookup("GODOT_AI_VENV_PYTHON").strip_edges() + if not env_py.is_empty(): + if FileAccess.file_exists(env_py): + return env_py + ## An explicit override pointing nowhere is a misconfiguration the + ## user needs to see — falling through silently would make the dev + ## venv appear randomly ignored. + push_warning( + "godot-ai: GODOT_AI_VENV_PYTHON is set but no file exists at '%s'; ignoring override." + % env_py + ) + ## 1) Walk up from the open project (classic monorepo / test_project layout). + var from_project := _find_venv_python_in( + ProjectSettings.globalize_path("res://").rstrip("/").rstrip("\\") + ) + if not from_project.is_empty(): + return from_project + ## 2) Junctioned plugin: resolve reparse target, then walk up to fork root. + var addons_real := resolve_addons_realpath() + if not addons_real.is_empty(): + var from_addons := _find_venv_python_in(addons_real) + if not from_addons.is_empty(): + return from_addons + return "" + + +## Pure path-based lookup so tests can drive it with a scratch dir instead of +## monkey-patching `res://`. Only treats a `.venv/bin/python` as a godot-ai dev +## venv if a sibling `src/godot_ai/` exists in the same parent dir — otherwise +## an unrelated user venv (e.g. `~/.venv` from a data-science side project) +## gets picked up and `python -m godot_ai` fails with ModuleNotFoundError about +## 5s into startup, cascading into an infinite reconnect loop. The retry-with- +## refresh recovery in `plugin.gd::_should_retry_with_refresh` only fires on +## the uvx tier, so the dev_venv misidentification has no escape hatch — the +## detection has to be right the first time. +static func _find_venv_python_in(start_dir: String) -> String: + var dir := start_dir.rstrip("/").rstrip("\\") + var python_name := "python" if OS.get_name() != "Windows" else "python.exe" + var venv_dir := ".venv/bin/" if OS.get_name() != "Windows" else ".venv/Scripts/" + ## 8 hops: game project roots are shallow; junctioned plugins sit at + ## /plugin/addons/godot_ai (4) and nested worktrees may be deeper. + for i in 8: + var venv_path := dir.path_join(venv_dir + python_name) + if FileAccess.file_exists(venv_path) and DirAccess.dir_exists_absolute(dir.path_join("src/godot_ai")): + return venv_path + var parent := dir.get_base_dir() + if parent == dir or parent.is_empty(): + break + dir = parent + return "" + + +## Walk up from `start_dir` looking for a sibling `src/godot_ai/` — returns +## the absolute path of the enclosing `src/` dir, or "". Used by the dev +## server launcher to prepend the caller's own source to PYTHONPATH so a +## worktree-launched editor serves the worktree's Python, not the root +## repo's editable install. See #84. +static func find_worktree_src_dir(start_dir: String) -> String: + var dir := start_dir.rstrip("/") + for i in 5: + var candidate := dir.path_join("src/godot_ai") + if DirAccess.dir_exists_absolute(candidate): + return dir.path_join("src") + var parent := dir.get_base_dir() + if parent == dir: + break + dir = parent + return "" + + +## Delegates to McpCliFinder rather than shelling out to which/where +## directly: the finder adds the well-known-install-dirs and login-shell +## PATH tiers plus its per-exe cache, and this drops the private +## `_pick_best_path` cross-class reach (#711). +static func _find_system_install() -> String: + ## Built with append, not a ternary of untyped literals — assigning a + ## ternary's Array to Array[String] is a runtime error on newer Godot + ## builds (same idiom as _uvx_cli_names above). + var names: Array[String] = ["godot-ai"] + if OS.get_name() == "Windows": + names.push_front("godot-ai.exe") + return CliFinder.find(names) diff --git a/addons/godot_ai/client_configurator.gd.uid b/addons/godot_ai/client_configurator.gd.uid new file mode 100644 index 0000000..9182096 --- /dev/null +++ b/addons/godot_ai/client_configurator.gd.uid @@ -0,0 +1 @@ +uid://1kiy8hqyymyj diff --git a/addons/godot_ai/clients/_atomic_write.gd b/addons/godot_ai/clients/_atomic_write.gd new file mode 100644 index 0000000..3dbf72c --- /dev/null +++ b/addons/godot_ai/clients/_atomic_write.gd @@ -0,0 +1,251 @@ +@tool +class_name McpAtomicWrite +extends RefCounted + +## Write text to a file via temp + rename so a crash mid-write never leaves +## the user's MCP config truncated. Creates the parent dir if needed and +## keeps a one-shot `.backup` of the prior file. +## +## On filesystems where rename-over-existing fails (Windows under AV / lock +## pressure, some SMB shares), falls back to overwrite-copy plus a +## backup-restore on failure. The original file is never removed before the +## new bytes are verified on disk — if both the rename and the copy fail, +## the user's prior config is restored from the `.backup` snapshot. See +## issue #297 finding #10 for the data-loss scenario this guards against. + + +static func write(path: String, content: String) -> bool: + # Last line of defence for the path-resolution layer above. A relative (or + # empty) destination resolves against the EDITOR's working directory, not the + # caller's. The empty-path case is especially deceptive: editor safe-save + # runs mkstemp on "-XXXXXX", writes the payload into the project root, then + # fails only when renaming back to "" and leaves the random file behind. + # Callers gate this already (`McpClient.resolved_config_path_details`), but a + # writer that cannot tell where it is writing must refuse rather than guess. + if not path.is_absolute_path(): + return false + # If the target is a symlink (stow/chezmoi-managed dotfiles), rename-over + # would replace the LINK with a regular file, silently detaching the + # config from the user's dotfile repo (#534). Resolve the link chain and + # write to the real target so the symlink survives. + path = _resolve_symlink_target(path) + var dir_path := path.get_base_dir() + if not DirAccess.dir_exists_absolute(dir_path): + if DirAccess.make_dir_recursive_absolute(dir_path) != OK: + return false + + # Decide the permission mode the final file (and its backup) must carry + # BEFORE we replace anything. A rewrite must preserve the prior file's + # mode: the Claude CLI creates ~/.claude.json as 0600 (it holds OAuth + # creds + history), and a naive FileAccess write + DirAccess copy would + # silently relax that to the umask default (0644) and leak it on shared + # machines. A brand-new config defaults to owner-only 0600 since these + # files routinely carry tokens. On platforms without POSIX permissions + # (Windows) the get/set calls no-op and this logic is inert. See #297 + # finding TC-1. + var had_original := FileAccess.file_exists(path) + var target_mode := _resolve_target_mode(path, had_original) + + # Suffix the temp name with this process's PID so two editors writing the + # same config concurrently (both clicking Configure) can't interleave + # bytes on a shared fixed ".tmp" path (#534). Each process stages its own + # temp file; the final rename remains the atomic commit point. + var tmp_path := "%s.tmp.%d" % [path, OS.get_process_id()] + var file := _open_restricted_temp(tmp_path, target_mode) + if file == null: + return false + file.store_string(content) + # Push Godot's internal buffer out to the OS before the rename. Godot + # exposes no fsync, so the bytes aren't guaranteed durable on the physical + # disk until the OS flushes its own cache — a power loss in that window can + # still lose the data. But flush() ensures the rename can't be ordered ahead + # of the write at the application layer, which is the failure this guards. + file.flush() + file.close() + # Re-assert the mode on the closed inode before rename. The temp was already + # restricted before this handle opened, so this is defence in depth rather + # than the first point at which secrets become owner-only. + if not _apply_mode(tmp_path, target_mode): + DirAccess.remove_absolute(tmp_path) + return false + + # Verify the staged temp landed intact before committing it anywhere. The + # copy-fallback path below already guards this (`_written_size_matches` at + # the rename-fallback check); the rename path was the one gap — under + # disk-full/quota the temp can be silently truncated, and an unverified + # rename would swap a truncated file over the live target while the + # caller is told the write succeeded (#687). + if not _written_size_matches(tmp_path, content): + DirAccess.remove_absolute(tmp_path) + return false + + # Best-effort: snapshot the prior file before we touch the target so we + # can restore on a failed swap. The backup is also kept on success as a + # one-shot rollback aid for the user — give it the same (preserved) mode + # so a 0600 config's backup isn't itself a world-readable copy. + # + # copy_absolute creates the backup at the umask default and we can only + # chmod it afterward, so there's a sub-millisecond window where the backup + # carries default perms. Accepted: it duplicates bytes already sitting at + # `path` (which the caller created 0600) inside the user's own config dir, + # and Godot exposes no API to create the copy pre-chmod'd. Not worth + # reimplementing copy by hand to shave that window. + var backup_path := path + ".backup" + var backup_made := false + if had_original: + DirAccess.remove_absolute(backup_path) + if DirAccess.copy_absolute(path, backup_path) == OK: + if not _apply_mode(backup_path, target_mode): + ## The backup contains the same secrets as the live config. Do + ## not leave that copy behind — or touch the destination — when + ## it cannot be restricted to the intended mode. + DirAccess.remove_absolute(backup_path) + DirAccess.remove_absolute(tmp_path) + return false + backup_made = true + else: + ## copy_absolute may leave a partial destination on failure. It + ## contains config bytes under the process umask, so remove it. + DirAccess.remove_absolute(backup_path) + + if DirAccess.rename_absolute(tmp_path, path) == OK: + return true + + # Rename-over-existing rejected (Windows + AV / lock timing, some SMB + # shares). Use overwrite-copy as the recovery path: copy_absolute never + # removes the original before writing the new bytes, so a failure here + # leaves the user's prior config in place rather than nuking it. + if DirAccess.copy_absolute(tmp_path, path) == OK and _written_size_matches(path, content): + # copy_absolute creates the destination with the default mode, so + # re-apply the preserved/owner-only mode after the copy lands. A + # permission failure is a failed write: fall through to the same + # restore/remove path as a partial copy instead of reporting success + # with a potentially exposed token-bearing config. + if _apply_mode(path, target_mode): + DirAccess.remove_absolute(tmp_path) + return true + + # Copy didn't land cleanly. Restore the destination to its pre-call state. + if backup_made: + # Restore the snapshot we took before the swap. `copy_absolute` + # overwrites the destination, so we don't pre-remove `path` — the + # pre-remove created a window where `path` was gone if the + # subsequent copy itself failed. If the restore copy fails now the + # user's prior bytes are still in `.backup` for manual recovery + # and the false return value tells the caller the swap didn't + # complete. + var restored := ( + DirAccess.copy_absolute(backup_path, path) == OK + and _apply_mode(path, target_mode) + ) + if not restored: + ## The backup's mode was already verified before the swap. Remove + ## any partial/default-mode destination, then move that restricted + ## inode back into place. If even the same-directory rename fails, + ## the complete prior contents remain in `.backup` for recovery. + DirAccess.remove_absolute(path) + DirAccess.rename_absolute(backup_path, path) + elif not had_original and FileAccess.file_exists(path): + # No prior file existed but copy_absolute landed partial bytes at + # `path`. Remove them so the failure leaves nothing on disk rather + # than a truncated/invalid new file. The `file_exists` guard keeps + # us off non-file destinations (a path that points at a directory + # yields `had_original=false` too, but we must not try to delete + # the directory). Issue #297 PR review. + DirAccess.remove_absolute(path) + # (If `had_original` is true but the snapshot couldn't be taken, the + # original on disk is whatever copy_absolute managed to write before + # failing. This is a best-effort path — the false return value tells the + # caller the swap didn't complete; recovery beyond that requires a + # backup we couldn't take.) + DirAccess.remove_absolute(tmp_path) + return false + + +## Follow a symlink chain at `path` and return the final real target, so the +## temp+rename lands on the linked-to file instead of replacing the link. +## +## Best-effort by design: DirAccess.is_link()/read_link() are only implemented +## on platforms with POSIX symlinks (Linux/macOS; on Windows and other +## platforms is_link() returns false), and opening the parent dir can fail for +## exotic paths. In every "can't tell" case we return `path` unchanged, which +## is exactly the pre-#534 behavior — never worse, symlink-preserving where +## the engine lets us detect one. +static func _resolve_symlink_target(path: String) -> String: + var resolved := path + # Bounded hops so a symlink cycle can't loop us forever. + for _hop in 8: + var base_dir := resolved.get_base_dir() + var da := DirAccess.open(base_dir) + if da == null or not da.is_link(resolved): + return resolved + var target := da.read_link(resolved) + if target.is_empty(): + return resolved + if target.is_relative_path(): + target = base_dir.path_join(target) + resolved = target.simplify_path() + return resolved + + +static func _resolve_target_mode(path: String, had_original: bool) -> int: + # Preserve the prior file's POSIX mode on a rewrite; default a brand-new + # config (or any case we can't read a mode for) to owner read+write (0600). + # + # get_unix_permissions returns 0 both on Windows (no POSIX perms) and for a + # genuine 0000 file. Treating 0 as "use the 0600 floor" is deliberate, not a + # missed case: these are config files the plugin must read and write, 0000 is + # unusable, and re-applying 0000 would lock the owner out next run. 0600 is + # still owner-only so this never widens access. (A genuinely-0000 file can't + # reach a rewrite through the config strategies anyway — their read-first + # guard fails to open it and refuses the write before we get here.) + if had_original: + var existing := FileAccess.get_unix_permissions(path) + if existing > 0: + return existing + return FileAccess.UNIX_READ_OWNER | FileAccess.UNIX_WRITE_OWNER + + +## Create/truncate an EMPTY temp file, close it, restrict its mode, then reopen +## it without truncation for the payload write. Godot 4.6 on macOS returns +## FAILED when set_unix_permissions targets a path whose FileAccess is still +## open; the old create -> chmod-while-open -> write sequence therefore emitted +## one warning per configured client and briefly wrote secrets under the umask +## mode. Closing the empty inode first makes the security ordering real and +## removes that platform-specific warning without suppressing genuine errors. +static func _open_restricted_temp(path: String, mode: int) -> FileAccess: + var created := FileAccess.open(path, FileAccess.WRITE) + if created == null: + return null + created.close() + if not _apply_mode(path, mode): + DirAccess.remove_absolute(path) + return null + return FileAccess.open(path, FileAccess.READ_WRITE) + + +static func _apply_mode(path: String, mode: int) -> bool: + # Best-effort. set_unix_permissions returns ERR_UNAVAILABLE on platforms + # without POSIX permissions (Windows); that's expected and ignored so the + # write still works there. mode <= 0 should never happen (resolve always + # returns >0) but is guarded so a future caller can't chmod a file to nothing. + if mode <= 0: + return true + var err := FileAccess.set_unix_permissions(path, mode) + if err == OK or err == ERR_UNAVAILABLE: + return true + # Surface a real chmod failure (not the Windows no-op) so permission + # hardening on a sensitive config doesn't fail completely silently. + push_warning("MCP | could not set permissions on %s: %s" % [path, error_string(err)]) + return false + + +static func _written_size_matches(path: String, content: String) -> bool: + # `store_string` writes UTF-8 bytes with no BOM and no newline translation, + # so the byte length on disk must match `to_utf8_buffer().size()` exactly. + var f := FileAccess.open(path, FileAccess.READ) + if f == null: + return false + var on_disk := f.get_length() + f.close() + return on_disk == content.to_utf8_buffer().size() diff --git a/addons/godot_ai/clients/_atomic_write.gd.uid b/addons/godot_ai/clients/_atomic_write.gd.uid new file mode 100644 index 0000000..add9f7f --- /dev/null +++ b/addons/godot_ai/clients/_atomic_write.gd.uid @@ -0,0 +1 @@ +uid://6fkb5uau0r4h diff --git a/addons/godot_ai/clients/_base.gd b/addons/godot_ai/clients/_base.gd new file mode 100644 index 0000000..494646a --- /dev/null +++ b/addons/godot_ai/clients/_base.gd @@ -0,0 +1,528 @@ +@tool +class_name McpClient +extends RefCounted + +## Descriptor for one MCP client (Cursor, Claude Desktop, Codex, ...). +## +## Subclasses set fields in `_init()` and MUST NOT carry Callables — strategies +## (json/toml/cli) interpret the data. Enforced by +## `test_clients.gd::test_descriptors_are_data_only`. +## +## Why no Callables: per-client `.gd` files get hot-reloaded on disk-mtime +## change. A worker thread mid-call into a descriptor lambda races the +## bytecode swap and SEGVs (issue #229). Bonus: also obsoletes the stale- +## Callable workaround from #192. + +## CONFIGURED_MISMATCH = an entry with our `SERVER_NAME` exists in the user's +## client config, but its URL or launch command doesn't match the current +## ports/version/exclusions — typical after a setting change or update. +## Distinguishing this from `NOT_CONFIGURED` lets the dock surface a "your +## saved client configuration is stale" banner instead of conflating it with +## "you never configured this client". +enum Status { NOT_CONFIGURED, CONFIGURED, CONFIGURED_MISMATCH, ERROR } + + +## Lowercase string label for a `Status` value. Single source of truth so the +## MCP `client_status` tool, the dock, and the verify-after-write diagnostic +## in `McpClientConfigurator` all emit the same names — agents pattern-match +## against this set, so a fifth value being silently introduced would break +## them. +static func status_label(status: McpClient.Status) -> String: + match status: + Status.CONFIGURED: + return "configured" + Status.NOT_CONFIGURED: + return "not_configured" + Status.CONFIGURED_MISMATCH: + return "configured_mismatch" + return "error" + + +## One-line configure success message, shared by every strategy so the dock +## and the `client_manage` tool describe the transport that was actually +## written. Command-shape clients register the stdio `godot-ai attach` +## bridge — the URL-era "(HTTP: )" suffix would name a transport the +## write never touched (found live in the #838 Windows smoke). +static func configured_message(client: McpClient, server_url: String) -> String: + if client.command_shape != CommandShape.NONE: + return "%s configured (stdio attach)" % client.display_name + return "%s configured (HTTP: %s)" % [client.display_name, server_url] + +var id: String = "" ## stable key, e.g. "cursor" +var display_name: String = "" ## "Cursor" +var config_type: String = "" ## "json" | "toml" | "yaml" | "cli" | "dsh" + +# JSON / TOML clients ------------------------------------------------------ +## {"darwin": "~/...", "windows": "$APPDATA/...", "linux": "$XDG_CONFIG_HOME/..."} +## Keys may also use "unix" as a shorthand for darwin+linux. +var path_template: Dictionary = {} + +## Optional ordered path candidates by platform. Each value is an Array of +## templates; one `*` may appear in a directory segment so packaged-app roots +## can be discovered without hardcoding publisher hashes. +## +## Resolution contract: +## 1. Existing files win in descriptor order, except that a unique wildcard +## match is authoritative even before its config leaf exists. A matching +## package root therefore creates inside that package rather than writing +## a fallback path that may become invisible after copy-on-write. When +## that private leaf is new, Configure seeds it from the first later +## existing candidate so read-through content is not shadowed. +## 2. If no file or wildcard package match exists, the first non-wildcard +## template is the deterministic create target. +## 3. Multiple matches within any wildcard group are ambiguous and fail +## closed instead of choosing an arbitrary package. +## +## Exact-file and config-home environment overrides still have higher +## priority. When this map has no entry for the current platform, +## `path_template` remains the fallback. +var config_path_candidates: Dictionary = {} + +## Optional global JSON config files merged by the client from lowest to highest +## precedence. Unlike `config_path_candidates`, every existing file participates; +## Configure updates the effective last definition, status verifies it, and +## Remove clears every global definition transactionally. +var config_merge_path_templates: Dictionary = {} +## Project-relative tiers that may override the global files. Their root is the +## external client's working directory, which the Godot process cannot know. +## The strategy checks plausible roots and fails closed instead of mutating them. +var config_merge_project_paths: PackedStringArray = PackedStringArray() + +## De-duplicate persistent path-ambiguity warnings across recurring status +## refreshes. The actionable message still returns on every resolution; only +## the editor-console echo is single-shot until the ambiguity clears/changes. +var _last_config_path_warning := "" +var _config_path_warning_mutex := Mutex.new() + +## Path inside the config object where the per-server map lives. +## Cursor / Claude Desktop / most others: ["mcpServers"] +## VS Code: ["servers"] +## OpenCode: ["mcp"] +var server_key_path: PackedStringArray = PackedStringArray() +## Alternative server-map paths accepted by the client, in precedence order +## after `server_key_path`. JSON strategy operations select the first non-null +## existing path so Configure, status, and Remove agree with the client parser. +var server_key_path_aliases: Array[PackedStringArray] = [] + +## Field inside the entry dict that holds our server URL. +## "url" by default; some clients use "serverUrl" or "httpUrl". +var entry_url_field: String = "url" + +## Required entry fields — written on every Configure AND verified by the +## default verifier. Use this for transport pins (e.g. `type: +## "streamable-http"`) where a missing/wrong value breaks negotiation: a +## legacy entry without the pin fails verification and surfaces as drift. +## +## DO NOT put user-mutable state here (auto-approval lists, `disabled` +## flags, opt-in toggles). Verifying those treats every user customisation +## as drift, and Configure-All-Mismatched then silently overwrites them +## back to defaults — see the `entry_initial_fields` doc below. +var entry_extra_fields: Dictionary = {} + +## Default fields written ONLY when the entry doesn't yet exist. Reconfigure +## preserves whatever the user (or the client itself) has set; the verifier +## ignores these keys entirely. Use for opt-in flags and user-state arrays — +## e.g. Roo / Cline / Kilo `alwaysAllow` / `autoApprove` lists, `disabled: +## false`, `isActive: true`. The pre-#229 behaviour was equivalent: per- +## client `entry_builder` lambdas seeded these as defaults but the +## per-client `verify_entry` lambdas only checked transport pins, so a +## user-customised array was `CONFIGURED`, not drift. Splitting the field +## restores that contract under the data-only descriptor model. +var entry_initial_fields: Dictionary = {} + +## Client-owned stdio launch shape. Each strategy renders the shape in its +## config language: +## +## - FLAT — `command` string + `args` array as sibling keys. JSON and YAML +## strategies. A client whose docs require a type discriminator next to the +## flat keys (VS Code's `type: "stdio"`, Claude Code's fallback file) stays +## FLAT and declares it via `command_transport_key` / `command_transport_value`, +## so TYPED_FLAT remains reserved vocabulary. +## - COMMAND_ARRAY — the launch argv carried as one array. In the JSON +## strategy the entry's `command` field IS that array (OpenCode's +## `"command": ["uvx", …]`). In the TOML strategy the launcher renders as a +## `command = "…"` line plus an `args = […]` array (Codex, Grok) — the name +## refers to the argv-as-TOML-array body it emits. +## - NESTED_COMMAND — command/args nested inside a sub-object. Reserved; no +## current client needs it and strategies reject it with an actionable error. +## +## CLI-registered clients (`config_type == "cli"`) express the launch through +## `cli_register_template` tokens instead; their `command_shape` governs the +## JSON-fallback file rendering (Claude Code, #463). +## +## Values are data-only shared vocabulary; keeping them data-only avoids +## reintroducing the descriptor Callable race from #229. +enum CommandShape { NONE, FLAT, TYPED_FLAT, COMMAND_ARRAY, NESTED_COMMAND } +var command_shape: CommandShape = CommandShape.NONE + +## Whether manual instructions may offer the client's native URL transport as +## an alternative to its command shape. This is capability metadata, not a +## consequence of `command_shape`: Codex supports a URL block, while Claude +## Desktop's local `claude_desktop_config.json` entries are stdio-only. +var command_supports_url_fallback: bool = false + +## Optional discriminator required by a client's command transport shape +## (for example `type = "stdio"`). Empty means command+args are sufficient. +var command_transport_key: String = "" +var command_transport_value: Variant = null + +## Whether this client's Windows stdio entry must launch through the +## GUI-subsystem pythonw bootstrap (#827). The bootstrap exists for clients +## that run console-subsystem MCP commands in a visible terminal (Codex); +## Electron-family spawners hide child consoles themselves, and at least one +## (Antigravity) hangs tool calls when handed a GUI-subsystem executable +## (#863). Set false to write the plain console launcher on Windows. +var needs_consoleless_launcher: bool = true + +## Keys from the legacy transport that Configure must delete. Codex removes +## `url`, because Codex rejects a server entry containing both URL and stdio +## launch fields. +var command_legacy_keys: PackedStringArray = PackedStringArray() + +## Keys inside a preserved JSON `env` object that belonged to a legacy launch +## shape and must be removed during migration. Other environment values remain +## user-owned and survive Configure. Currently consumed by the JSON strategy. +var command_env_legacy_keys: PackedStringArray = PackedStringArray() + +## Defaults seeded only for a new entry. Reconfigure preserves user values. +## Codex uses this for enabled/startup/tool timeout defaults. +var command_initial_fields: Dictionary = {} + +## Declarative documentation of fields owned by the user and timeout fields +## supported by this client. Strategies preserve these values and tests pin +## the descriptor contract; no control flow lives on the descriptor. +var command_user_fields: PackedStringArray = PackedStringArray() +var command_timeout_fields: PackedStringArray = PackedStringArray() + +## Paths whose existence implies the user has this client installed. +## Used purely for the dock's "installed" badge. `is_installed()` additionally +## checks `resolved_config_path()`, so a config relocated via an environment +## override is detected without listing it here. +var detect_paths: PackedStringArray = PackedStringArray() + +# Config-path env overrides -------------------------------------------------- +## Some clients name the exact config file in an environment variable +## (OpenCode: `$OPENCODE_CONFIG`). When the variable is set and non-empty, it +## wins over directory-valued `config_home_env` and `path_template`. Relative +## values fail closed because the editor and client may have different working +## directories; auto-configuration cannot safely assume they resolve alike. +var config_file_env: String = "" + +## Some clients honor an env var that relocates their entire config home +## (Codex: `$CODEX_HOME/config.toml`; Claude Code: `$CLAUDE_CONFIG_DIR/.claude.json`). +## When `config_home_env` names an env var that is set and non-empty, +## `resolved_config_path()` returns `/` +## instead of resolving `path_template`. Both fields must be non-empty for the +## override to apply. Only declare a mapping when the client's docs guarantee +## the env var relocates the exact file we write — a wrong mapping writes the +## MCP entry somewhere the client never reads and Configure false-succeeds. +## Relative values fail closed for the same reason `config_file_env`'s do. +var config_home_env: String = "" +## Path of the config file relative to the env var's directory, e.g. +## "config.toml". Joined verbatim — no per-OS variants needed because the env +## value itself is already an absolute (or ~-prefixed) directory. +var config_home_env_subpath: String = "" + +# CLI clients -------------------------------------------------------------- +var cli_names: PackedStringArray = PackedStringArray() +## Argument templates with `{name}` and `{url}` tokens; the strategy +## substitutes them at call time. Tokens are matched verbatim — no escaping +## semantics, no shell expansion. Command-shape templates additionally use the +## whole-element tokens `{command}` / `{args...}` (see `McpCliStrategy.format_args`). +## Populated by CLI descriptors (currently `claude_code`; `kimi_code` moved to +## mcp.json in #813). +var cli_register_template: PackedStringArray = PackedStringArray() +var cli_unregister_template: PackedStringArray = PackedStringArray() +## Args run to read current state; stdout is scanned for the server name and +## URL. Presence of `name` AND `url` → CONFIGURED, name only → MISMATCH, +## neither → NOT_CONFIGURED. +var cli_status_args: PackedStringArray = PackedStringArray() +## Optional scope-aware status template with a `{name}` token, for descriptors +## that also take `{scope}` in their register template. `cli_status_args` lists +## whatever the CLI resolves for the current directory and cannot say WHICH +## scope an entry came from, so a leftover user-scope entry reads as CONFIGURED +## while the selected project scope is empty — the dock then shows green over +## exactly the "loaded in every workspace" state the scope setting exists to +## end (#872). This template must print a `Scope: …` line +## (`claude mcp get ` does) and exit non-zero when the server is absent. +## Only consulted when the selected scope isn't the one `path_template` reads. +var cli_scope_status_template: PackedStringArray = PackedStringArray() + +# Codex / TOML clients ----------------------------------------------------- +## Dotted TOML path under which our entry lives, e.g. ["mcp_servers", "godot-ai"]. +## Strategies build the [section."name"] header from this. +var toml_section_path: PackedStringArray = PackedStringArray() +var toml_legacy_section_aliases: PackedStringArray = PackedStringArray() +## Lines (without the [header]) emitted under the section, with `{url}` +## tokens. Substituted at call time. +var toml_body_template: PackedStringArray = PackedStringArray() + + +## Resolved absolute config path for this client on the current OS. Exact-file +## overrides win first, followed by directory-valued `config_home_env`, then +## ordered candidates / `path_template`. Ignoring either override can write a +## file the client never reads and false-succeed. +func resolved_config_path() -> String: + return str(resolved_config_path_details().get("path", "")) + + +## Detailed sibling used by status/configure/remove so safe resolution +## failures reach the dock instead of collapsing into NOT_CONFIGURED. `error` +## is empty for ordinary unsupported/missing path mappings to preserve the +## long-standing status behavior for clients not installed on this platform. +func resolved_config_path_details() -> Dictionary: + var details := _resolve_config_path_details() + var path := str(details.get("path", "")) + if path.is_empty() or path.is_absolute_path(): + return details + ## Last gate before every strategy's read/write. `McpPathTemplate.expand` + ## leaves a token it cannot resolve in place, so an unset `$USERPROFILE` (or + ## a `~` with no HOME) reaches here as a RELATIVE path rather than as the + ## root-relative `/godot` that sails through `is_absolute_path()`. Acting on + ## it would resolve against the editor's own working directory and create a + ## literal `$USERPROFILE` folder in the Godot project. No descriptor + ## template is intentionally relative — every one is `~`- or `$VAR`-rooted — + ## so a non-absolute survivor is always a resolution failure. Report it with + ## the unexpanded path, which still shows what could not be resolved. + return {"path": "", "error": unresolved_config_path_error(display_name, path)} + + +## Shared wording for a path template `McpPathTemplate.expand` could not fully +## resolve. Used by the guard above and by the merge-tier loader in +## `_json_strategy.gd`, which resolves its own templates and never passes +## through `resolved_config_path_details`. +static func unresolved_config_path_error(client_name: String, path: String) -> String: + return ( + "Could not resolve %s's config path: %s did not expand to an absolute " + + "path. Set HOME/USERPROFILE (or the variable the path names) in the " + + "environment the editor was launched from." + ) % [client_name, path] + + +func _resolve_config_path_details() -> Dictionary: + ## Reflected reads: after an in-session self-update, an instance created + ## before the update can answer Nil for vars the update added, and the + ## typed calls below would each hard-error (Nil -> Dictionary, #850's + ## per-row error wall). Fail with the + ## one repair message instead; the registry's coherence probe drives the + ## same text on the status path. + var candidates: Variant = get("config_path_candidates") + var template: Variant = get("path_template") + var file_env: Variant = get("config_file_env") + if not (candidates is Dictionary) or not (template is Dictionary) or not (file_env is String): + return {"path": "", "error": McpClientRegistry.RESTART_TO_FINISH_UPDATE} + var file_override := config_file_override_details() + if not str(file_override.get("path", "")).is_empty() or not str(file_override.get("error", "")).is_empty(): + _clear_config_path_warning() + return file_override + var home_override := config_home_override_details() + if not str(home_override.get("path", "")).is_empty() or not str(home_override.get("error", "")).is_empty(): + _clear_config_path_warning() + return home_override + var candidate_key := McpPathTemplate.platform_key(candidates) + if not candidate_key.is_empty(): + return _resolve_ordered_config_path_candidates(candidates[candidate_key]) + _clear_config_path_warning() + return {"path": McpPathTemplate.resolve(template), "error": ""} + + +## The exact-file env override plus any fail-closed diagnostic. Empty path and +## error means no override applies (no mapping, unset, or blank env var). +func config_file_override_details() -> Dictionary: + if config_file_env.is_empty(): + return {"path": "", "error": ""} + ## env_lookup, not OS.get_environment: this can run on dock workers (#691). + var raw_path := McpPathTemplate.env_lookup(config_file_env).strip_edges() + if raw_path.is_empty(): + return {"path": "", "error": ""} + var expanded := McpPathTemplate.expand(raw_path) + if not expanded.is_absolute_path(): + return { + "path": "", + "error": "%s's $%s override must be an absolute config-file path; got %s" % [ + display_name, config_file_env, raw_path, + ], + } + if DirAccess.dir_exists_absolute(expanded): + return { + "path": "", + "error": "%s's $%s override must point to a config file, not a directory: %s" % [ + display_name, config_file_env, expanded, + ], + } + return {"path": expanded, "error": ""} + + +func _resolve_ordered_config_path_candidates(templates: Variant) -> Dictionary: + if not (templates is Array or templates is PackedStringArray): + _clear_config_path_warning() + return {"path": "", "error": ""} + var ordered_templates: Array = [] + for template_variant in templates: + ordered_templates.append(str(template_variant)) + var fallback_create_path := "" + for index in range(ordered_templates.size()): + var template := str(ordered_templates[index]) + var expanded_template := McpPathTemplate.expand(template) + # An empty wildcard group ordinarily means "this package is not + # installed", but an unresolved root token produces the same empty + # group. Do not silently treat "could not inspect" as "not present" and + # fall through to a later writable candidate. + if not expanded_template.is_absolute_path(): + _clear_config_path_warning() + return { + "path": "", + "error": unresolved_config_path_error(display_name, expanded_template), + } + var group := McpPathTemplate.expand_path_candidates(template) + if group.size() > 1: + var message := ( + "%s has multiple matching config package paths for %s: %s. " + + "Remove the stale package installation or edit the intended config manually." + ) % [display_name, template, ", ".join(group)] + _warn_config_path_once(message) + return {"path": "", "error": message} + if group.is_empty(): + continue + var path := String(group[0]) + if FileAccess.file_exists(path): + _clear_config_path_warning() + return {"path": path, "error": ""} + # A wildcard only resolves when its package directory exists. Treat that + # installation evidence as authoritative and create its private config + # directly instead of relying on copy-on-write read-through. Preserve + # anything currently visible through read-through by naming the first + # later existing candidate as a one-time seed source. + if template.contains("*"): + var seed := _first_existing_later_candidate(ordered_templates, index + 1) + if not str(seed.get("error", "")).is_empty(): + _clear_config_path_warning() + return {"path": "", "error": seed["error"]} + _clear_config_path_warning() + return {"path": path, "error": "", "seed_path": seed.get("path", "")} + if fallback_create_path.is_empty(): + fallback_create_path = path + _clear_config_path_warning() + return {"path": fallback_create_path, "error": ""} + + +## Find a readable seed for a newly-created authoritative wildcard target. +## An unresolved later root is an error, not an absent seed: writing without +## inspecting it could silently discard configuration visible through the +## package's read-through fallback. +func _first_existing_later_candidate(templates: Array, start_index: int) -> Dictionary: + for index in range(start_index, templates.size()): + var template := str(templates[index]) + var expanded_template := McpPathTemplate.expand(template) + if not expanded_template.is_absolute_path(): + return { + "path": "", + "error": unresolved_config_path_error(display_name, expanded_template), + } + var group := McpPathTemplate.expand_path_candidates(template) + # A seed is optional. Never choose among an ambiguous later wildcard; + # the authoritative target was already resolved by the earlier group. + if group.size() != 1: + continue + var path := String(group[0]) + if FileAccess.file_exists(path): + return {"path": path, "error": ""} + return {"path": "", "error": ""} + + +func _warn_config_path_once(message: String) -> void: + _config_path_warning_mutex.lock() + var should_warn := message != _last_config_path_warning + _last_config_path_warning = message + _config_path_warning_mutex.unlock() + if should_warn: + push_warning(message) + + +func _clear_config_path_warning() -> void: + _config_path_warning_mutex.lock() + _last_config_path_warning = "" + _config_path_warning_mutex.unlock() + + +## The config-home env override plus any fail-closed diagnostic. Empty path and +## error means no override applies (no mapping declared, env var unset, or env +## var empty/whitespace). +func config_home_override_details() -> Dictionary: + if config_home_env.is_empty() or config_home_env_subpath.is_empty(): + return {"path": "", "error": ""} + ## env_lookup, not OS.get_environment: this runs on dock worker threads, + ## which must not race the spawn window's setenv/unsetenv (#691). + var home := McpPathTemplate.env_lookup(config_home_env).strip_edges() + if home.is_empty(): + return {"path": "", "error": ""} + # Expand a leading ~ so `CODEX_HOME=~/codex-alt` behaves like the shell. + var expanded := McpPathTemplate.expand(home) + ## Same fail-closed rule as `config_file_override_details`: a relative value + ## resolves against the EDITOR's working directory, not the client's, so + ## honouring it silently aims the write at the Godot project directory + ## instead of the file the client reads. The write layer can only name the + ## mangled path it was handed; only here do we still know which env var + ## produced it, so this is where the user-facing explanation belongs. + if not expanded.is_absolute_path(): + return { + "path": "", + "error": "%s's $%s override must be an absolute config-home directory path; got %s" % [ + display_name, config_home_env, home, + ], + } + return {"path": expanded.path_join(config_home_env_subpath), "error": ""} + + +## The env-var-relocated config path, or "" when no override applies (no +## mapping declared, env var unset, env var empty/whitespace, or a value that +## failed closed — `config_home_override_details` carries that diagnostic). +func config_home_override() -> String: + return str(config_home_override_details().get("path", "")) + + +## True when a CLI client also declares where its config file lives, so it can +## fall back to writing that file directly when the CLI binary isn't on PATH. +## #463: Claude Code installed only as a VS Code / Cursor extension exposes no +## `claude` binary, but `claude mcp add --scope user` just writes `mcpServers` +## into ~/.claude.json — so we can produce the same entry ourselves. +func has_json_fallback() -> bool: + return config_type == "cli" and not path_template.is_empty() and not server_key_path.is_empty() + + +## True if the user appears to have this client installed locally. +func is_installed() -> bool: + if config_type == "cli": + if not McpCliFinder.find(_array_from_packed(cli_names)).is_empty(): + return true + # CLI not on PATH. A cli client with a JSON fallback (Claude Code as a + # VS Code/Cursor extension, #463) still counts as installed if its + # fallback config file already exists. + if has_json_fallback(): + var cfg := resolved_config_path() + return not cfg.is_empty() and FileAccess.file_exists(cfg) + return false + for p in detect_paths: + for resolved in McpPathTemplate.expand_path_candidates(p): + if FileAccess.file_exists(resolved) or DirAccess.dir_exists_absolute(resolved): + return true + # Fall back to "config file already exists" — usually means installed at some point. + var cfg := resolved_config_path() + return not cfg.is_empty() and FileAccess.file_exists(cfg) + + +static func _array_from_packed(packed: PackedStringArray) -> Array[String]: + var out: Array[String] = [] + for s in packed: + out.append(s) + return out + + +## Slice a PackedStringArray into a new PackedStringArray over [from, to). +## Used by `_toml_strategy` and `_manual_command` to peel the section path +## apart for `[a.b."c"]` header rendering. +static func _packed_slice(packed: PackedStringArray, from: int, to: int) -> PackedStringArray: + var out := PackedStringArray() + for i in range(from, to): + out.append(packed[i]) + return out diff --git a/addons/godot_ai/clients/_base.gd.uid b/addons/godot_ai/clients/_base.gd.uid new file mode 100644 index 0000000..5ea77d3 --- /dev/null +++ b/addons/godot_ai/clients/_base.gd.uid @@ -0,0 +1 @@ +uid://cyowqr1x12ilg diff --git a/addons/godot_ai/clients/_cli_exec.gd b/addons/godot_ai/clients/_cli_exec.gd new file mode 100644 index 0000000..995b91c --- /dev/null +++ b/addons/godot_ai/clients/_cli_exec.gd @@ -0,0 +1,176 @@ +@tool +class_name McpCliExec +extends RefCounted + +## Wall-clock-bounded CLI invocation. Every dock shell-out to a per-client +## CLI (`claude mcp list`, `claude mcp add ...`, etc.) goes through here so +## a hung subprocess can't trap the calling thread forever. +## +## Without the timeout, a contended `claude mcp list` has been observed to +## hang for 6+ minutes (issues #238, #239) — wedging the dock's status +## refresh worker, and on the Configure / Remove paths the editor main +## thread itself. +## +## Why poll/kill instead of `OS.execute(..., true)`: GDScript can't +## interrupt a blocking `OS.execute`, so a hung CLI takes its caller's +## thread with it. `OS.execute_with_pipe` returns immediately with a PID; +## we drive the wait ourselves and `OS.kill` the orphan if budget +## expires. CLI registry commands have bounded output (a few hundred +## bytes), so we don't bother draining the pipe during the poll loop — +## the kernel buffer absorbs it. +## +## Returns a Dictionary with: +## exit_code: process exit code (0 = success). -1 on timeout / spawn failure. +## stdout: captured stdout text. May be partial on timeout. +## stderr: captured stderr text. May be partial on timeout. Empty when +## `capture_stderr` is false. +## output: stdout + (newline + stderr if non-empty). Convenience for +## the common case of "show whatever the CLI said when it +## failed" — `claude mcp add` writes its real diagnostics to +## stderr, so callers that only read `stdout` would surface +## a generic "exit code 1" instead. +## timed_out: true if we killed the process at the wall-clock budget. +## cancelled: true if the caller requested a cooperative early stop. +## spawn_failed: true if `OS.execute_with_pipe` didn't return a usable PID. + +const DEFAULT_TIMEOUT_MS := 8000 +const _POLL_INTERVAL_MS := 50 +const _KILL_GRACE_MS := 500 + + +static func run( + exe: String, + args: Array, + timeout_ms: int = DEFAULT_TIMEOUT_MS, + capture_stderr: bool = true, + cancel_check: Callable = Callable(), +) -> Dictionary: + if exe.is_empty(): + return _spawn_failed_result() + return _run_piped(exe, args, timeout_ms, capture_stderr, cancel_check) + + +static func _run_piped( + exe: String, + args: Array, + timeout_ms: int, + capture_stderr: bool, + cancel_check: Callable, +) -> Dictionary: + + var spawn_exe := exe + var spawn_args := args + if OS.get_name() == "Windows": + var lower := exe.to_lower() + if lower.ends_with(".cmd") or lower.ends_with(".bat"): + ## CreateProcessW can't launch `.cmd` / `.bat` scripts on its + ## own — they're cmd.exe input, not PE binaries. Without this + ## wrap, the moment `McpCliFinder` resolves a Node-style shim + ## (npm's `claude.cmd`, pnpm's wrappers, …) the next + ## `OS.execute_with_pipe` surfaces "Could not create child + ## process: ..." in Godot's output log (#251). Passing + ## `exe` as a separate argv element keeps spaces in the path + ## quoted by Godot's standard quoter — no manual escaping. + spawn_exe = "cmd.exe" + spawn_args = ["/c", exe] + spawn_args.append_array(args) + + var info := OS.execute_with_pipe(spawn_exe, spawn_args) + if info.is_empty(): + return _spawn_failed_result() + + var pid: int = int(info.get("pid", -1)) + var stdio: Variant = info.get("stdio", null) + var stderr_pipe: Variant = info.get("stderr", null) + if pid <= 0: + _close_pipes(stdio, stderr_pipe) + return _spawn_failed_result() + + var deadline := Time.get_ticks_msec() + maxi(timeout_ms, _POLL_INTERVAL_MS) + while OS.is_process_running(pid): + var cancelled := cancel_check.is_valid() and bool(cancel_check.call()) + if cancelled or Time.get_ticks_msec() >= deadline: + ## Kill before draining: a pipe read can block while the child is + ## still alive. Once it exits, drain any buffered partial output. + OS.kill(pid) + var kill_deadline := Time.get_ticks_msec() + _KILL_GRACE_MS + while OS.is_process_running(pid) and Time.get_ticks_msec() < kill_deadline: + OS.delay_msec(_POLL_INTERVAL_MS) + + var partial_stdout := "" + var partial_stderr := "" + if not OS.is_process_running(pid): + partial_stdout = _drain_pipe(stdio) + partial_stderr = _drain_pipe(stderr_pipe) if capture_stderr else "" + _close_pipes(stdio, stderr_pipe) + return { + "exit_code": -1, + "stdout": partial_stdout, + "stderr": partial_stderr, + "output": _join_streams(partial_stdout, partial_stderr), + "timed_out": not cancelled, + "cancelled": cancelled, + "spawn_failed": false, + } + OS.delay_msec(_POLL_INTERVAL_MS) + + var stdout := _drain_pipe(stdio) + var stderr_text := _drain_pipe(stderr_pipe) if capture_stderr else "" + _close_pipes(stdio, stderr_pipe) + + return { + "exit_code": OS.get_process_exit_code(pid), + "stdout": stdout, + "stderr": stderr_text, + "output": _join_streams(stdout, stderr_text), + "timed_out": false, + "cancelled": false, + "spawn_failed": false, + } + + +static func _spawn_failed_result() -> Dictionary: + return { + "exit_code": -1, + "stdout": "", + "stderr": "", + "output": "", + "timed_out": false, + "cancelled": false, + "spawn_failed": true, + } + + +static func _drain_pipe(pipe: Variant) -> String: + if not (pipe is FileAccess): + return "" + var f := pipe as FileAccess + var bytes := PackedByteArray() + var max_bytes := 1 << 20 # 1 MiB, far above expected client CLI output. + while bytes.size() < max_bytes: + var chunk := f.get_buffer(mini(4096, max_bytes - bytes.size())) + if chunk.is_empty(): + break + bytes.append_array(chunk) + if f.eof_reached(): + break + return bytes.get_string_from_utf8() + + +static func _join_streams(stdout: String, stderr_text: String) -> String: + ## Most CLIs write their actionable diagnostics to one stream or the + ## other, never both — so concatenation gives "the message" without + ## the caller having to guess which key to read. Newline-separate so + ## callers that grep don't see two lines run together. + if stderr_text.is_empty(): + return stdout + if stdout.is_empty(): + return stderr_text + return "%s\n%s" % [stdout, stderr_text] + + +static func _close_pipes(stdio: Variant, stderr_pipe: Variant) -> void: + if stdio is FileAccess: + (stdio as FileAccess).close() + if stderr_pipe is FileAccess: + (stderr_pipe as FileAccess).close() diff --git a/addons/godot_ai/clients/_cli_exec.gd.uid b/addons/godot_ai/clients/_cli_exec.gd.uid new file mode 100644 index 0000000..4a97a2c --- /dev/null +++ b/addons/godot_ai/clients/_cli_exec.gd.uid @@ -0,0 +1 @@ +uid://dhoe3ypkhm12v diff --git a/addons/godot_ai/clients/_cli_finder.gd b/addons/godot_ai/clients/_cli_finder.gd new file mode 100644 index 0000000..394e76c --- /dev/null +++ b/addons/godot_ai/clients/_cli_finder.gd @@ -0,0 +1,181 @@ +@tool +class_name McpCliFinder +extends RefCounted + +## Generic three-tier CLI resolution for clients whose binary lives somewhere +## a GUI-launched Godot's minimal PATH won't see: +## 1. Well-known install locations (~/.local/bin, /opt/homebrew/bin, ...) +## 2. Login shell lookup (`bash -lc 'command -v '`) — picks up .zshrc / .bashrc +## 3. Plain `which` / `where` against the inherited PATH +## Caches per-exe so repeated dock refreshes don't fork a shell every frame. +## +## Thread safety: `find()` runs on action-worker threads +## (`_run_client_action_worker` in `mcp_dock.gd`), and `invalidate()` runs on +## the main thread (manual Refresh path). Godot `Dictionary` is not safe for +## concurrent mutation, so `_cache` / `_searched` access is guarded by +## `_mutex`. The mutex is held only across dictionary read/write — the slow +## `_resolve()` path (FileAccess + bounded subprocess lookup) runs unlocked, so a +## main-thread `invalidate()` can never block on a worker's subprocess. +## Two workers racing the same exe both call `_resolve()` and both write +## back the same answer; that's wasted work, not corruption. + + +static var _mutex: Mutex = Mutex.new() +static var _cache: Dictionary = {} # exe_name -> resolved path (or "") +static var _searched: Dictionary = {} + +const _LOOKUP_TIMEOUT_MS := 3000 + + +## Find any of the supplied exe names; returns the first hit. +## On Windows pass the .exe variant in `exe_names` if relevant. +static func find(exe_names: Array[String]) -> String: + for name in exe_names: + var hit := _find_one(name) + if not hit.is_empty(): + return hit + return "" + + +## Drop cache for one exe (call after the user installs / reinstalls). +static func invalidate(exe_name: String = "") -> void: + _mutex.lock() + if exe_name.is_empty(): + _cache.clear() + _searched.clear() + else: + _cache.erase(exe_name) + _searched.erase(exe_name) + _mutex.unlock() + + +static func _find_one(exe_name: String) -> String: + _mutex.lock() + var already_searched: bool = _searched.get(exe_name, false) + var cached: String = _cache.get(exe_name, "") + _mutex.unlock() + if already_searched: + return cached + # `_resolve()` does FileAccess + bounded subprocess lookup (forks + # `bash -lc` / `which`), which can take 100ms-1s. Holding the mutex across that + # would let a concurrent `invalidate()` on the main thread freeze the + # editor for the duration of the subprocess — which defeats the whole + # point of running CLI lookup off the main thread. + var hit := _resolve(exe_name) + _mutex.lock() + _cache[exe_name] = hit + _searched[exe_name] = true + _mutex.unlock() + return hit + + +static func _resolve(exe_name: String) -> String: + var is_windows := OS.get_name() == "Windows" + + # 1. Well-known locations + for dir in _well_known_dirs(): + var full := dir.path_join(exe_name) + if FileAccess.file_exists(full): + return full + + # 2. Login shell lookup (Unix only) + if not is_windows: + ## env_lookup, not OS.get_environment: CLI resolution runs on dock + ## worker threads (configure/remove actions) and must not race the + ## spawn window's setenv/unsetenv (#691). + var shell := McpPathTemplate.env_lookup("SHELL") + if shell.is_empty(): + shell = "/bin/bash" + var stripped := exe_name.trim_suffix(".exe") + var login_result := McpCliExec.run(shell, ["-lc", "command -v %s" % stripped], _LOOKUP_TIMEOUT_MS, false) + if int(login_result.get("exit_code", -1)) == 0: + var login_found: String = str(login_result.get("stdout", "")).strip_edges() + if not login_found.is_empty() and FileAccess.file_exists(login_found): + return login_found + + # 3. which / where with inherited PATH + var lookup := "where" if is_windows else "which" + var result := McpCliExec.run(lookup, [exe_name], _LOOKUP_TIMEOUT_MS, false) + if int(result.get("exit_code", -1)) == 0: + var output := str(result.get("stdout", "")) + var lines := PackedStringArray(output.split("\n")) + var found := _pick_best_path(lines) if is_windows else lines[0].strip_edges() + if not found.is_empty(): + return found + return "" + + +## Executable extensions Windows' CreateProcessW can launch from a path +## (after the cmd.exe wrap in `_cli_exec.gd`). Order is preference: `.exe` +## is a native PE binary; `.cmd` / `.bat` go through the shell; `.com` is +## the legacy COM-format executable that some shims still ship. +const _WINDOWS_EXEC_EXTS := [".exe", ".cmd", ".bat", ".com"] + + +## Pick the best path from `where` output on Windows. +## +## npm-installed Node CLIs ship as BOTH `/` (a POSIX bash shim +## for WSL / Git Bash users) AND `/.cmd` (the actual Windows +## wrapper). `where ` lists both. CreateProcessW — the underlying +## syscall behind `OS.execute_with_pipe` — refuses to launch the +## extensionless POSIX shim, surfacing as +## `ERROR: Could not create child process: "...\claude" mcp list` +## in Godot's output log (#251). Picking a path with a real executable +## extension dodges that entirely. +## +## Extension scan is the OUTER loop so the order in `_WINDOWS_EXEC_EXTS` +## drives preference — `.exe` wins over `.cmd` even when the `.cmd` shows +## up first in `where` output (one fewer process per shell-out). Falls +## back to the first non-empty line when no entry has a recognised +## extension, so we never come up empty when `where` returned *something*. +static func _pick_best_path(lines: PackedStringArray) -> String: + var stripped := PackedStringArray() + for raw in lines: + var line := raw.strip_edges() + if not line.is_empty(): + stripped.append(line) + if stripped.is_empty(): + return "" + for ext in _WINDOWS_EXEC_EXTS: + for candidate in stripped: + if candidate.to_lower().ends_with(ext): + return candidate + return stripped[0] + + +static func _well_known_dirs() -> Array[String]: + ## env_lookup, not OS.get_environment — see _resolve()'s worker-thread + ## note (#691). + var home := McpPathTemplate.env_lookup("HOME") + if home.is_empty(): + home = McpPathTemplate.env_lookup("USERPROFILE") + match OS.get_name(): + "macOS": + return [ + home.path_join(".local/bin"), + home.path_join(".claude/local"), + home.path_join(".cargo/bin"), + "/opt/homebrew/bin", + "/usr/local/bin", + ] + "Windows": + var local := McpPathTemplate.env_lookup("LOCALAPPDATA") + var prog := McpPathTemplate.env_lookup("ProgramFiles") + var paths: Array[String] = [] + if not home.is_empty(): + paths.append(home.path_join(".claude/local")) + paths.append(home.path_join(".local/bin")) + paths.append(home.path_join(".cargo/bin")) + paths.append(home.path_join("AppData/Local/Programs/uv")) + if not local.is_empty(): + paths.append(local.path_join("Programs/uv")) + if not prog.is_empty(): + paths.append(prog.path_join("uv")) + return paths + _: + return [ + home.path_join(".local/bin"), + home.path_join(".claude/local"), + home.path_join(".cargo/bin"), + "/usr/local/bin", + ] diff --git a/addons/godot_ai/clients/_cli_finder.gd.uid b/addons/godot_ai/clients/_cli_finder.gd.uid new file mode 100644 index 0000000..9985270 --- /dev/null +++ b/addons/godot_ai/clients/_cli_finder.gd.uid @@ -0,0 +1 @@ +uid://cnp5b6fcwou2y diff --git a/addons/godot_ai/clients/_cli_strategy.gd b/addons/godot_ai/clients/_cli_strategy.gd new file mode 100644 index 0000000..0714115 --- /dev/null +++ b/addons/godot_ai/clients/_cli_strategy.gd @@ -0,0 +1,372 @@ +@tool +class_name McpCliStrategy +extends RefCounted + +## Strategy for MCP clients that own their own state via a CLI (e.g. +## `claude mcp add`). Reads `cli_register_template` / `cli_unregister_template` +## / `cli_status_args` from the descriptor and substitutes `{name}` / `{url}` +## tokens. Command-shape descriptors additionally use the whole-element launch +## tokens `{command}` / `{args...}` (see `format_args`). No descriptor-supplied +## Callables — see `_base.gd` for why. +## +## Every shell-out goes through `McpCliExec.run`, which wraps the call in a +## wall-clock timeout. A hung CLI (e.g. `claude mcp list` under +## inter-Claude-Code contention) gets killed at the budget instead of +## locking up the caller forever — see issues #238 / #239. + +## The descriptor token resolved from `godot_ai/mcp_client_scope` (#872). +## Only Claude Code takes it today; any `config_type = "cli"` descriptor can. +const SCOPE_TOKEN := "{scope}" + +const _CONFIGURE_TIMEOUT_MS := 10000 +const _REMOVE_TIMEOUT_MS := 10000 +const _STATUS_TIMEOUT_MS := 6000 + + +static func configure( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> Dictionary: + ## Fail closed before any subprocess runs: a command-shape client without a + ## verified attach launcher must not register anything (see + ## docs/client-configuration.md — an ERROR beats an entry known to be broken). + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": "error", "message": launch_error} + var cli := _resolve_cli(client) + if cli.is_empty(): + return {"status": "error", "message": "%s not found" % client.display_name} + + # Best-effort prior cleanup so re-configure is idempotent. Bounded to + # the same budget — a hung unregister shouldn't block the configure + # that follows. + if not client.cli_unregister_template.is_empty(): + ## #872: a `{scope}` descriptor sweeps EVERY scope, not just the + ## selected one. Flipping the setting user -> project and pressing + ## Configure would otherwise leave the old user-scope entry alive — + ## exactly the "loaded in every unrelated workspace" problem the + ## setting exists to fix. `mcp remove` on an absent entry is a no-op + ## and the result is discarded either way, so the extra passes are + ## safe; they cost one bounded subprocess per additional scope. + for pre_scope in _cleanup_scopes(client): + var pre_args := _format_args( + client.cli_unregister_template, server_name, server_url, {}, pre_scope + ) + McpCliExec.run(cli, pre_args, _REMOVE_TIMEOUT_MS) + + if client.cli_register_template.is_empty(): + return {"status": "error", "message": "%s descriptor missing cli_register_template" % client.display_name} + var args := _format_args(client.cli_register_template, server_name, server_url, launch) + var result := McpCliExec.run(cli, args, _CONFIGURE_TIMEOUT_MS) + if result.get("timed_out", false): + return { + "status": "error", + "message": "Configure %s timed out after %ds — see 'Run this manually' below to retry by hand" % [ + client.display_name, _CONFIGURE_TIMEOUT_MS / 1000, + ], + } + if result.get("spawn_failed", false): + return {"status": "error", "message": "Failed to spawn %s" % client.display_name} + if int(result.get("exit_code", -1)) == 0: + return {"status": "ok", "message": McpClient.configured_message(client, server_url)} + ## `claude mcp add` writes its real failure diagnostics to stderr, so + ## prefer `output` (stdout + stderr) over `stdout` alone — otherwise + ## the user sees "exit code 1" instead of the actual error. + var combined := str(result.get("output", "")).strip_edges() + var err := combined if not combined.is_empty() else "exit code %d" % int(result.get("exit_code", -1)) + return {"status": "error", "message": "Failed to configure %s: %s" % [client.display_name, err]} + + +## Run the descriptor's `cli_status_args`, scan stdout for `server_name` and +## the expected target. The matching rule is the only sensible one for "list +## MCP entries" output across CLI clients we currently support: name AND +## target present → CONFIGURED; name only → MISMATCH; neither → +## NOT_CONFIGURED. For URL descriptors the target is `server_url`; for +## command-shape descriptors it is the resolved attach launcher path (the +## listing prints the registered command line, not a URL). Command-shape CLI +## clients with a JSON fallback file get exact drift detection via the JSON +## strategy instead — the configurator prefers that path and only lands here +## for CLI clients whose state isn't file-readable. +static func check_status( + client: McpClient, server_name: String, server_url: String, launch: Dictionary = {} +) -> McpClient.Status: + return check_status_with_cli_path(client, server_name, server_url, _resolve_cli(client), launch) + + +static func check_status_with_cli_path( + client: McpClient, server_name: String, server_url: String, cli: String, launch: Dictionary = {} +) -> McpClient.Status: + return check_status_details(client, server_name, server_url, cli, launch).get("status", McpClient.Status.NOT_CONFIGURED) + + +## Detailed variant used by the dock's refresh worker so it can surface a +## "probe timed out" badge on the affected row instead of silently +## conflating the timeout with NOT_CONFIGURED. Returns +## `{"status": Status, "error_msg": String}`. The caller plumbs +## `error_msg` straight into `_apply_row_status`. +static func check_status_details( + client: McpClient, server_name: String, server_url: String, cli: String, launch: Dictionary = {} +) -> Dictionary: + if cli.is_empty(): + return _status_details(McpClient.Status.NOT_CONFIGURED) + if client.cli_status_args.is_empty(): + return _status_details(McpClient.Status.NOT_CONFIGURED) + var expected_target := server_url + if client.command_shape != McpClient.CommandShape.NONE: + ## Same fail-closed contract as configure: without a verified launcher + ## there is no target to compare against, and guessing would report a + ## broken entry as green. + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return _status_details(McpClient.Status.ERROR, launch_error) + expected_target = str(launch.get("command", "")) + var result := McpCliExec.run( + cli, + McpClient._array_from_packed(client.cli_status_args), + _STATUS_TIMEOUT_MS, + false + ) + if result.get("timed_out", false): + return _status_details(McpClient.Status.ERROR, "probe timed out") + if result.get("spawn_failed", false): + return _status_details(McpClient.Status.NOT_CONFIGURED) + if int(result.get("exit_code", -1)) != 0: + return _status_details(McpClient.Status.NOT_CONFIGURED) + var text := str(result.get("stdout", "")) + if text.find(server_name) < 0: + return _status_details(McpClient.Status.NOT_CONFIGURED) + ## Server registered, but pointing somewhere else — drift after a + ## port change. Surface as mismatch so the dock offers Reconfigure. + if text.find(expected_target) < 0: + return _status_details(McpClient.Status.CONFIGURED_MISMATCH) + return _status_details(McpClient.Status.CONFIGURED) + + +## Empty string when this client's launch requirements are satisfied. A +## command-shape descriptor requires a successfully resolved attach launch; +## URL descriptors (`CommandShape.NONE`) never require one. Mirrors +## `McpJsonStrategy.command_launch_error` / the TOML equivalent. +static func command_launch_error(client: McpClient, launch: Dictionary) -> String: + if client.command_shape == McpClient.CommandShape.NONE: + return "" + if not bool(launch.get("ok", false)): + return str(launch.get("error", "No compatible attach launcher was found.")) + return "" + + +static func _status_details(status: McpClient.Status, error_msg: String = "") -> Dictionary: + return {"status": status, "error_msg": error_msg} + + +static func remove(client: McpClient, server_name: String) -> Dictionary: + var cli := _resolve_cli(client) + if cli.is_empty(): + return {"status": "error", "message": "%s not found" % client.display_name} + if client.cli_unregister_template.is_empty(): + return {"status": "error", "message": "%s descriptor missing cli_unregister_template" % client.display_name} + var args := _format_args(client.cli_unregister_template, server_name, "") + var result := McpCliExec.run(cli, args, _REMOVE_TIMEOUT_MS) + if result.get("timed_out", false): + return { + "status": "error", + "message": "Remove %s timed out after %ds — see 'Run this manually' below to retry by hand" % [ + client.display_name, _REMOVE_TIMEOUT_MS / 1000, + ], + } + if result.get("spawn_failed", false): + return {"status": "error", "message": "Failed to spawn %s" % client.display_name} + if int(result.get("exit_code", -1)) == 0: + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + ## `claude mcp add` writes its real failure diagnostics to stderr, so + ## prefer `output` (stdout + stderr) over `stdout` alone — otherwise + ## the user sees "exit code 1" instead of the actual error. + var combined := str(result.get("output", "")).strip_edges() + var err := combined if not combined.is_empty() else "exit code %d" % int(result.get("exit_code", -1)) + return {"status": "error", "message": "Failed to remove %s: %s" % [client.display_name, err]} + + +## Substitute `{name}` and `{url}` tokens in every template entry. +## Tokens match verbatim — `{name_suffix}` is NOT touched, so callers don't +## have to worry about partial-token collisions in their argv. +## +## Launch tokens are whole-element only: an element that is exactly +## `{command}` becomes the resolved attach launcher path, and an element that +## is exactly `{args...}` is spliced into the argv as one element per launch +## arg. Whole-element matching keeps a literal brace inside a path or flag +## from ever triggering an expansion. +## +## `scope_override` forces a specific `{scope}` value instead of the live +## setting; the configure pre-cleanup uses it to sweep the scopes the user is +## NOT currently on. Empty means "resolve from the setting". +static func format_args( + template: PackedStringArray, + server_name: String, + server_url: String, + launch: Dictionary = {}, + scope_override: String = "", +) -> Array[String]: + return _format_args(template, server_name, server_url, launch, scope_override) + + +static func _format_args( + template: PackedStringArray, + server_name: String, + server_url: String, + launch: Dictionary = {}, + scope_override: String = "", +) -> Array[String]: + var scope := scope_override if not scope_override.is_empty() else McpSettings.client_scope() + var out: Array[String] = [] + for arg in template: + var s := String(arg) + if s == "{command}": + out.append(str(launch.get("command", ""))) + continue + if s == "{args...}": + for launch_arg in launch.get("args", []): + out.append(str(launch_arg)) + continue + s = s.replace("{name}", server_name) + s = s.replace("{url}", server_url) + ## Resolved per-call rather than baked into the descriptor so the + ## setting can change without an editor restart, and so the manual + ## command shown in the dock always matches what Configure would run. + s = s.replace(SCOPE_TOKEN, scope) + out.append(s) + return out + + +## Scope-aware status for descriptors that declare `cli_scope_status_template`. +## Returns the same `{"status", "error_msg"}` shape as check_status_details. +## +## Split from the subprocess call so the verdict is a pure function of what the +## CLI printed — `_scope_probe_verdict` is unit-tested against real recorded +## `claude mcp get` output rather than needing a `claude` binary on the runner. +static func check_scope_status_details( + client: McpClient, + server_name: String, + server_url: String, + cli: String, + launch: Dictionary, + expected_scope: String, +) -> Dictionary: + if cli.is_empty() or client.cli_scope_status_template.is_empty(): + return _status_details(McpClient.Status.NOT_CONFIGURED) + var expected_target := server_url + if client.command_shape != McpClient.CommandShape.NONE: + ## Same fail-closed contract as configure and the plain status probe. + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return _status_details(McpClient.Status.ERROR, launch_error) + expected_target = str(launch.get("command", "")) + var args := _format_args(client.cli_scope_status_template, server_name, server_url) + var result := McpCliExec.run(cli, args, _STATUS_TIMEOUT_MS, false) + if result.get("timed_out", false): + return _status_details(McpClient.Status.ERROR, "probe timed out") + if result.get("spawn_failed", false): + return _status_details(McpClient.Status.NOT_CONFIGURED) + return _scope_probe_verdict( + int(result.get("exit_code", -1)), + str(result.get("stdout", "")), + expected_scope, + expected_target, + ) + + +## The `Scope:` label the probe printed, normalised to a CLIENT_SCOPES value, +## or "" when no line was recognisable. Matched on the first word after the +## label so the parenthetical blurb ("(shared via .mcp.json)") can change +## wording between CLI releases without breaking detection. +static func _scope_from_probe_output(text: String) -> String: + for raw_line in text.split("\n"): + var line := String(raw_line).strip_edges() + var marker := line.find("Scope:") + if marker < 0: + continue + var rest := line.substr(marker + 6).strip_edges().to_lower() + for scope in McpSettings.CLIENT_SCOPES: + var name := String(scope) + if rest.begins_with(name): + return name + return "" + + +## Pure verdict for a scope probe. A non-zero exit is the CLI's "no such +## server" signal. An entry resolved from a scope other than the selected one +## is MISMATCH, not CONFIGURED: the dock offers Reconfigure, and Configure's +## all-scope pre-cleanup is what actually moves it. +## +## A missing or unrecognised `Scope:` line degrades to the target check alone, +## deliberately rather than failing closed. `_verify_post_state` turns any +## non-CONFIGURED status after a successful write into an error, so treating an +## unparsed label as MISMATCH would mean a future CLI release that reworded or +## dropped that line breaks Configure outright — a false error plus a +## permanently amber row whose Reconfigure button cannot clear it. The entry +## has already been matched by name and exact launcher path at that point; the +## only thing in doubt is which scope it came from, and a slightly optimistic +## dot is a much cheaper failure than a configure flow that reports success as +## failure. Today's claude (2.1.241) always prints the line, so this is a +## forward-compatibility hedge, not a live code path. +static func _scope_probe_verdict( + exit_code: int, text: String, expected_scope: String, expected_target: String +) -> Dictionary: + if exit_code != 0: + return _status_details(McpClient.Status.NOT_CONFIGURED) + ## `resolved_scope` rides along as structured data so callers can act on it + ## — `_verify_post_state`'s path hint needs to know WHICH scope survived to + ## name the right file, and parsing it back out of the human-facing message + ## would couple that hint to this wording (#879). Parsed BEFORE the target + ## check so both mismatch paths carry it: an entry whose launcher drifted + ## sends the user to the wrong file just as readily as one whose scope did. + var resolved := _scope_from_probe_output(text) + if not expected_target.is_empty() and text.find(expected_target) < 0: + var drifted := _status_details(McpClient.Status.CONFIGURED_MISMATCH) + if not resolved.is_empty(): + drifted["resolved_scope"] = resolved + return drifted + if resolved.is_empty(): + return _status_details(McpClient.Status.CONFIGURED) + if resolved != expected_scope: + var details := _status_details( + McpClient.Status.CONFIGURED_MISMATCH, + "registered at %s scope, not %s" % [resolved, expected_scope], + ) + details["resolved_scope"] = resolved + return details + return _status_details(McpClient.Status.CONFIGURED) + + +## True when the descriptor's register template takes `{scope}`, i.e. where +## its entry lands is decided by the `godot_ai/mcp_client_scope` setting rather +## than fixed by the descriptor. The configurator uses this to decide whether +## the JSON-fallback file is still a valid place to read status back from. +static func uses_scope_token(client: McpClient) -> bool: + return client.cli_register_template.has(SCOPE_TOKEN) + + +## Public view of the pre-cleanup sweep, for the manual-command text: what the +## dock tells the user to run has to match what Configure actually runs (#877). +static func cleanup_scopes(client: McpClient) -> Array[String]: + return _cleanup_scopes(client) + + +## Scopes the configure pre-cleanup removes from. A descriptor without the +## `{scope}` token has exactly one place its entry can live, so it keeps the +## single pass it always had — "" means "resolve the scope normally". +static func _cleanup_scopes(client: McpClient) -> Array[String]: + if not uses_scope_token(client): + return [""] + var scopes: Array[String] = [] + for scope in McpSettings.CLIENT_SCOPES: + scopes.append(String(scope)) + return scopes + + +static func _resolve_cli(client: McpClient) -> String: + return McpCliFinder.find(McpClient._array_from_packed(client.cli_names)) + + +static func resolve_cli_path(client: McpClient) -> String: + return _resolve_cli(client) diff --git a/addons/godot_ai/clients/_cli_strategy.gd.uid b/addons/godot_ai/clients/_cli_strategy.gd.uid new file mode 100644 index 0000000..f84a92b --- /dev/null +++ b/addons/godot_ai/clients/_cli_strategy.gd.uid @@ -0,0 +1 @@ +uid://bvib7d8eabbcm diff --git a/addons/godot_ai/clients/_dsh_strategy.gd b/addons/godot_ai/clients/_dsh_strategy.gd new file mode 100644 index 0000000..e18385c --- /dev/null +++ b/addons/godot_ai/clients/_dsh_strategy.gd @@ -0,0 +1,759 @@ +@tool +class_name McpDshStrategy +extends RefCounted + +## Configure / status / remove for DeepSeek Harness (dsh) MCP servers. +## +## DeepSeek Harness has no `mcp` CLI verb (verified against dsh +## 0.1.0-rc.6 — `dsh --help` exposes only `web` and `plugin`). MCP servers +## register as `@deepseek-ai/dsh-mcp-client` plugin entries in the HOME patch +## layer `$DSH_HOME/cordis.patch.yml` — the machine-local layer dsh applies +## over EVERY profile's own patch layer (the web GUI included), so one entry +## covers every profile the user boots. +## +## The patch file is a top-level YAML array of loader patch entries +## (`@deepseek-ai/cordis-plugin-include`'s `applyEntryPatches`). A non-insert +## row only OVERRIDES an existing bundle row (a new id is skipped with a +## warning), so a brand-new server must be added with an `insert` row: +## +## - insert: +## - id: mcp-godot-ai +## name: '@deepseek-ai/dsh-mcp-client' +## config: +## serverName: godot-ai +## transport: stdio +## command: "..." +## args: [...] +## +## Both shapes verified live against the dsh loader +## (`dsh --profile web --dump-config` composes the inserted entry; a plain +## row for a new id warns "patch: entry not found" and is skipped). We write +## one dedicated insert row per server, preserve every other row byte-for-byte +## (including other users' insert rows, overrides, comments, and `!!js` +## expressions), and status-verify the entry we wrote — the same file-read +## drift contract the JSON/TOML/YAML strategies use. +## +## The entry's `config` nests the launch under `serverName`/`transport`/ +## `command`/`args`; `serverName` is the model-facing tool namespace +## (`mcp__godot-ai__`), so it carries the server name like the +## `server_key_path` map key does for the other strategies. + +## Loader entry id prefix inside the patch list. The full id is +## `` — "mcp-godot-ai" for the godot-ai server. +const ENTRY_ID_PREFIX := "mcp-" +## The loader plugin that bridges MCP servers into the harness. Must be +## installed in the profile's node_modules (dsh ships it as a dependency of +## the CLI package). Quoted in the file: `@` is a reserved YAML indicator and +## cannot start a plain scalar. +const PLUGIN_NAME := "@deepseek-ai/dsh-mcp-client" +## Indent of a nested entry header under `- insert:` (children step 2 spaces +## deeper), matching the shipped profile patch files. +const ENTRY_INDENT := 4 + + +static func entry_id(server_name: String) -> String: + return ENTRY_ID_PREFIX + server_name + + +static func configure( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty(): + return {"status": "error", "message": "Could not resolve config path for %s on this OS" % client.display_name} + ## Fail closed before touching the file — same contract as JSON/TOML/YAML. + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": "error", "message": launch_error} + + var read := _read(path) + if not read["ok"]: + return {"status": "error", "message": "Refusing to overwrite %s: %s. Fix or move the file, then re-run Configure." % [path, read["error"]]} + ## Fail closed on content that is not a loader patch list: dsh's patch + ## parser rejects a non-array file at boot, so appending our row to a + ## top-level mapping would hand the user a broken file (#867 review). + ## `[]` is a valid empty sequence meaning "no rows"; the literal must not + ## survive an append (block rows after `[]` are malformed YAML), so only + ## that line is dropped — comments around it belong to the user and stay. + var text := String(read["data"]) + text = _strip_empty_flow_sequence(text) + if not _is_patch_sequence(text): + return { + "status": "error", + "message": "Refusing to overwrite %s: it is not a top-level YAML list of loader entries. Fix or remove the file, then re-run Configure." % path, + } + + var existing_config: Variant = null + var lines := _split_lines(text) + var found := _find_entry_block(lines, entry_id(server_name), true) + if found.is_empty(): + var plain := _find_entry_block(lines, entry_id(server_name), false) + if not plain.is_empty(): + ## A plain `- id: mcp-godot-ai` row is inert for a new id — the + ## loader skips it with a warning and never registers the server. + ## Replacing the whole row with the insert form migrates it. + found = plain + if not found.is_empty(): + ## Pass the parsed config through so user-mutable fields (env, + ## toolCallTimeoutMs, reconnect) survive a reconfigure. + existing_config = _extract_config(lines, found) + var new_entry := build_entry(client, server_name, server_url, existing_config, launch) + ## Nested replacement must keep the sequence's existing header indent — + ## items of one block sequence share indentation, so a hand-written + ## 2-space file re-emitted at 4 spaces would no longer parse (#867 + ## review). Fresh rows and plain-row migrations keep the 4-space style. + var base_indent := ENTRY_INDENT + if not found.is_empty(): + var header_indent := int(found.get("indent", 0)) + if header_indent > 0: + base_indent = header_indent + var rendered := render_nested_entry(entry_id(server_name), new_entry, base_indent) + var out := "" + if found.is_empty(): + out = _append_row(lines, rendered) + else: + out = _replace_lines(lines, found, rendered) + if not McpAtomicWrite.write(path, out): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": McpClient.configured_message(client, server_url)} + + +static func check_status( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> McpClient.Status: + return check_status_details(client, server_name, server_url, launch)["status"] + + +## Same contract as the other strategies (#711): {status, error_msg}. An +## existing-but-unreadable config is ERROR with the diagnostic — not +## NOT_CONFIGURED — so the dock row can tell "no config" from "config the +## editor can't read" instead of offering a Configure that would fail. +static func check_status_details( + client: McpClient, server_name: String, server_url: String, launch: Dictionary = {} +) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": McpClient.Status.ERROR, "error_msg": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + var read := _read(path) + if not read["ok"]: + return { + "status": McpClient.Status.ERROR, + "error_msg": "Cannot read %s: %s" % [path, read["error"]], + } + var text := String(read["data"]) + if not _is_patch_sequence(text): + ## A top-level mapping/scalar is not a dsh patch list: nothing in it + ## can be "configured", and a nested `- id:` inside a mapping must + ## not read as ours (#867 review). + return { + "status": McpClient.Status.ERROR, + "error_msg": "%s is not a top-level YAML list of loader entries; fix or remove the file." % path, + } + var lines := _split_lines(text) + var found := _find_entry_block(lines, entry_id(server_name), true) + if found.is_empty(): + ## A plain row for our id is inert (the loader skips unknown ids), so + ## the server is NOT registered no matter what the file says. It only + ## becomes registered once Configure rewrites it as an insert row. + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + var config := _extract_config(lines, found) + if config.is_empty(): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + ## An entry exists but no verified launcher does — mirror the other + ## strategies: this is an environment ERROR, not entry drift. + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": McpClient.Status.ERROR, "error_msg": launch_error} + if verify_entry(client, config, server_name, server_url, launch): + return {"status": McpClient.Status.CONFIGURED, "error_msg": ""} + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + + +static func remove(client: McpClient, server_name: String) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": "ok", "message": "Not configured"} + var read := _read(path) + if not read["ok"]: + return {"status": "error", "message": "Refusing to rewrite %s: %s." % [path, read["error"]]} + var text := String(read["data"]) + if not _is_patch_sequence(text): + ## Same fail-closed contract as configure (#867 review): never modify + ## a file that dsh cannot load as a patch list. + return { + "status": "error", + "message": "Refusing to rewrite %s: it is not a top-level YAML list of loader entries. Fix or remove the file, then re-run Remove." % path, + } + var lines := _split_lines(text) + var found := _find_entry_block(lines, entry_id(server_name), true) + if found.is_empty(): + found = _find_entry_block(lines, entry_id(server_name), false) + if found.is_empty(): + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + var out := _remove_lines(lines, found) + if _is_blank_or_comment_only(out): + ## dsh's patch parser requires a top-level YAML array: an empty or + ## comment-only patch file FAILS BOOT (`loadOptionalPatches` throws on + ## a non-array file), while an absent file means "no layer". After our + ## row is gone, an all-blank file must therefore be deleted, not + ## written back. + if FileAccess.file_exists(path): + var remove_err := DirAccess.remove_absolute(path) + if remove_err != OK: + return {"status": "error", "message": "Cannot remove %s (error %d)" % [path, remove_err]} + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + if not McpAtomicWrite.write(path, out): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + + +## Build the `config` dict written inside the loader entry. Command mode +## (FLAT, #838) nests `serverName`/`transport`/`command`/`args`; URL mode nests +## `serverName`/`transport`/`url`. Existing user state (env, timeouts, +## reconnect) survives a reconfigure via the deep copy. +static func build_entry( + client: McpClient, + server_name: String, + server_url: String, + existing: Variant = null, + launch: Dictionary = {}, +) -> Dictionary: + var entry: Dictionary = (existing as Dictionary).duplicate(true) if existing is Dictionary else {} + entry["serverName"] = server_name + if client.command_shape == McpClient.CommandShape.FLAT: + entry["command"] = str(launch.get("command", "")) + entry["args"] = _array_copy(launch.get("args", [])) + if not client.command_transport_key.is_empty(): + entry[client.command_transport_key] = client.command_transport_value + for key in client.command_initial_fields: + if not entry.has(key): + entry[key] = client.command_initial_fields[key] + for key in client.command_legacy_keys: + entry.erase(String(key)) + return entry + if client.command_shape == McpClient.CommandShape.NONE: + ## Single URL-mode source of truth (#867 review): build_entry's URL + ## branch delegates to build_url_entry so the two can never drift. + return build_url_entry(client, server_name, server_url, existing) + return {} + + +## URL-mode sibling for the manual-instruction fallback text and the +## build_entry URL branch. DeepSeek Harness' mcp-client bridge accepts +## `transport: streamable-http` with a `url`, so the entry keeps the same +## `serverName` namespace with an HTTP transport instead of the stdio attach +## bridge. Existing user state survives via the deep copy. +static func build_url_entry( + client: McpClient, server_name: String, server_url: String, existing: Variant = null +) -> Dictionary: + var entry: Dictionary = (existing as Dictionary).duplicate(true) if existing is Dictionary else {} + entry["serverName"] = server_name + entry["transport"] = "streamable-http" + if not client.entry_url_field.is_empty(): + entry[client.entry_url_field] = server_url + return entry + + +## Verify a stored `config` dict matches the current launch. Command mode +## checks every launch-affecting value exactly and requires legacy URL keys +## gone; serverName must match the pinned namespace. URL mode checks the url +## and the streamable-http pin. +static func verify_entry( + client: McpClient, + config: Dictionary, + server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> bool: + if config.get("serverName") != server_name: + return false + if client.command_shape != McpClient.CommandShape.NONE: + if client.command_shape != McpClient.CommandShape.FLAT or not bool(launch.get("ok", false)): + return false + for key in client.command_legacy_keys: + if config.has(String(key)): + return false + if config.get("command") != launch.get("command"): + return false + if not _arrays_equal(config.get("args", null), launch.get("args", null)): + return false + if not client.command_transport_key.is_empty(): + if config.get(client.command_transport_key, null) != client.command_transport_value: + return false + return true + if config.get(client.entry_url_field, "") != server_url: + return false + return config.get("transport", "") == "streamable-http" + + +## Empty string when this client's launch requirements are satisfied. +## Mirrors `McpYamlStrategy.command_launch_error`; the patch-list dialect +## supports FLAT (and the URL fallback) only. +static func command_launch_error(client: McpClient, launch: Dictionary) -> String: + if client.command_shape == McpClient.CommandShape.NONE: + return "" + if client.command_shape != McpClient.CommandShape.FLAT: + return "%s uses a command shape not supported by DeepSeek Harness config yet" % client.display_name + if not bool(launch.get("ok", false)): + return str(launch.get("error", "No compatible attach launcher was found.")) + return "" + + +# --- Rendering -------------------------------------------------------------- + +## Render a full `- insert:` row containing one nested loader entry. Public +## seam for the dock's manual-instruction text so the pasted YAML matches +## what Configure would write byte-for-byte. +static func render_insert_row(entry_id_value: String, config: Dictionary) -> PackedStringArray: + var lines: PackedStringArray = ["- insert:"] + lines.append_array(render_nested_entry(entry_id_value, config)) + return lines + + +## Render one nested loader entry (the `- id:` block inside an `insert` +## list). `base_indent` defaults to the 4-space style used by the shipped +## patch files; a nested replacement reuses the indent the existing entry was +## found at so the block sequence keeps a single indentation (#867 review). +static func render_nested_entry( + entry_id_value: String, config: Dictionary, base_indent: int = ENTRY_INDENT +) -> PackedStringArray: + var lines: PackedStringArray = [] + lines.append("%s- id: %s" % [_indent_str(base_indent), entry_id_value]) + lines.append("%sname: '%s'" % [_indent_str(base_indent + 2), PLUGIN_NAME]) + lines.append("%sconfig:" % _indent_str(base_indent + 2)) + for key in config: + lines.append_array(_emit_field(String(key), config[key], base_indent + 4)) + return lines + + +## Emit one `key: value` line (or a nested block for Dictionary values) at +## the given indent. Arrays render in flow style; scalars through the shared +## YAML emitter so quoting rules stay identical across the two YAML dialects. +static func _emit_field(key: String, value: Variant, indent: int) -> PackedStringArray: + var lines: PackedStringArray = [] + var prefix := _indent_str(indent) + if value is Dictionary: + lines.append("%s%s:" % [prefix, key]) + for sub_key in value: + lines.append_array(_emit_field(String(sub_key), value[sub_key], indent + 2)) + elif value is Array or value is PackedStringArray: + lines.append("%s%s: %s" % [prefix, key, McpYamlStrategy.emit_flow_array(_array_copy(value))]) + else: + lines.append("%s%s: %s" % [prefix, key, McpYamlStrategy.emit_scalar(value)]) + return lines + + +# --- Line-level parsing (no YAML parser in Godot) --------------------------- + +## Split file text into lines, dropping only a single trailing newline so the +## remainder round-trips byte-for-byte. `text` is never split on the empty +## string, so an empty file yields an empty array. +static func _split_lines(text: String) -> PackedStringArray: + if text.is_empty(): + return PackedStringArray() + var lines := text.split("\n") + if lines.size() > 0 and String(lines[lines.size() - 1]).is_empty(): + lines.remove_at(lines.size() - 1) + return lines + + +## Locate the block owned by our loader entry: +## require_nested=true — the `- id: ` line inside an `insert` +## list (indent > 0), plus its indented children. +## require_nested=false — a plain top-level `- id: ` row (indent +## 0), plus its indented children. +## Returns {"start": int, "end": int, "indent": int} (end exclusive) or {} +## when absent. The header indent is detected dynamically so a hand-written +## file using non-2-space indentation is still found; children are lines +## deeper than the header. `end` stops right AFTER the last content line: +## trailing blank and comment lines between our entry and the next sibling +## belong to the file, not to our block, so `_replace_lines` / `_remove_lines` +## (which splice [start, end)) never delete them (#867 review). +static func _find_entry_block(lines: PackedStringArray, entry_id_value: String, require_nested: bool) -> Dictionary: + for i in range(lines.size()): + var indent := _indent_of(lines[i]) + if require_nested and indent <= 0: + continue + if not require_nested and indent != 0: + continue + var parsed := _parse_entry_header(lines[i]) + if parsed.is_empty() or parsed.get("id") != entry_id_value: + continue + ## A nested match must actually live inside an `- insert:` row: a + ## `- id:` list under some other top-level row (an override row's own + ## sequence, say) is not a loader entry and is not ours to touch. + if require_nested and not _under_insert_row(lines, i): + continue + var j := i + 1 + var last_content := i + while j < lines.size(): + var l := lines[j] + if _is_blank_or_comment(l): + j += 1 + continue + if _indent_of(l) <= indent: + break + last_content = j + j += 1 + return {"start": i, "end": last_content + 1, "indent": indent} + return {} + + +## True when the nearest preceding 0-indent content line above `index` is an +## `- insert:` row header. Blank and comment lines are skipped; hitting the +## top of the file without a header means the nested line is orphaned and +## cannot be a loader entry. +static func _under_insert_row(lines: PackedStringArray, index: int) -> bool: + for i in range(index - 1, -1, -1): + if _is_blank_or_comment(lines[i]): + continue + if _indent_of(lines[i]) == 0: + return lines[i].strip_edges().begins_with("- insert:") + return false + + +## Parse a `- id: ` header line into {"id": String}. Returns {} for +## any other line. The value may be plain or single/double-quoted. +static func _parse_entry_header(line: String) -> Dictionary: + var stripped := line.strip_edges() + if not stripped.begins_with("- "): + return {} + var body := stripped.substr(2).strip_edges() + if not body.begins_with("id:"): + return {} + var value := body.substr(3).strip_edges() + if value.begins_with("\"") and value.ends_with("\"") and value.length() >= 2: + var parsed: Variant = JSON.parse_string(value) + if parsed is String: + value = parsed + elif value.begins_with("'") and value.ends_with("'") and value.length() >= 2: + value = value.substr(1, value.length() - 2) + return {"id": value} + + +## Extract the `config:` sub-dict from a found entry block. Fields may nest +## (env, reconnect); deeper values are parsed with the same scalar coercion +## the YAML strategy uses. Returns {} when the block has no config block. +static func _extract_config(lines: PackedStringArray, block: Dictionary) -> Dictionary: + var start := int(block.get("start", -1)) + var end := int(block.get("end", -1)) + if start < 0: + return {} + var config_indent := -1 + var config_start := -1 + for i in range(start, end): + var stripped := lines[i].strip_edges() + if _is_blank_or_comment(lines[i]): + continue + if stripped == "config:": + config_indent = _indent_of(lines[i]) + config_start = i + break + if config_start < 0: + return {} + return _parse_block_lines(lines, config_start + 1, end, config_indent) + + +## Parse sibling `key: value` lines at a fixed minimum indent into a +## Dictionary. Nested blocks (a key with no inline value) recurse and their +## child lines are consumed by the recursion — the parent index advances past +## them so they are never re-parsed as top-level config fields (#867 review). +## Flow arrays parse back into Arrays via JSON. Quoted and plain scalars +## strip via the YAML strategy's shared `coerce_scalar`. +static func _parse_block_lines(lines: PackedStringArray, start: int, end: int, min_indent: int) -> Dictionary: + var out: Dictionary = {} + var i := start + while i < end: + var l := lines[i] + if _is_blank_or_comment(l): + i += 1 + continue + var indent := _indent_of(l) + if indent <= min_indent: + break + var stripped := l.strip_edges() + var colon := stripped.find(":") + if colon < 0: + i += 1 + continue + var key := stripped.substr(0, colon).strip_edges() + var value := stripped.substr(colon + 1).strip_edges() + if value.is_empty(): + ## Nested block: find where its children end (a line at or above + ## the block key's indent), parse only that span, and jump past it. + var child_end := i + 1 + while child_end < end: + if not _is_blank_or_comment(lines[child_end]) and _indent_of(lines[child_end]) <= indent: + break + child_end += 1 + out[key] = _parse_block_lines(lines, i + 1, child_end, indent) + i = child_end + else: + ## Shared with the YAML strategy so the two dialects can never + ## drift on quoting/typing rules (#867 review). + out[key] = McpYamlStrategy.coerce_scalar(value) + i += 1 + return out + + +# --- Rewrites --------------------------------------------------------------- + +## Append a new `- insert:` row at the end of the file. A blank separator +## line keeps rows visually distinct; the file always ends with a newline. +static func _append_row(lines: PackedStringArray, nested_lines: PackedStringArray) -> String: + var parts: Array[String] = [] + for l in lines: + parts.append(l) + ## Collapse trailing blank lines so the appended row is not orphaned + ## below stray empties; one separator blank keeps rows readable. + while parts.size() > 0 and String(parts[parts.size() - 1]).strip_edges().is_empty(): + parts.remove_at(parts.size() - 1) + if parts.size() > 0: + parts.append("") + parts.append("- insert:") + for l in nested_lines: + parts.append(l) + return _join_lines(parts) + + +## Replace the lines owned by our entry. When the found block is a plain +## top-level row (indent 0 header), the whole row — including its children — +## is replaced by the insert form. When it is a nested block inside an +## insert row, only that block's lines are replaced, leaving sibling entries +## and comments in the same row byte-for-byte intact. +static func _replace_lines(lines: PackedStringArray, block: Dictionary, nested_lines: PackedStringArray) -> String: + var start := int(block.get("start", -1)) + var end := int(block.get("end", -1)) + var parts: Array[String] = [] + for i in range(lines.size()): + if i == start: + ## A nested block keeps the surrounding `- insert:` row, so only + ## the nested entry lines (indent > 0) are spliced in. + if _indent_of(lines[start]) > 0: + for l in nested_lines: + parts.append(l) + else: + parts.append("- insert:") + for l in nested_lines: + parts.append(l) + if i >= start and i < end: + continue + parts.append(lines[i]) + return _join_lines(parts) + + +## Remove our entry. A nested block is spliced out; if its enclosing insert +## row is left without any nested entries (only the bare `- insert:` header, +## blanks, and comments), the row header goes too so the file stays a valid +## patch list. A plain row for our id is removed wholesale. +static func _remove_lines(lines: PackedStringArray, block: Dictionary) -> String: + var start := int(block.get("start", -1)) + var end := int(block.get("end", -1)) + var nested := _indent_of(lines[start]) > 0 + var parts: Array[String] = [] + if nested: + ## Find the enclosing `- insert:` row header: the nearest preceding + ## 0-indent `- ` line. + var row_start := -1 + for i in range(start - 1, -1, -1): + if _indent_of(lines[i]) == 0 and lines[i].strip_edges().begins_with("- "): + row_start = i + break + ## Row end: first 0-indent non-blank/comment line after the block. + var row_end := lines.size() + for i in range(end, lines.size()): + if _indent_of(lines[i]) == 0 and not _is_blank_or_comment(lines[i]): + row_end = i + break + var has_other_entries := false + for i in range(row_start + 1, row_end): + if i >= start and i < end: + continue + if _is_blank_or_comment(lines[i]): + continue + if _indent_of(lines[i]) > 0 and lines[i].strip_edges().begins_with("- "): + has_other_entries = true + break + if has_other_entries or row_start < 0: + ## Only our block goes; sibling entries and any trailing + ## comments in the same row survive. + for i in range(lines.size()): + if i >= start and i < end: + continue + parts.append(lines[i]) + else: + ## The row held only our entry: drop the `- insert:` header and + ## our block, but keep trailing blank/comment lines — a comment + ## the user wrote above the next row must survive (#867 review). + for i in range(lines.size()): + if i >= row_start and i < end: + continue + parts.append(lines[i]) + parts = _trim_trailing_blanks(parts) + else: + ## Plain top-level row for our id: drop the whole block. + for i in range(lines.size()): + if i >= start and i < end: + continue + parts.append(lines[i]) + parts = _trim_trailing_blanks(parts) + return _join_lines(parts) + + +## Remove trailing blank lines left behind by a removal. +static func _trim_trailing_blanks(parts: Array[String]) -> Array[String]: + while parts.size() > 0 and String(parts[parts.size() - 1]).strip_edges().is_empty(): + parts.remove_at(parts.size() - 1) + return parts + + +## True when the text holds no patch rows at all — blank lines and comments +## only. Such a file cannot be written back (see `remove`), because dsh's +## patch parser rejects a non-array file at boot. +static func _is_blank_or_comment_only(text: String) -> bool: + for line in text.split("\n"): + var stripped := line.strip_edges() + if not stripped.is_empty() and not stripped.begins_with("#"): + return false + return true + + +## When the document's only content line is the empty flow sequence `[]`, +## return the text with that one line removed — blanks and comments stay, +## because they belong to the user. Any other document comes back unchanged; +## a `[]` mixed with real rows is left for `_is_patch_sequence` to refuse. +static func _strip_empty_flow_sequence(text: String) -> String: + var lines := _split_lines(text) + var bracket_line := -1 + for i in range(lines.size()): + if _is_blank_or_comment(lines[i]): + continue + if bracket_line < 0 and lines[i].strip_edges() == "[]": + bracket_line = i + continue + return text + if bracket_line < 0: + return text + var parts: Array[String] = [] + for i in range(lines.size()): + if i != bracket_line: + parts.append(lines[i]) + if parts.is_empty(): + return "" + return _join_lines(parts) + + +## True when the text is a valid loader patch list (or empty/comment-only / +## the empty flow sequence `[]`, which all mean "no layer"). Anything else — +## a top-level mapping or scalar — would make dsh fail boot, so Configure +## refuses to write into it instead of producing a broken file (#867 review). +## Only 0-indent content lines define the top-level structure: they must all +## be `- ` rows. Deeper lines are row children and are not inspected. `[]` is +## valid only as the COMPLETE document — appending rows after the empty flow +## sequence would produce malformed YAML, so a mixed `[]` + rows file fails +## the check too. +static func _is_patch_sequence(text: String) -> bool: + if text.strip_edges().is_empty(): + return true + var saw_brackets := false + var content_count := 0 + for line in text.split("\n"): + var stripped := line.strip_edges() + if stripped.is_empty() or stripped.begins_with("#"): + continue + content_count += 1 + if stripped == "[]": + saw_brackets = true + continue + if _indent_of(line) == 0 and not stripped.begins_with("- "): + return false + if saw_brackets and content_count > 1: + return false + return true + + +static func _join_lines(parts: Array) -> String: + if parts.is_empty(): + return "" + var lines: Array[String] = [] + for p in parts: + lines.append(String(p)) + return "\n".join(lines) + "\n" + + +# --- Small helpers ---------------------------------------------------------- + +static func _indent_str(n: int) -> String: + var out := "" + for i in range(n): + out += " " + return out + + +static func _indent_of(line: String) -> int: + var n := 0 + while n < line.length() and (line[n] == " " or line[n] == "\t"): + n += 1 + return n + + +static func _is_blank_or_comment(line: String) -> bool: + var stripped := line.strip_edges() + return stripped.is_empty() or stripped.begins_with("#") + + +static func _array_copy(value: Variant) -> Array: + if value is Array: + return (value as Array).duplicate(true) + if value is PackedStringArray: + return McpClient._array_from_packed(value) + return [] + + +static func _arrays_equal(left: Variant, right: Variant) -> bool: + if not (left is Array or left is PackedStringArray): + return false + if not (right is Array or right is PackedStringArray): + return false + var left_array := _array_copy(left) + var right_array := _array_copy(right) + if left_array.size() != right_array.size(): + return false + for i in range(left_array.size()): + if left_array[i] != right_array[i]: + return false + return true + + +## Returns {"ok": true, "data": String} when the file is absent or readable, +## and {"ok": false, "error": String} when unreadable. Callers must NOT fall +## back to an empty string on the error path — doing so blows away the user's +## other patch rows on the next write. +static func _read(path: String) -> Dictionary: + if not FileAccess.file_exists(path): + return {"ok": true, "data": ""} + var f := FileAccess.open(path, FileAccess.READ) + if f == null: + var err := FileAccess.get_open_error() + return {"ok": false, "error": "could not open for reading (%s)" % error_string(err)} + var t := f.get_as_text() + f.close() + return {"ok": true, "data": t} diff --git a/addons/godot_ai/clients/_dsh_strategy.gd.uid b/addons/godot_ai/clients/_dsh_strategy.gd.uid new file mode 100644 index 0000000..36703f4 --- /dev/null +++ b/addons/godot_ai/clients/_dsh_strategy.gd.uid @@ -0,0 +1 @@ +uid://ch0brn7swb6qx diff --git a/addons/godot_ai/clients/_json_strategy.gd b/addons/godot_ai/clients/_json_strategy.gd new file mode 100644 index 0000000..9fb40eb --- /dev/null +++ b/addons/godot_ai/clients/_json_strategy.gd @@ -0,0 +1,989 @@ +@tool +class_name McpJsonStrategy +extends RefCounted + +## Read–merge–write strategy for JSON-backed MCP clients. +## All knobs come from the McpClient descriptor as plain data — no Callables. +## See `_base.gd` for why descriptors are data-only. + + +static func configure( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, + project_roots: PackedStringArray = PackedStringArray(), +) -> Dictionary: + if _uses_merge_tiers(client): + return _configure_merged(client, server_name, server_url, launch, project_roots) + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty(): + return {"status": "error", "message": "Could not resolve config path for %s on this OS" % client.display_name} + + var seed_path := str(resolution.get("seed_path", "")) + var read_path := seed_path if not FileAccess.file_exists(path) and not seed_path.is_empty() else path + var read := _read_or_init(read_path) + if not read["ok"]: + return {"status": "error", "message": "Refusing to overwrite %s: %s. Fix or move the file, then re-run Configure." % [read_path, read["error"]]} + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": "error", "message": launch_error} + var config: Dictionary = read["data"] + var holder := _ensure_path(config, select_server_key_path(config, client)) + ## Pass the existing entry through so `build_entry` can preserve user-mutable + ## state (auto-approval lists, `disabled` toggles) instead of resetting it + ## to descriptor defaults on every Configure click. See `entry_initial_fields` + ## docs in `_base.gd`. + var existing: Variant = holder.get(server_name, null) + holder[server_name] = build_entry(client, server_url, existing, launch) + + # F5: refuse to re-serialize a file whose parsed integers above 2^53 would + # lose precision. Editing by hand keeps those values intact. + if _has_lossy_numbers(config): + return {"status": "error", "message": "Refusing to rewrite %s: contains integers above 2^53 that Godot's JSON parser would re-emit imprecise. Edit the file by hand." % path} + if not McpAtomicWrite.write(path, JSON.stringify(_narrow_integral_numbers(config), "\t", false)): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": McpClient.configured_message(client, server_url)} + +## Pi-style clients merge several global config files. Update the effective +## highest-precedence definition; fail closed when a project override exists +## because Pi's external working directory cannot be inferred safely here. +static func _configure_merged( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary, + project_roots: PackedStringArray, +) -> Dictionary: + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": "error", "message": launch_error} + var project := _load_project_definitions(client, server_name, project_roots) + if not project.get("ok", false): + return {"status": "error", "message": str(project.get("error", "Cannot inspect project config tiers"))} + var project_tiers: Array = project.get("tiers", []) + if not project_tiers.is_empty(): + return {"status": "error", "message": _project_override_message(project_tiers, "update or remove", client.display_name, server_name)} + var loaded := _load_merge_tiers(client) + if not loaded.get("ok", false): + return {"status": "error", "message": str(loaded.get("error", "Cannot read merged config tiers"))} + var tiers: Array = loaded.get("tiers", []) + if tiers.is_empty(): + return {"status": "error", "message": "Could not resolve config path for %s on this OS" % client.display_name} + var target_index := 0 + for index in range(tiers.size()): + var config: Dictionary = tiers[index]["data"] + var holder := _walk_path(config, select_server_key_path(config, client)) + if holder is Dictionary and holder.has(server_name): + target_index = index + var tier: Dictionary = tiers[target_index] + var config: Dictionary = tier["data"] + var holder := _ensure_path(config, select_server_key_path(config, client)) + var existing: Variant = holder.get(server_name, null) + holder[server_name] = build_entry(client, server_url, existing, launch) + var path := str(tier["path"]) + # F5: refuse to re-serialize a tier whose parsed integers above 2^53 would + # lose precision. The same check guards the simple `configure` path. + if _has_lossy_numbers(config): + return {"status": "error", "message": "Refusing to rewrite %s: contains integers above 2^53 that Godot's JSON parser would re-emit imprecise. Edit the file by hand." % path} + if not McpAtomicWrite.write(path, JSON.stringify(_narrow_integral_numbers(config), "\t", false)): + return {"status": "error", "message": "Cannot write to %s" % path} + # Codex F1 caveat: when we wrote a global tier but couldn't find any project + # override in the roots we probed AND the user hasn't told us where Pi (or any + # external cwd client) actually runs from, we can't prove this write is the + # effective config. Surface the actionable hint instead of silently passing. + # The early `not project_tiers.is_empty()` return above already covers the + # "project override exists in probed roots" case (we fail closed there), so + # reaching this point with `project_tiers.is_empty()` means: no probed + # override was found. + var message := McpClient.configured_message(client, server_url) + var external_cwd := str(McpClientConfigurator._editor_setting_lookup(McpClientConfigurator.SETTING_EXTERNAL_CLIENT_CWD)) + if external_cwd.is_empty() and project_tiers.is_empty(): + message += " If %s is launched from a cwd this editor cannot see, the effective entry may still be in a project-tier file — set godot_ai/external_client_cwd to that cwd to verify." % client.display_name + return {"status": "ok", "message": message} + + +static func check_status( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, + project_roots: PackedStringArray = PackedStringArray(), +) -> McpClient.Status: + return check_status_details(client, server_name, server_url, launch, project_roots).get("status", McpClient.Status.NOT_CONFIGURED) + + +## Detailed variant feeding the dock's error_msg plumbing (#711): a config +## file that EXISTS but can't be read or parsed is Status.ERROR carrying the +## read/parse error, not NOT_CONFIGURED — the write path refuses to touch +## such a file (see `_read_or_init`), so the status dot must say "broken +## file", not "click Configure". +static func check_status_details( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, + project_roots: PackedStringArray = PackedStringArray(), +) -> Dictionary: + if _uses_merge_tiers(client): + return _check_status_merged(client, server_name, server_url, launch, project_roots) + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": McpClient.Status.ERROR, "error_msg": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + var read := _read_or_init(path) + if not read["ok"]: + return {"status": McpClient.Status.ERROR, "error_msg": String(read["error"])} + var config: Dictionary = read["data"] + var holder := _walk_path(config, select_server_key_path(config, client)) + if not (holder is Dictionary) or not holder.has(server_name): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + return _entry_status_details(client, holder[server_name], server_url, launch) + + +## Verify the effective last definition after applying the client's merge order. +static func _check_status_merged( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary, + project_roots: PackedStringArray, +) -> Dictionary: + var loaded := _load_merge_tiers(client) + if not loaded.get("ok", false): + return {"status": McpClient.Status.ERROR, "error_msg": str(loaded.get("error", "Cannot read merged config tiers"))} + var effective: Variant = null + for tier in loaded.get("tiers", []): + var config: Dictionary = tier["data"] + var holder := _walk_path(config, select_server_key_path(config, client)) + if holder is Dictionary and holder.has(server_name): + effective = holder[server_name] + var project := _load_project_definitions(client, server_name, project_roots) + if not project.get("ok", false): + return {"status": McpClient.Status.ERROR, "error_msg": str(project.get("error", "Cannot inspect project config tiers"))} + var project_tiers: Array = project.get("tiers", []) + if not project_tiers.is_empty(): + # Last-definition-wins mirrors the global-tier fold above and how + # pi-codemode-mcp merges project tiers on disk. Earlier tiers are dead + # once a later one defines the same server, so an early-stale entry + # doesn't make Pi's effective config drift (codex-review finding F2). + # Pass `[latest]` to `_project_override_message` so the error names only + # the file the user actually has to edit. + var latest: Dictionary = project_tiers[project_tiers.size() - 1] + var details := _entry_status_details(client, latest["entry"], server_url, launch) + if details.get("status") != McpClient.Status.CONFIGURED: + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": _project_override_message([latest], "update or remove", client.display_name, server_name)} + return {"status": McpClient.Status.CONFIGURED, "error_msg": ""} + if effective == null: + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + return _entry_status_details(client, effective, server_url, launch) + + +static func _entry_status_details( + client: McpClient, + entry: Variant, + server_url: String, + launch: Dictionary, +) -> Dictionary: + if not (entry is Dictionary): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": McpClient.Status.ERROR, "error_msg": launch_error} + if verify_entry(client, entry, server_url, launch): + return {"status": McpClient.Status.CONFIGURED, "error_msg": ""} + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + + +static func remove( + client: McpClient, + server_name: String, + project_roots: PackedStringArray = PackedStringArray(), +) -> Dictionary: + if _uses_merge_tiers(client): + return _remove_merged(client, server_name, project_roots) + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": "ok", "message": "Not configured"} + # Token-preserving removal (F5): pull the original file text via + # `_read_file_text` and edit only the entry's bytes — keeps every other + # byte, including integers above 2^53, byte-for-byte identical to what + # the user wrote. The parsed-dict round-trip path is gone. + var file_read := _read_file_text(path) + if not file_read.get("ok", false): + return {"status": "error", "message": "Refusing to rewrite %s: %s." % [path, file_read.get("error", "")]} + var config: Dictionary = file_read.get("data", {}) + var key_path := select_server_key_path(config, client) + var original_text: String = str(file_read.get("original_text", "")) + var updated: String = _text_remove_server_entry(original_text, key_path, server_name) + if updated == original_text: + return {"status": "ok", "message": "Not configured"} + if not McpAtomicWrite.write(path, updated): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + + +static func _remove_merged( + client: McpClient, server_name: String, project_roots: PackedStringArray +) -> Dictionary: + var project := _load_project_definitions(client, server_name, project_roots) + if not project.get("ok", false): + return {"status": "error", "message": str(project.get("error", "Cannot inspect project config tiers"))} + var project_tiers: Array = project.get("tiers", []) + if not project_tiers.is_empty(): + return {"status": "error", "message": _project_override_message(project_tiers, "remove", client.display_name, server_name)} + var loaded := _load_merge_tiers(client) + if not loaded.get("ok", false): + return {"status": "error", "message": str(loaded.get("error", "Cannot read merged config tiers"))} + var writes: Array[Dictionary] = [] + for tier in loaded.get("tiers", []): + if not tier.get("exists", false): + continue + var key_path := select_server_key_path(tier["data"], client) + var original: String = str(tier.get("original_text", "")) + # Token-preserving removal (F5): edit `original` textually instead of + # re-serialising the parsed config. This preserves every byte outside + # the entry block, so unrelated integers (including those above the + # IEEE-754 exact-int range that `_narrow_integral_numbers` cannot + # round-trip) keep their original literals. + var updated: String = _text_remove_server_entry(original, key_path, server_name) + if updated == original: + continue # entry not in this tier; skip + writes.append({ + "path": tier["path"], + "text": updated, + "original_text": original, + }) + if writes.is_empty(): + return {"status": "ok", "message": "Not configured"} + var written := _write_transaction(writes) + if not written.get("ok", false): + return {"status": "error", "message": written.get("error", "Cannot remove merged configuration")} + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + + +## Synthesize the entry dict the strategy writes under +## `server_key_path[server_name]`. Both URL and command entries deep-copy the +## existing dict before overwriting strategy-owned fields, preserving unknown +## client additions as well as descriptor-documented user fields. +static func build_entry( + client: McpClient, + server_url: String, + existing: Variant = null, + launch: Dictionary = {}, +) -> Dictionary: + if _is_supported_command_shape(client.command_shape): + var command_entry: Dictionary = (existing as Dictionary).duplicate(true) if existing is Dictionary else {} + if client.command_shape == McpClient.CommandShape.COMMAND_ARRAY: + ## OpenCode-style: the entry's `command` field IS the argv array. + ## A stale sibling `args` from a FLAT-style hand edit would be + ## ambiguous next to it, so it is strategy-owned and removed. + command_entry["command"] = _launch_argv(launch) + command_entry.erase("args") + else: + command_entry["command"] = str(launch.get("command", "")) + command_entry["args"] = _array_copy(launch.get("args", [])) + if not client.command_transport_key.is_empty(): + command_entry[client.command_transport_key] = client.command_transport_value + for key in client.command_initial_fields: + if not command_entry.has(key): + command_entry[key] = client.command_initial_fields[key] + for key in client.command_legacy_keys: + command_entry.erase(String(key)) + _remove_legacy_env_keys(command_entry, client.command_env_legacy_keys) + return command_entry + if client.command_shape != McpClient.CommandShape.NONE: + return {} + return build_url_entry(client, server_url, existing) + + +static func build_url_entry(client: McpClient, server_url: String, existing: Variant = null) -> Dictionary: + var entry: Dictionary = (existing as Dictionary).duplicate(true) if existing is Dictionary else {} + entry[client.entry_url_field] = server_url + for k in client.entry_extra_fields: + entry[k] = client.entry_extra_fields[k] + for k in client.entry_initial_fields: + if not entry.has(k): + entry[k] = client.entry_initial_fields[k] + return entry + + +## Default verifier for a stored entry. Command entries must match every +## launch-affecting value exactly; legacy URL or env keys are migration drift. +## For URL clients, assert `entry[entry_url_field] == url` AND every +## key in `entry_extra_fields` matches verbatim. Type-pinning for Cline / +## Roo / Kilo (`type: "streamable-http"` etc.) falls out of this — pre-fix +## entries that lack the type field fail verification and surface as drift. +static func verify_entry( + client: McpClient, + entry: Dictionary, + server_url: String, + launch: Dictionary = {}, +) -> bool: + if client.command_shape != McpClient.CommandShape.NONE: + if not _is_supported_command_shape(client.command_shape) or not bool(launch.get("ok", false)): + return false + for key in client.command_legacy_keys: + if entry.has(String(key)): + return false + var env = entry.get("env", null) + if env is Dictionary: + for key in client.command_env_legacy_keys: + if env.has(String(key)): + return false + if client.command_shape == McpClient.CommandShape.COMMAND_ARRAY: + if not _arrays_equal(entry.get("command", null), _launch_argv(launch)): + return false + if entry.has("args"): + return false + else: + if entry.get("command") != launch.get("command"): + return false + if not _arrays_equal(entry.get("args", null), launch.get("args", null)): + return false + if not client.command_transport_key.is_empty(): + if not entry.has(client.command_transport_key): + return false + if entry.get(client.command_transport_key) != client.command_transport_value: + return false + return true + if entry.get(client.entry_url_field, "") != server_url: + return false + for k in client.entry_extra_fields: + if entry.get(k) != client.entry_extra_fields[k]: + return false + return true + + +static func command_launch_error(client: McpClient, launch: Dictionary) -> String: + if client.command_shape == McpClient.CommandShape.NONE: + return "" + if not _is_supported_command_shape(client.command_shape): + return "%s uses a command shape not supported by JSON yet" % client.display_name + if not bool(launch.get("ok", false)): + return str(launch.get("error", "No compatible attach launcher was found.")) + return "" + + +static func _is_supported_command_shape(shape: McpClient.CommandShape) -> bool: + return shape == McpClient.CommandShape.FLAT or shape == McpClient.CommandShape.COMMAND_ARRAY + + +## The full launch argv as one array: launcher path followed by every arg. +static func _launch_argv(launch: Dictionary) -> Array: + var argv: Array = [str(launch.get("command", ""))] + argv.append_array(_array_copy(launch.get("args", []))) + return argv + + +static func _remove_legacy_env_keys(entry: Dictionary, legacy_keys: PackedStringArray) -> void: + if legacy_keys.is_empty(): + return + var existing_env = entry.get("env", null) + if not (existing_env is Dictionary): + return + var env: Dictionary = (existing_env as Dictionary).duplicate(true) + for key in legacy_keys: + env.erase(String(key)) + if env.is_empty(): + entry.erase("env") + else: + entry["env"] = env + + +static func _array_copy(value: Variant) -> Array: + if value is Array: + return (value as Array).duplicate(true) + if value is PackedStringArray: + return McpClient._array_from_packed(value) + return [] + + +static func _arrays_equal(left: Variant, right: Variant) -> bool: + if not (left is Array or left is PackedStringArray): + return false + if not (right is Array or right is PackedStringArray): + return false + var left_array := _array_copy(left) + var right_array := _array_copy(right) + if left_array.size() != right_array.size(): + return false + for i in range(left_array.size()): + if left_array[i] != right_array[i]: + return false + return true + + +## Read a config file once and parse the captured text. Returns +## {"exists": bool, "ok": bool, "data": Dictionary, "original_text": String} +## when the file is absent or parses cleanly, and +## {"exists": true, "ok": false, "error": String, "original_text": String} +## when the file exists with non-empty content we cannot safely round-trip. +## Callers must NOT treat the error path as an empty config — doing so blows +## away the user's other MCP entries on the next write. The `original_text` +## is the exact captured source so transactional rollback can restore +## byte-for-byte; the UTF-8 BOM is stripped only from the parsing copy. +static func _read_file_text(path: String) -> Dictionary: + if not FileAccess.file_exists(path): + return {"exists": false, "ok": true, "data": {}, "original_text": ""} + var file := FileAccess.open(path, FileAccess.READ) + if file == null: + var open_err := FileAccess.get_open_error() + return {"exists": true, "ok": false, "error": "could not open for reading (error %d)" % open_err, "original_text": ""} + var content := file.get_as_text() + file.close() + if content.strip_edges().is_empty(): + return {"exists": true, "ok": true, "data": {}, "original_text": content} + var parse_copy := content + # Strip a UTF-8 BOM if present — some editors (notably on Windows) save + # JSON with a leading , which Godot's JSON.parse rejects outright. + # Previously this landed on the "unparseable → wipe" path. + if parse_copy.begins_with(""): + parse_copy = parse_copy.substr(1) + var json := JSON.new() + if json.parse(parse_copy) != OK: + var msg := "JSON parse error on line %d: %s" % [json.get_error_line(), json.get_error_message()] + push_warning("MCP | %s in %s" % [msg, path]) + return {"exists": true, "ok": false, "error": msg, "original_text": content} + if not (json.data is Dictionary): + return {"exists": true, "ok": false, "error": "top-level value is %s, expected object" % type_string(typeof(json.data)), "original_text": content} + return {"exists": true, "ok": true, "data": json.data, "original_text": content} + + +## Returns {"ok": true, "data": Dictionary} when the file is absent or parses +## cleanly, and {"ok": false, "error": String} when the file exists with +## non-empty content we cannot safely round-trip. Callers must NOT fall back +## to an empty dict on the error path — doing so blows away the user's other +## MCP entries on the next write. +static func _read_or_init(path: String) -> Dictionary: + var read := _read_file_text(path) + var result: Dictionary = {"ok": read.get("ok", false), "data": read.get("data", {})} + if not result.get("ok", false): + result["error"] = read.get("error", "") + return result + + +## Walk a key path, creating intermediate Dicts as needed. Returns the leaf Dict. +static func _ensure_path(root: Dictionary, key_path: PackedStringArray) -> Dictionary: + var cur := root + for key in key_path: + var next = cur.get(key) + if not (next is Dictionary): + next = {} + cur[key] = next + cur = next + return cur + + +## Walk a key path, returning the leaf Dict if all hops exist; else null. +static func _walk_path(root: Dictionary, key_path: PackedStringArray) -> Variant: + var cur: Variant = root + for key in key_path: + if not (cur is Dictionary) or not cur.has(key): + return null + cur = cur[key] + return cur + + +## Match clients that accept multiple server-map keys without creating a +## higher-precedence canonical map that shadows an existing legacy map. A +## non-null scalar still wins, matching nullish-coalescing parsers; Configure's +## `_ensure_path` then repairs it using the strategy's existing behavior. +static func select_server_key_path(root: Dictionary, client: McpClient) -> PackedStringArray: + var candidates: Array[PackedStringArray] = [client.server_key_path] + # Dynamic access keeps mixed-snapshot self-updates parse-safe when a new + # strategy is briefly loaded with an older McpClient base (#398/#736). + var aliases = client.get("server_key_path_aliases") + if aliases is Array: + for alias in aliases: + if alias is PackedStringArray: + candidates.append(alias) + for key_path in candidates: + if _walk_path(root, key_path) != null: + return key_path + return client.server_key_path + + +static func _uses_merge_tiers(client: McpClient) -> bool: + var templates = client.get("config_merge_path_templates") + return templates is Dictionary and not templates.is_empty() + + +## Resolve the global config tiers in the client's documented merge order. +static func _merge_paths(client: McpClient) -> PackedStringArray: + var result := PackedStringArray() + var templates = client.get("config_merge_path_templates") + if templates is Dictionary: + var platform_key := McpPathTemplate.platform_key(templates) + if not platform_key.is_empty(): + var raw_paths: Variant = templates.get(platform_key, []) + if raw_paths is Array or raw_paths is PackedStringArray: + for template in raw_paths: + var path := McpPathTemplate.expand(str(template)).simplify_path() + if not path.is_empty() and not result.has(path): + result.append(path) + return result + + +## Pi's project tiers are relative to Pi's process cwd, not Godot's. Inspect +## plausible roots only to detect overrides; callers fail closed rather than +## mutating both guesses. +static func _project_candidate_paths( + client: McpClient, roots: PackedStringArray +) -> PackedStringArray: + var result := PackedStringArray() + var project_paths = client.get("config_merge_project_paths") + if not (project_paths is PackedStringArray): + return result + for project_path in project_paths: + var absolute_path := String(project_path).simplify_path() + if absolute_path.is_absolute_path() and FileAccess.file_exists(absolute_path) and not result.has(absolute_path): + result.append(absolute_path) + for root in roots: + if String(root).is_empty(): + continue + for relative_path in project_paths: + if String(relative_path).is_absolute_path(): + continue + var path := String(root).path_join(String(relative_path)).simplify_path() + if FileAccess.file_exists(path) and not result.has(path): + result.append(path) + return result + + +static func _load_project_definitions( + client: McpClient, server_name: String, project_roots: PackedStringArray +) -> Dictionary: + var tiers: Array[Dictionary] = [] + for path in _project_candidate_paths(client, project_roots): + var read := _read_or_init(path) + if not read.get("ok", false): + return {"ok": false, "error": "Cannot inspect project config %s: %s" % [path, read.get("error", "invalid JSON")]} + var config: Dictionary = read["data"] + var key_path := select_server_key_path(config, client) + var holder := _walk_path(config, key_path) + if holder is Dictionary and holder.has(server_name): + tiers.append({ + "path": path, + "data": config, + "key_path": key_path, + "entry": holder[server_name], + }) + return {"ok": true, "tiers": tiers} + + +static func _project_override_message( + tiers: Array, action: String, client_name: String, server_name: String +) -> String: + var paths := PackedStringArray() + for tier in tiers: + paths.append(str(tier["path"])) + return "%s project config overrides %s at %s. %s resolves project files from its own working directory, so the dock cannot safely choose one; %s the entry manually." % [client_name, server_name, ", ".join(paths), client_name, action] + + +static func _load_merge_tiers(client: McpClient) -> Dictionary: + var tiers: Array[Dictionary] = [] + for path in _merge_paths(client): + ## These templates never pass through `resolved_config_path_details`, + ## so they need its fail-closed gate here: `McpPathTemplate.expand` + ## leaves a token it cannot resolve in place, and the relative survivor + ## would be read — and on Configure, written — against the editor's own + ## working directory. Fail the whole fold rather than dropping the tier: + ## a dropped tier reads as "the user has no config there", which is + ## exactly the wrong thing to conclude when we could not look. + if not path.is_absolute_path(): + return { + "ok": false, + "error": McpClient.unresolved_config_path_error(client.display_name, path), + } + var read := _read_file_text(path) + if not read.get("ok", false): + return { + "ok": false, + "error": "Refusing to rewrite %s: %s. Fix or move the file, then re-run Configure." % [path, read.get("error", "invalid JSON")], + } + tiers.append({ + "path": path, + "exists": read.get("exists", false), + "original_text": read.get("original_text", ""), + "data": read.get("data", {}), + }) + return {"ok": true, "tiers": tiers} + + +## Commit a multi-file removal with best-effort rollback. Each individual write +## is atomic; this layer restores earlier tiers if a later commit fails. +static func _write_transaction(writes: Array[Dictionary]) -> Dictionary: + var completed: Array[Dictionary] = [] + for write in writes: + var path := str(write["path"]) + if McpAtomicWrite.write(path, str(write["text"])): + completed.append(write) + continue + var rollback_failed := PackedStringArray() + completed.reverse() + for previous in completed: + if not McpAtomicWrite.write(str(previous["path"]), str(previous["original_text"])): + rollback_failed.append(str(previous["path"])) + var suffix := "" + if not rollback_failed.is_empty(): + suffix = " Rollback also failed for: %s" % ", ".join(rollback_failed) + return {"ok": false, "error": "Cannot write to %s; earlier tier changes were rolled back.%s" % [path, suffix]} + return {"ok": true} +## Path that `_check_status_merged`'s last-wins logic would consider +## authoritative for the server entry, or "" when no entry is found in +## any tier. Mirrors the same project-tier / global-tier resolution the +## status check uses so callers (notably the dock Open/Reveal buttons) +## land on the file that actually drives Pi's effective config. +## +## Resolution order (codex round 3, F-3-4): +## 1. Latest project tier containing the entry — F2 last-wins means the +## latest of `.pi/mcp.json` and `.mcp.json` wins (matches `_check_status_merged`). +## 2. Latest global tier containing the entry — already iterated in +## merge order, last-iterated-wins (same loop pattern as +## `manual_target_details` lines 660-665). +## 3. "" when no tier has the entry — caller decides what fallback +## (`path_template`) to use. +## +## Returns "" (not `path_template`) on the "nothing anywhere" branch so +## the dock can distinguish "no entry yet" from "entry is at the +## template path" if it wants to. +static func authoritative_tier_path( + client: McpClient, + server_name: String, + project_roots: PackedStringArray, +) -> String: + if not _uses_merge_tiers(client): + return "" + var project := _load_project_definitions(client, server_name, project_roots) + if not bool(project.get("ok", false)): + return "" + var project_tiers: Array = project.get("tiers", []) + if not project_tiers.is_empty(): + # F2 last-wins: latest project tier is authoritative. When there are + # multiple project tiers, the user-visible status is driven by the + # latest, so the Open/Reveal buttons should send them there too. + var latest: Dictionary = project_tiers[project_tiers.size() - 1] + return str(latest.get("path", "")) + var loaded := _load_merge_tiers(client) + if not bool(loaded.get("ok", false)): + return "" + var tiers: Array = loaded.get("tiers", []) + # Iterate in priority order, overwrite `selected_path` each time we + # find a tier containing the entry. With Pi's merge path order + # [mcp.json, .mcp.json] this leaves the higher-precedence `.mcp.json`. + var selected_path: String = "" + for tier in tiers: + var data: Dictionary = tier.get("data", {}) + var holder: Variant = _walk_path(data, select_server_key_path(data, client)) + if holder is Dictionary and holder.has(server_name): + selected_path = str(tier.get("path", "")) + return selected_path + + +## Pick the file and top-level map shown by the manual JSON instructions using +## the same merge and alias precedence as automatic Configure. +static func manual_target_details( + client: McpClient, + server_name: String, + fallback_path: String, + project_roots: PackedStringArray = PackedStringArray(), +) -> Dictionary: + if _uses_merge_tiers(client): + var project := _load_project_definitions(client, server_name, project_roots) + if not project.get("ok", false): + return {"ok": false, "error": project.get("error", "Cannot inspect project config tiers")} + var project_tiers: Array = project.get("tiers", []) + if project_tiers.size() > 1: + return {"ok": false, "error": _project_override_message(project_tiers, "update or remove", client.display_name, server_name)} + if project_tiers.size() == 1: + var selected_project: Dictionary = project_tiers[0] + return { + "ok": true, + "path": selected_project["path"], + "key_path": selected_project["key_path"], + } + var loaded := _load_merge_tiers(client) + if not loaded.get("ok", false): + return {"ok": false, "error": loaded.get("error", "Cannot read merged config tiers")} + var tiers: Array = loaded.get("tiers", []) + var selected: Variant = tiers[0] if not tiers.is_empty() else null + for tier in tiers: + var config: Dictionary = tier["data"] + var holder := _walk_path(config, select_server_key_path(config, client)) + if holder is Dictionary and holder.has(server_name): + selected = tier + if selected != null: + var config: Dictionary = selected["data"] + return { + "ok": true, + "path": selected["path"], + "key_path": select_server_key_path(config, client), + } + var read := _read_or_init(fallback_path) + if not read.get("ok", false): + return {"ok": false, "error": "Cannot inspect %s: %s" % [fallback_path, read.get("error", "invalid JSON")]} + return { + "ok": true, + "path": fallback_path, + "key_path": select_server_key_path(read["data"], client), + } + + +## Godot's JSON.parse turns every JSON number into a float, so a later +## JSON.stringify re-emits the user's integer fields as "8080.0" — which strict +## consumers (Go's encoding/json into an int field, etc.) reject, and which +## needlessly rewrites every number across the user's *other* entries. Re-narrow +## exactly-representable integral floats back to int so they serialize without +## the ".0". Walks dicts/arrays in place and returns the (same) value. +## +## Integers above 2^53 already lost precision when Godot parsed them to double, +## so they're left as the float Godot produced rather than faking exactness — +## byte-perfect preservation would require not parsing the file at all, and such +## magnitudes don't occur in MCP client configs. +static func _narrow_integral_numbers(value: Variant) -> Variant: + match typeof(value): + TYPE_FLOAT: + if is_finite(value) and value == floor(value) and absf(value) <= 9007199254740992.0: + return int(value) + TYPE_DICTIONARY: + for k in value: + value[k] = _narrow_integral_numbers(value[k]) + TYPE_ARRAY: + for i in value.size(): + value[i] = _narrow_integral_numbers(value[i]) + return value + + +## True when `value` contains any float outside the IEEE-754 exact-int range +## (`abs(f) > 2^53`) that would lose precision when JSON.stringify re-emits it. +## The configure path refuses such files instead of silently mutating unrelated +## integers; the remove path never needs this check because it does +## token-preserving surgery (F5). +static func _has_lossy_numbers(value: Variant) -> bool: + match typeof(value): + TYPE_FLOAT: + # `>=` not `>`: `2^53 + 1` rounds down to `2^53.0` when Godot parses + # the integer to double, so even a "clean" `2^53.0` after parse may + # have lost a least-significant bit we cannot recover. Refusing at + # the boundary is conservative but correct — and 2^53+ magnitudes + # don't appear in real MCP client configs anyway. + if is_finite(value) and absf(value) >= 9007199254740992.0: + return true + TYPE_DICTIONARY: + for k in value: + if _has_lossy_numbers(value[k]): + return true + TYPE_ARRAY: + for i in value.size(): + if _has_lossy_numbers(value[i]): + return true + return false + + +## Token-preserving entry removal. Walks the JSON text with a brace-balanced +## scanner to locate the entry at `key_path[0]/.../[server_name]` and returns +## `text` with that entry's bytes deleted (along with the surrounding +## whitespace + trailing comma). Everything else — including integers above +## the IEEE-754 exact-int range that `_narrow_integral_numbers` would silently +## mutate — is preserved byte-for-byte. Returns `text` unchanged when the +## entry isn't found in `text` (callers treat this as a no-op write). +static func _text_remove_server_entry(text: String, key_path: PackedStringArray, server_name: String) -> String: + # Descend through `key_path`. Each step finds `"":` directly inside the + # current container and moves the cursor past the value's opening `{` or `[`. + # After the loop, `cursor` is positioned just past the opening bracket of the + # container that holds our entry, and `container_depth` tracks how deeply + # nested that container is from the root (0 = root object/array). + var cursor := 0 + # Skip past the root's opening `{` or `[` (and any leading whitespace or + # UTF-8 BOM) so `_find_key_at_container_depth` starts scanning from + # inside the root container with `inner_depth == 0`. Without this step, + # the first character encountered is the root's `{`, which bumps + # `inner_depth` to 1 and makes the top-level key check fail. The BOM + # skip mirrors `_read_file_text`'s parse_copy BOM-strip above so the + # scanner sees the same view of the file the parser does; the BOM + # itself stays in `text` so the byte-survival F5 contract still holds + # (codex round 3, F-3-6 — without it, files saved with a Windows BOM + # left the entry in place after Remove). + while cursor < text.length() and _is_json_ws(text[cursor]): + cursor += 1 + if cursor < text.length() and text[cursor] == "": + cursor += 1 + if cursor < text.length() and (text[cursor] == "{" or text[cursor] == "["): + cursor += 1 + var container_depth := 0 + for key in key_path: + var key_bytes := JSON.stringify(String(key)) + var match := _find_key_at_container_depth(text, cursor, key_bytes) + if match.is_empty(): + return text + var open_char := text[match["value_start"]] + if open_char != "{" and open_char != "[": + return text # leaf isn't an object/array — path can't reach our entry + container_depth += 1 + cursor = match["value_start"] + 1 + # Now find `"":` at the top level of the container we descended + # into (the helper gates on `inner_depth == 0`). + var entry_bytes := JSON.stringify(server_name) + var entry_match := _find_key_at_container_depth(text, cursor, entry_bytes) + if entry_match.is_empty(): + return text + var key_start: int = entry_match["key_start"] + var value_end: int = entry_match["value_end"] + # Trim the surrounding comma in a mutually exclusive way: the trailing comma + # (after the entry's value) carries the burden when the entry is NOT the last + # in its container, and the leading comma (before the entry's key) carries it + # only when the entry IS the last. Trimming BOTH unconditionally corrupts a + # middle-position entry into `"x"}"y"` with no separator — codex-review + # finding F5 (regression after the initial round). + var remove_end := value_end + # Skip JSON whitespace before checking for the trailing comma — valid + # (if unusual) formats like `"godot-ai":{} ,"other":{}` put whitespace + # between the value and its separator. codex round 4 finding. + var trailing_scan := remove_end + while trailing_scan < text.length() and _is_json_ws(text[trailing_scan]): + trailing_scan += 1 + var had_trailing_comma := trailing_scan < text.length() and text[trailing_scan] == "," + if had_trailing_comma: + # Jump past the comma (and any whitespace before it we just skipped). + remove_end = trailing_scan + 1 + while remove_end < text.length() and _is_json_ws(text[remove_end]): + remove_end += 1 + var remove_start := key_start + if not had_trailing_comma: + while remove_start > 0 and _is_json_ws(text[remove_start - 1]): + remove_start -= 1 + if remove_start > 0 and text[remove_start - 1] == ",": + remove_start -= 1 + while remove_start > 0 and _is_json_ws(text[remove_start - 1]): + remove_start -= 1 + return text.substr(0, remove_start) + text.substr(remove_end) + + +## Look for `key_bytes` (a JSON-encoded string literal including the surrounding +## quotes) at the TOP LEVEL of the container we're inside, scanning `text` from +## `start` onwards. The caller is expected to advance `start` just past the +## container's opening `{` or `[`, so we begin with `inner_depth == 0` and a +## key matches when we hit it while `inner_depth` is still 0. The scan exits +## immediately if `inner_depth` drops below 0 (the target container closed) +## to prevent same-named keys in later sibling containers from being picked +## up. Returns `{key_start, value_start, value_end}` on success or `{}` if +## the key isn't present in that container. +static func _find_key_at_container_depth(text: String, start: int, key_bytes: String) -> Dictionary: + var i := start + var in_string := false + var escape := false + var inner_depth := 0 # depth *inside* the current container + while i < text.length(): + var c := text[i] + if in_string: + if escape: + escape = false + elif c == "\\": + escape = true + elif c == '"': + in_string = false + i += 1 + continue + if c == '"': + if text.substr(i, key_bytes.length()) == key_bytes: + var after_key := i + key_bytes.length() + while after_key < text.length() and _is_json_ws(text[after_key]): + after_key += 1 + if after_key < text.length() and text[after_key] == ":": + var value_start := after_key + 1 + while value_start < text.length() and _is_json_ws(text[value_start]): + value_start += 1 + var value_end := _json_value_span_end(text, value_start) + if value_end >= 0 and inner_depth == 0: + return {"key_start": i, "value_start": value_start, "value_end": value_end} + in_string = true + i += 1 + continue + if c == "{" or c == "[": + inner_depth += 1 + elif c == "}" or c == "]": + inner_depth -= 1 + # Bail out the moment we leave the container we're scanning. Without + # this guard, a later sibling container at the same level (e.g. a + # top-level `extensions` block after `mcpServers` closes) re-balances + # `inner_depth` back to 0 and a same-named key in that sibling would + # match — silently deleting data we never intended to touch + # (codex-review finding F5, regression after the initial round). + if inner_depth < 0: + return {} + i += 1 + return {} + + +## Given `value_start` pointing at the first char of a JSON value, return the +## position AFTER the value's last char. Handles objects, arrays, strings, +## and bare literals (numbers, true/false/null). Returns -1 if the value is +## unterminated. +static func _json_value_span_end(text: String, value_start: int) -> int: + if value_start >= text.length(): + return -1 + var c := text[value_start] + if c == "{" or c == "[": + var open_char := c + var close_char := "}" if c == "{" else "]" + var depth := 1 + var i := value_start + 1 + var in_string := false + var escape := false + while i < text.length() and depth > 0: + var ch := text[i] + if in_string: + if escape: + escape = false + elif ch == "\\": + escape = true + elif ch == '"': + in_string = false + i += 1 + continue + if ch == '"': + in_string = true + elif ch == open_char: + depth += 1 + elif ch == close_char: + depth -= 1 + i += 1 + return i if depth == 0 else -1 + if c == '"': + var i := value_start + 1 + var escape := false + while i < text.length(): + var ch := text[i] + if escape: + escape = false + elif ch == "\\": + escape = true + elif ch == '"': + return i + 1 + i += 1 + return -1 + # Bare literal: number / true / false / null. Walk until a JSON-significant + # delimiter (`,`, `}`, `]`, or whitespace). + var i := value_start + while i < text.length(): + var ch := text[i] + if ch == "," or ch == "}" or ch == "]" or _is_json_ws(ch): + break + i += 1 + return i + + +static func _is_json_ws(c: String) -> bool: + return c == " " or c == "\t" or c == "\n" or c == "\r" diff --git a/addons/godot_ai/clients/_json_strategy.gd.uid b/addons/godot_ai/clients/_json_strategy.gd.uid new file mode 100644 index 0000000..5e41fbb --- /dev/null +++ b/addons/godot_ai/clients/_json_strategy.gd.uid @@ -0,0 +1 @@ +uid://g8a4iijpk22w diff --git a/addons/godot_ai/clients/_manual_command.gd b/addons/godot_ai/clients/_manual_command.gd new file mode 100644 index 0000000..3e178ca --- /dev/null +++ b/addons/godot_ai/clients/_manual_command.gd @@ -0,0 +1,383 @@ +@tool +class_name McpManualCommand +extends RefCounted + +const SHELL_POSIX := "posix" +const SHELL_POWERSHELL := "powershell" +## Keep this intersection deliberately small. PowerShell treats a leading `@` +## as splatting syntax and commas as list separators, while POSIX shells accept +## both literally; quoting either is safer than trying to infer token position. +const _SHELL_BARE_SAFE_CHARS := "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_+=:./-" + +## Synthesize the "Run this manually" string the dock surfaces when +## auto-configure can't find a CLI / write a file. Generated from the +## descriptor's declarative fields — there is no per-client builder +## Callable. See `_base.gd` for why descriptors are data-only. + + +static func build( + client: McpClient, + server_name: String, + server_url: String, + resolved_path: String, + launch: Dictionary = {}, + project_roots: PackedStringArray = PackedStringArray(), +) -> String: + match client.config_type: + "cli": + return _build_cli(client, server_name, server_url, resolved_path, launch, project_roots) + "json": + return _build_json(client, server_name, server_url, resolved_path, launch, project_roots) + "toml": + return _build_toml(client, server_name, server_url, resolved_path, launch) + "yaml": + return _build_yaml(client, server_name, server_url, resolved_path, launch) + "dsh": + return _build_dsh(client, server_name, server_url, resolved_path, launch) + return "" + + +## CLI clients: format the register template against the *short* CLI name so +## the user can paste it into a terminal regardless of where their binary +## lives. (The auto-configure path resolves to an absolute uvx-style path; +## that's noise for a paste-into-terminal hint. The attach launcher path +## inside a command-shape line stays absolute — status verification compares +## the registered command against the resolved launcher verbatim.) +static func _build_cli( + client: McpClient, + server_name: String, + server_url: String, + resolved_path: String = "", + launch: Dictionary = {}, + project_roots: PackedStringArray = PackedStringArray(), +) -> String: + if client.cli_register_template.is_empty() or client.cli_names.is_empty(): + return "" + var shell_kind := _shell_kind_for_platform() + var short_name: String = String(client.cli_names[0]) + # Prefer the non-.exe form for a cross-platform-looking command line. + for n in client.cli_names: + if not String(n).ends_with(".exe"): + short_name = String(n) + break + var cmd := "" + if client.command_shape != McpClient.CommandShape.NONE: + var launch_error := McpCliStrategy.command_launch_error(client, launch) + if not launch_error.is_empty(): + cmd = "Attach launch command unavailable: %s" % launch_error + else: + var args := McpCliStrategy.format_args(client.cli_register_template, server_name, server_url, launch) + var parts: Array[String] = [short_name] + for arg in args: + parts.append(String(arg)) + var lines := _sweep_lines(client, server_name, server_url, short_name, shell_kind) + lines.append(_render_command_line(parts, shell_kind)) + cmd = _format_shell_block(lines, shell_kind) + _sweep_caveat(client) + else: + var args := McpCliStrategy.format_args(client.cli_register_template, server_name, server_url) + var parts: Array[String] = [short_name] + for arg in args: + parts.append(String(arg)) + var lines := _sweep_lines(client, server_name, server_url, short_name, shell_kind) + lines.append(_render_command_line(parts, shell_kind)) + cmd = _format_shell_block(lines, shell_kind) + _sweep_caveat(client) + # #463: a CLI client with a JSON fallback (Claude Code) may have no `claude` + # binary at all — e.g. installed only as a VS Code/Cursor extension. The CLI + # line above is useless to that user, so also show the config-file edit that + # auto-configure falls back to writing. + if client.has_json_fallback() and not resolved_path.is_empty(): + return "%s\n\nNo `%s` CLI (e.g. installed as a VS Code/Cursor extension)? %s" % [ + cmd, short_name, _build_json(client, server_name, server_url, resolved_path, launch, project_roots), + ] + return cmd + + +## #877: Configure's first act is the pre-cleanup — it runs the unregister +## template once per scope the descriptor can write to (`_cli_strategy.gd` +## `configure`) before registering. Rendering only the register line made this +## hint disagree with what the button does, which is the worst property a +## "run this manually" string can have. The removes go in the SAME shell block +## as the register, in the order Configure runs them, so the whole thing stays +## one copy-paste rather than a labelled command plus loose prose. +static func _sweep_lines( + client: McpClient, + server_name: String, + server_url: String, + short_name: String, + shell_kind: String, +) -> Array[String]: + var lines: Array[String] = [] + if client.cli_unregister_template.is_empty(): + return lines + for pre_scope in McpCliStrategy.cleanup_scopes(client): + var args := McpCliStrategy.format_args( + client.cli_unregister_template, server_name, server_url, {}, pre_scope + ) + var parts: Array[String] = [short_name] + for arg in args: + parts.append(String(arg)) + lines.append(_render_command_line(parts, shell_kind)) + return lines + + +## The one thing the commands themselves cannot show: that the project pass +## resolves `.mcp.json` against the CLI's cwd, so it can delete an entry from a +## repository that has nothing to do with this project. Only for `{scope}` +## descriptors — a single implicit-scope pass removes exactly the entry the +## register is about to rewrite, which needs no warning. Kept outside the shell +## block so pasting the block never picks up prose. +static func _sweep_caveat(client: McpClient) -> String: + if client.cli_unregister_template.is_empty() or not McpCliStrategy.uses_scope_token(client): + return "" + return ( + "\n\nThe project-scope remove rewrites the .mcp.json in the directory the" + + " editor was launched from — not necessarily this project — so it drops a" + + " hand-maintained godot-ai entry there. Other servers in that file are left" + + " alone." + ) + + +static func _shell_kind_for_platform() -> String: + return SHELL_POWERSHELL if OS.get_name() == "Windows" else SHELL_POSIX + + +## Render a command for one explicitly named shell. The label is load-bearing: +## POSIX and PowerShell use different escaping for embedded single quotes, so +## presenting the command without its target shell invites a bad copy/paste. +static func _format_shell_command(parts: Array[String], shell_kind: String) -> String: + return _format_shell_block([_render_command_line(parts, shell_kind)], shell_kind) + + +## One label over N command lines. The label is per-block, not per-line: +## repeating "Run in PowerShell:" four times would bury the single line that +## actually registers. +static func _format_shell_block(lines: Array[String], shell_kind: String) -> String: + var label := "Run in PowerShell:" if shell_kind == SHELL_POWERSHELL else "Run in a POSIX shell:" + return "%s\n%s" % [label, "\n".join(lines)] + + +static func _render_command_line(parts: Array[String], shell_kind: String) -> String: + var rendered: Array[String] = [] + for part in parts: + rendered.append(_shell_display_arg(part, shell_kind)) + return " ".join(rendered) + + +## Quote one argv element for the paste-into-terminal hint. Single-quoted +## strings are literal in both supported shells, but embedded single quotes +## have shell-specific spellings. Backslashes, double quotes, dollar signs, +## and PowerShell backticks remain byte-for-byte unchanged inside the quotes. +static func _shell_display_arg(arg: String, shell_kind: String) -> String: + if arg.is_empty(): + return "''" + var stays_bare := true + for index in range(arg.length()): + if _SHELL_BARE_SAFE_CHARS.find(arg.substr(index, 1)) < 0: + stays_bare = false + break + if stays_bare: + return arg + if shell_kind == SHELL_POWERSHELL: + return "'%s'" % arg.replace("'", "''") + return "'%s'" % arg.replace("'", "'\"'\"'") + + +static func _build_json( + client: McpClient, + server_name: String, + server_url: String, + resolved_path: String, + launch: Dictionary = {}, + project_roots: PackedStringArray = PackedStringArray(), +) -> String: + var target := McpJsonStrategy.manual_target_details(client, server_name, resolved_path, project_roots) + var target_note := "" + if not target.get("ok", false): + target_note = "Target inspection failed: %s" % str(target.get("error", "cannot inspect config")) + target = {"path": resolved_path, "key_path": client.server_key_path} + var target_path := str(target.get("path", resolved_path)) + var key_path: PackedStringArray = target.get("key_path", client.server_key_path) + var key := key_path[0] if key_path.size() > 0 else "mcpServers" + if client.command_shape != McpClient.CommandShape.NONE: + var lines: Array[String] = [] + var launch_error := McpJsonStrategy.command_launch_error(client, launch) + if launch_error.is_empty(): + var command_entry := McpJsonStrategy.build_entry(client, server_url, null, launch) + lines.append("Edit %s and add under \"%s\":" % [target_path, key]) + lines.append(" \"%s\": %s" % [server_name, _format_entry_inline(command_entry)]) + else: + lines.append("Attach launch command unavailable: %s" % launch_error) + if client.command_supports_url_fallback: + lines.append("") + lines.append("Advanced fallback — use this URL-mode entry instead; never configure both shapes together. URL mode depends on your client's own reconnect behavior. If the server is down when the client starts, restarting the client may be required.") + lines.append("Edit %s and add under \"%s\":" % [target_path, key]) + var fallback_entry := McpJsonStrategy.build_url_entry(client, server_url) + lines.append(" \"%s\": %s" % [server_name, _format_entry_inline(fallback_entry)]) + if not target_note.is_empty(): + lines.append("") + lines.append(target_note) + return "\n".join(lines) + var entry := McpJsonStrategy.build_entry(client, server_url) + var instructions := "Edit %s and add under \"%s\":\n \"%s\": %s" % [target_path, key, server_name, _format_entry_inline(entry)] + if not target_note.is_empty(): + instructions += "\n\n" + target_note + return instructions + + +static func _build_toml( + client: McpClient, + _server_name: String, + server_url: String, + resolved_path: String, + launch: Dictionary = {}, +) -> String: + var header := _toml_header(client) + if client.command_shape != McpClient.CommandShape.NONE: + var lines: Array[String] = [] + var rendered := McpTomlStrategy.render_body(client, server_url, launch) + if bool(rendered.get("ok", false)): + lines.append("Edit %s and add:" % resolved_path) + lines.append(" %s" % header) + for body_line in rendered.get("lines", []): + lines.append(" %s" % str(body_line)) + else: + lines.append("Attach launch command unavailable: %s" % str(rendered.get("error", "no compatible launcher found"))) + if client.command_supports_url_fallback: + lines.append("") + lines.append("Advanced fallback — replace the command/args block above with this URL-mode block; never configure both shapes together. URL mode depends on your client's own reconnect behavior. If the server is down when the client starts, restarting the client may be required.") + lines.append("Edit %s and add:" % resolved_path) + lines.append(" %s" % header) + lines.append(" url = %s" % McpTomlStrategy.encode_basic_string(server_url)) + return "\n".join(lines) + var body := McpTomlStrategy.format_body(client.toml_body_template, server_url) + var lines: Array[String] = ["Edit %s and add:" % resolved_path, " %s" % header] + for b in body: + lines.append(" %s" % String(b)) + return "\n".join(lines) + + +static func _build_yaml( + client: McpClient, + server_name: String, + server_url: String, + resolved_path: String, + launch: Dictionary = {}, +) -> String: + var key := client.server_key_path[0] if client.server_key_path.size() > 0 else "mcp_servers" + if client.command_shape != McpClient.CommandShape.NONE: + var lines: Array[String] = [] + var launch_error := McpYamlStrategy.command_launch_error(client, launch) + if launch_error.is_empty(): + var command_entry := McpYamlStrategy.build_entry(client, server_url, null, launch) + lines.append("Edit %s and add under '%s':" % [resolved_path, key]) + for entry_line in McpYamlStrategy.render_entry_lines(server_name, command_entry): + lines.append(String(entry_line)) + else: + lines.append("Attach launch command unavailable: %s" % launch_error) + if client.command_supports_url_fallback: + lines.append("") + lines.append("Advanced fallback — use this URL-mode entry instead; never configure both shapes together. URL mode depends on your client's own reconnect behavior. If the server is down when the client starts, restarting the client may be required.") + lines.append("Edit %s and add under '%s':" % [resolved_path, key]) + var fallback_entry := {client.entry_url_field: server_url} + for entry_line in McpYamlStrategy.render_entry_lines(server_name, fallback_entry): + lines.append(String(entry_line)) + return "\n".join(lines) + var entry := McpYamlStrategy.build_entry(client, server_url) + var lines: Array[String] = [ + "Edit %s and add under '%s':" % [resolved_path, key], + " %s:" % server_name, + ] + for k in entry: + lines.append(" %s: %s" % [k, str(entry[k])]) + return "\n".join(lines) + + +## DeepSeek Harness: the user pastes a loader `insert` row into the home +## patch layer (`$DSH_HOME/cordis.patch.yml`). Auto-configure writes exactly +## these lines, so the manual text matches the file Configure would produce +## byte-for-byte. +static func _build_dsh( + client: McpClient, + server_name: String, + server_url: String, + resolved_path: String, + launch: Dictionary = {}, +) -> String: + var lines: Array[String] = ["Edit %s and add this loader entry (an `insert` row; a plain `- id:` row only overrides an existing bundle id and would be skipped):" % resolved_path] + var entry_id_value := McpDshStrategy.entry_id(server_name) + if client.command_shape != McpClient.CommandShape.NONE: + var launch_error := McpDshStrategy.command_launch_error(client, launch) + if launch_error.is_empty(): + var command_entry := McpDshStrategy.build_entry(client, server_name, server_url, null, launch) + for row_line in McpDshStrategy.render_insert_row(entry_id_value, command_entry): + lines.append(String(row_line)) + else: + lines.append("Attach launch command unavailable: %s" % launch_error) + if client.command_supports_url_fallback: + lines.append("") + ## No command/args block was rendered on the launch-error path, so + ## "replace the block above" would point at nothing. + var fallback_lead := ( + "replace the command/args block above with this URL-mode entry" + if launch_error.is_empty() + else "use this URL-mode entry instead" + ) + lines.append("Advanced fallback — %s; never configure both shapes together. URL mode depends on the harness' own reconnect behavior. If the server is down when the harness starts, restarting the harness may be required." % fallback_lead) + var fallback_entry := McpDshStrategy.build_url_entry(client, server_name, server_url) + for row_line in McpDshStrategy.render_insert_row(entry_id_value, fallback_entry): + lines.append(String(row_line)) + return "\n".join(lines) + var url_entry := McpDshStrategy.build_url_entry(client, server_name, server_url) + for row_line in McpDshStrategy.render_insert_row(entry_id_value, url_entry): + lines.append(String(row_line)) + return "\n".join(lines) + + +## Mirrors the [section."name"] header `_toml_strategy._primary_header` +## emits, kept here so the manual-command text matches the file we'd write. +static func _toml_header(client: McpClient) -> String: + var parts := client.toml_section_path + if parts.size() < 2: + return "[%s]" % ".".join(parts) + var section := ".".join(McpClient._array_from_packed(McpClient._packed_slice(parts, 0, parts.size() - 1))) + var name := parts[parts.size() - 1] + return "[%s.\"%s\"]" % [section, name] + + +## Format an entry dict as a single inline JSON-ish string, matching the +## pre-refactor manual-command style: `{ "k": v, "k": v }` with spaces. +## Pre-existing manual-command tests assert the exact substring shape; this +## keeps them stable. +## +## Uses `JSON.stringify` for every leaf String (key OR value) so paths +## containing backslashes / quotes / newlines render as syntactically valid +## JSON. A Windows uvx path like `C:\Users\foo\uvx.exe` would otherwise be +## emitted as `"C:\Users\foo\uvx.exe"` — invalid JSON, unsafe to paste. +static func _format_entry_inline(entry: Dictionary) -> String: + var parts: Array[String] = [] + for k in entry: + parts.append("%s: %s" % [JSON.stringify(String(k)), _format_value(entry[k])]) + if parts.is_empty(): + return "{}" + return "{ %s }" % ", ".join(parts) + + +static func _format_value(value: Variant) -> String: + # Strings, bools, numbers, null all round-trip correctly through JSON.stringify + # without spurious quoting of non-string scalars (true → `true`, 5 → `5`). + # Arrays and Dictionaries are formatted manually so the inline ` { k: v } ` + # spacing matches the pre-refactor manual-command output shape that tests + # pin with assert_contains. + if value is Array: + var arr_parts: Array[String] = [] + for v in value: + arr_parts.append(_format_value(v)) + return "[%s]" % ", ".join(arr_parts) + if value is Dictionary: + var d_parts: Array[String] = [] + for k in value: + d_parts.append("%s: %s" % [JSON.stringify(String(k)), _format_value(value[k])]) + if d_parts.is_empty(): + return "{}" + return "{ %s }" % ", ".join(d_parts) + return JSON.stringify(value) diff --git a/addons/godot_ai/clients/_manual_command.gd.uid b/addons/godot_ai/clients/_manual_command.gd.uid new file mode 100644 index 0000000..07a96f4 --- /dev/null +++ b/addons/godot_ai/clients/_manual_command.gd.uid @@ -0,0 +1 @@ +uid://ct1wmgfk408x0 diff --git a/addons/godot_ai/clients/_path_template.gd b/addons/godot_ai/clients/_path_template.gd new file mode 100644 index 0000000..8fc9753 --- /dev/null +++ b/addons/godot_ai/clients/_path_template.gd @@ -0,0 +1,242 @@ +@tool +class_name McpPathTemplate +extends RefCounted + +## Expands ~ / $HOME / $APPDATA / $XDG_CONFIG_HOME / $LOCALAPPDATA / $USERPROFILE +## inside path templates so per-client descriptors can declare paths declaratively +## without hand-rolling per-OS lookups. + +## #691: dock worker threads (client-status refresh, configure/remove +## actions) and the #678 startup walk's discovery worker expand these +## templates off the main thread, while the spawn step mutates the +## process-global environment around `OS.create_process` +## (`GODOT_AI_OWNER_PID`, `GODOT_AI_PLUGIN_SPAWNED`, `PYTHONPATH`, +## `GODOT_AI_DISABLE_TELEMETRY`). A glibc `getenv` racing a concurrent +## `setenv` can return a freed pointer — rare but process-fatal. All env +## reads in this layer therefore go through `env_lookup`: on the MAIN +## thread it reads live and refreshes a mutex-guarded snapshot; off the +## main thread it serves from the snapshot, so no `OS.get_environment` +## runs concurrently with the spawn window's mutations. Callers pre-warm +## every var their workers can touch via `warm_env_snapshot` (plugin +## `_enter_tree` and the dock's phase-1 refresh prep, both main-thread, +## both before any worker starts). +static var _env_snapshot := {} +static var _env_snapshot_mutex := Mutex.new() + +## Every var this layer and its sibling consumers (`_base.gd` +## `config_file_override_details`, `config_home_override_details`, `_cli_finder.gd` lookups, +## `client_configurator.gd` mode/trace reads) can touch off-main. +## Descriptor-declared config-file/config-home env names are passed as extras +## by the warm callers. +const _BASE_ENV_VARS: Array[String] = [ + "HOME", + "USERPROFILE", + "XDG_CONFIG_HOME", + "APPDATA", + "LOCALAPPDATA", + "SHELL", + "ProgramFiles", + "GODOT_AI_MODE", + "GODOT_AI_STARTUP_TRACE", + ## #804 (#752 adoption): _find_venv_python reads this via env_lookup on + ## the dock's worker path; without pre-warming, a set override reads as + ## empty there and is silently ignored — the exact misconfiguration the + ## push_warning in client_configurator.gd exists to surface. + "GODOT_AI_VENV_PYTHON", +] + + +## Thread-safe env read (#691). Main thread: live read + snapshot refresh. +## Worker thread: snapshot only, so it can never race a main-thread +## setenv/unsetenv. A worker read of a never-warmed var returns "" — the +## same value an unset var reads as — never a live OS.get_environment, +## which would reintroduce the race for exactly the vars nobody thought +## to warm. Missing warm-up degrades resolution; it must not touch the +## process-global environment off-main. +static func env_lookup(name: String) -> String: + if OS.get_thread_caller_id() == OS.get_main_thread_id(): + var live := OS.get_environment(name) + _env_snapshot_mutex.lock() + _env_snapshot[name] = live + _env_snapshot_mutex.unlock() + return live + _env_snapshot_mutex.lock() + var cached: Variant = _env_snapshot.get(name, null) + _env_snapshot_mutex.unlock() + if cached != null: + return str(cached) + return "" + + +## Main-thread pre-warm so subsequent worker reads never touch the real +## environment. Idempotent; safe to call before every worker dispatch. +static func warm_env_snapshot(extra_vars: PackedStringArray = PackedStringArray()) -> void: + for var_name in _BASE_ENV_VARS: + env_lookup(var_name) + for var_name in extra_vars: + if not String(var_name).is_empty(): + env_lookup(String(var_name)) + + +## Pick the right entry from a {"darwin": ..., "windows": ..., "linux": ...} map. +static func resolve(template_map: Dictionary) -> String: + var key := platform_key(template_map) + if key.is_empty(): + return "" + var template: String = template_map[key] + return expand(template) + + +## Return the platform-specific key present in a descriptor map. `unix` is a +## shorthand for macOS and Linux. Public so descriptors can use the same +## platform selection for ordered path-candidate arrays as for one path. +static func platform_key(template_map: Dictionary) -> String: + var key := _os_key() + if template_map.has(key): + return key + if (key == "darwin" or key == "linux") and template_map.has("unix"): + return "unix" + return "" + + +## Expand one path template into zero or more concrete paths. A single `*` is +## allowed inside one DIRECTORY segment (for example `Packages/Claude_*`). The +## wildcard is resolved by enumerating that segment's parent; the remaining +## suffix may name a file that does not exist yet, which lets callers derive a +## deterministic create target for a fresh packaged-app install. +## +## Multiple wildcards fail closed and return no candidates. A wildcard final +## segment may identify an installation directory for `detect_paths`. Returned +## paths are sorted for deterministic tests and diagnostics; callers still +## reject ambiguous config groups rather than picking one. +static func expand_path_candidates(template: String) -> PackedStringArray: + var expanded := expand(template) + if expanded.is_empty(): + return PackedStringArray() + var star := expanded.find("*") + if star < 0: + return PackedStringArray([expanded]) + if expanded.find("*", star + 1) >= 0: + return PackedStringArray() + + var slash_before := maxi(expanded.rfind("/", star), expanded.rfind("\\", star)) + var forward_after := expanded.find("/", star) + var backward_after := expanded.find("\\", star) + var slash_after := forward_after + if slash_after < 0 or (backward_after >= 0 and backward_after < slash_after): + slash_after = backward_after + if slash_before < 0: + return PackedStringArray() + + var parent := expanded.substr(0, slash_before) + var pattern := ( + expanded.substr(slash_before + 1) + if slash_after < 0 + else expanded.substr(slash_before + 1, slash_after - slash_before - 1) + ) + var suffix := "" if slash_after < 0 else expanded.substr(slash_after + 1) + var pattern_star := pattern.find("*") + if pattern_star < 0: + return PackedStringArray() + var prefix := pattern.substr(0, pattern_star) + var ending := pattern.substr(pattern_star + 1) + var dir := DirAccess.open(parent) + if dir == null: + return PackedStringArray() + + var matches := PackedStringArray() + for child in dir.get_directories(): + if _wildcard_segment_matches(String(child), prefix, ending): + var matched_path := parent.path_join(String(child)) + matches.append(matched_path if suffix.is_empty() else matched_path.path_join(suffix)) + matches.sort() + return matches + + +## Substitute env vars and ~ in a single template string. +## +## A token that cannot be resolved — the var is unset and no home-derived +## fallback applies, or a dock worker's env snapshot was never warmed with it — +## is LEFT IN PLACE rather than replaced with "". Substituting "" is what turns +## `$USERPROFILE/godot` into `/godot`: a root-relative path that +## `is_absolute_path()` accepts, so every fail-closed guard downstream waves it +## through and the caller reads or writes a directory the user never named. +## `$USERPROFILE` is the easy repro (unset off Windows, and the only one of +## these vars with no fallback), but `$HOME`/`$XDG_CONFIG_HOME`/`$APPDATA`/ +## `$LOCALAPPDATA` reach the same state whenever `_home()` is empty, which the +## missing-warm-up degradation above makes reachable on a worker thread. +## +## The surviving token keeps the result non-absolute, so those guards catch it, +## and the unexpanded path they report still shows what failed to resolve. +## `~` is left alone for the same reason: collapsing `~/godot` to the relative +## `godot` aims it at the editor's own working directory. +static func expand(template: String) -> String: + if template.is_empty(): + return "" + var out := template + if out.begins_with("~/") or out == "~": + var home := _home() + if not home.is_empty(): + out = home if out == "~" else home.path_join(out.substr(2)) + # $HOME, $APPDATA, $LOCALAPPDATA, $USERPROFILE, $XDG_CONFIG_HOME + for var_name in ["XDG_CONFIG_HOME", "LOCALAPPDATA", "USERPROFILE", "APPDATA", "HOME"]: + var token := "$%s" % var_name + if out.find(token) < 0: + continue + var value := env_lookup(var_name) + if value.is_empty(): + value = _home_fallback(var_name) + if value.is_empty(): + continue + out = out.replace(token, value) + return out + + +## Home-derived default for a var the environment does not define. Returns "" +## when home itself is unresolvable so `expand` leaves the token alone: rooting +## these at an empty home yields a RELATIVE path, not an absent one — +## `"".path_join(".config")` is `.config`, which reads against the editor's +## working directory rather than the user's config dir. `USERPROFILE` has no +## fallback (it is the thing `_home()` itself falls back to). +static func _home_fallback(var_name: String) -> String: + var home := _home() + if home.is_empty(): + return "" + match var_name: + "XDG_CONFIG_HOME": + return home.path_join(".config") + "APPDATA": + return home.path_join("AppData/Roaming") + "LOCALAPPDATA": + return home.path_join("AppData/Local") + "HOME": + return home + return "" + + +static func _os_key() -> String: + match OS.get_name(): + "macOS": + return "darwin" + "Windows": + return "windows" + _: + return "linux" + + +static func _wildcard_segment_matches(value: String, prefix: String, ending: String) -> bool: + # Prefix/suffix tests alone allow the two fixed portions to overlap inside a + # too-short value. Glob semantics require room for both portions even when + # `*` matches an empty string. + if value.length() < prefix.length() + ending.length(): + return false + if OS.get_name() == "Windows": + return value.to_lower().begins_with(prefix.to_lower()) and value.to_lower().ends_with(ending.to_lower()) + return value.begins_with(prefix) and value.ends_with(ending) + + +static func _home() -> String: + var h := env_lookup("HOME") + if h.is_empty(): + h = env_lookup("USERPROFILE") + return h diff --git a/addons/godot_ai/clients/_path_template.gd.uid b/addons/godot_ai/clients/_path_template.gd.uid new file mode 100644 index 0000000..f2403d7 --- /dev/null +++ b/addons/godot_ai/clients/_path_template.gd.uid @@ -0,0 +1 @@ +uid://5pd418va35ms diff --git a/addons/godot_ai/clients/_registry.gd b/addons/godot_ai/clients/_registry.gd new file mode 100644 index 0000000..f61f667 --- /dev/null +++ b/addons/godot_ai/clients/_registry.gd @@ -0,0 +1,156 @@ +@tool +class_name McpClientRegistry +extends RefCounted + +## Central enumeration of every supported MCP client. Adding a new client +## means: drop a file in clients/, then append one path below. +## +## Paths, not preloads (#736): a preload array pulled all client descriptor +## scripts into the boot-time compile closure of everything that preloads +## this registry (plugin.gd via client_configurator.gd and mcp_dock.gd), +## stalling "Initializing plugins" on every editor boot. Descriptors are +## only needed when the dock refreshes client statuses or a client_* +## command runs, so they load lazily on first registry access. + +const _CLIENT_SCRIPT_PATHS := [ + "res://addons/godot_ai/clients/claude_code.gd", + "res://addons/godot_ai/clients/claude_desktop.gd", + "res://addons/godot_ai/clients/codex.gd", + "res://addons/godot_ai/clients/grok.gd", + "res://addons/godot_ai/clients/antigravity.gd", + "res://addons/godot_ai/clients/cursor.gd", + "res://addons/godot_ai/clients/windsurf.gd", + "res://addons/godot_ai/clients/vscode.gd", + "res://addons/godot_ai/clients/vscode_insiders.gd", + "res://addons/godot_ai/clients/zed.gd", + "res://addons/godot_ai/clients/gemini_cli.gd", + "res://addons/godot_ai/clients/cline.gd", + "res://addons/godot_ai/clients/kilo_code.gd", + "res://addons/godot_ai/clients/roo_code.gd", + "res://addons/godot_ai/clients/zoo_code.gd", + "res://addons/godot_ai/clients/kiro.gd", + "res://addons/godot_ai/clients/trae.gd", + "res://addons/godot_ai/clients/cherry_studio.gd", + "res://addons/godot_ai/clients/opencode.gd", + "res://addons/godot_ai/clients/qwen_code.gd", + "res://addons/godot_ai/clients/kimi_code.gd", + "res://addons/godot_ai/clients/hermes.gd", + "res://addons/godot_ai/clients/pi.gd", + "res://addons/godot_ai/clients/deepseek_harness.gd", +] + +static var _instances: Array[McpClient] = [] +static var _by_id: Dictionary = {} +## First registry access can come from the dock's client-status refresh +## worker thread while the main thread hits it via a client_* command — +## serialize the one-time load so a racing thread can never observe a +## half-built registry. load() itself is thread-safe via ResourceLoader. +static var _load_mutex := Mutex.new() +## True when even a fresh rebuild yields instances missing base-schema +## fields — the deep stale-script state after an in-session self-update +## (#850; docs/releasing.md release-shape rules). Only an editor restart +## heals it; callers surface RESTART_TO_FINISH_UPDATE instead of erroring +## per client. Never reset within a session: rebuilding again cannot help, +## it would only repeat the load work and warning on every dock sweep. +static var _stale_session := false + +const RESTART_TO_FINISH_UPDATE := ( + "Godot AI was updated in this editor session. Restart the editor to finish the update." +) + + +static func all() -> Array[McpClient]: + _ensure_loaded() + return _instances + + +static func get_by_id(id: String) -> McpClient: + _ensure_loaded() + return _by_id.get(id, null) + + +static func ids() -> PackedStringArray: + var out := PackedStringArray() + for c in all(): + out.append(c.id) + return out + + +static func has_id(id: String) -> bool: + _ensure_loaded() + return _by_id.has(id) + + +## True when this editor session is running a self-update whose script +## reloads left descriptor state unusable. Client operations short-circuit +## with RESTART_TO_FINISH_UPDATE rather than spamming per-field errors. +static func stale_session_detected() -> bool: + _ensure_loaded() + return _stale_session + + +## An instance is coherent when fields added to the CURRENT McpClient schema +## read back with their declared types. After an in-session self-update, +## hot-patched or pre-update instances answer Nil for vars the update added +## (#850: `config_path_candidates` and +## `config_file_env` read as Nil, crashing platform_key / String()). The +## reflected `get()` avoids typed-access errors on such instances. +static func _instance_is_coherent(inst: Object) -> bool: + if inst == null: + return false + return ( + inst.get("config_path_candidates") is Dictionary + and inst.get("config_file_env") is String + and inst.get("path_template") is Dictionary + and inst.get("server_key_path_aliases") is Array + and inst.get("config_merge_path_templates") is Dictionary + and inst.get("config_merge_project_paths") is PackedStringArray + ) + + +static func _cache_is_coherent() -> bool: + return not _instances.is_empty() and _instance_is_coherent(_instances[0]) + + +static func _ensure_loaded() -> void: + if _stale_session: + return + if _cache_is_coherent(): + return + _load_mutex.lock() + ## Re-check under the lock: another thread may have rebuilt (or concluded + ## staleness) while this one waited. + if not _stale_session and not _cache_is_coherent(): + ## Covers both the first load and the post-self-update rebuild: this + ## registry file can survive an update unchanged, so its statics keep + ## serving pre-update instances to freshly reloaded callers. A rebuild + ## instantiates from the reloaded descriptor scripts, which repairs + ## every case except a stale base Script object itself. + _load() + if not _instances.is_empty() and not _cache_is_coherent(): + _stale_session = true + push_warning("MCP | %s" % RESTART_TO_FINISH_UPDATE) + _load_mutex.unlock() + + +static func _load() -> void: + ## Build into locals and publish whole containers last, so the lock-free + ## fast path in _ensure_loaded can never see a partially-filled registry. + var instances: Array[McpClient] = [] + var by_id: Dictionary = {} + for path in _CLIENT_SCRIPT_PATHS: + var script := load(path) as GDScript + if script == null: + push_warning("MCP | failed to load client descriptor %s" % path) + continue + var inst: McpClient = script.new() + if inst.id.is_empty(): + push_warning("MCP | client descriptor %s has empty id" % path) + continue + if by_id.has(inst.id): + push_warning("MCP | duplicate client id: %s" % inst.id) + continue + instances.append(inst) + by_id[inst.id] = inst + _by_id = by_id + _instances = instances diff --git a/addons/godot_ai/clients/_registry.gd.uid b/addons/godot_ai/clients/_registry.gd.uid new file mode 100644 index 0000000..57edcf7 --- /dev/null +++ b/addons/godot_ai/clients/_registry.gd.uid @@ -0,0 +1 @@ +uid://bxougoq8xwg1 diff --git a/addons/godot_ai/clients/_toml_strategy.gd b/addons/godot_ai/clients/_toml_strategy.gd new file mode 100644 index 0000000..a929dbd --- /dev/null +++ b/addons/godot_ai/clients/_toml_strategy.gd @@ -0,0 +1,730 @@ +@tool +class_name McpTomlStrategy +extends RefCounted + +## TOML upsert for URL entries and client-owned command entries. +## +## This remains deliberately smaller than a general TOML parser, but the +## parts that affect migration are semantic: assignments retain their whole +## value span (including multiline arrays/strings), and command/args status +## verification decodes TOML strings and arrays rather than comparing text. + + +static func configure( + client: McpClient, + _server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty(): + return {"status": "error", "message": "Could not resolve config path for %s" % client.display_name} + + var seed_path := str(resolution.get("seed_path", "")) + var read_path := seed_path if not FileAccess.file_exists(path) and not seed_path.is_empty() else path + var read := _read_or_init(read_path) + if not read["ok"]: + return {"status": "error", "message": "Refusing to overwrite %s: %s. Fix or move the file, then re-run Configure." % [read_path, read["error"]]} + + var rendered := render_body(client, server_url, launch) + if not bool(rendered.get("ok", false)): + return {"status": "error", "message": str(rendered.get("error", "Could not build the TOML entry."))} + + var lines: Array[String] = _split_lines(String(read["data"])) + var body: Array[String] = rendered["lines"] + var pinned_keys: Dictionary = rendered["pinned_keys"] + var initial_keys: Dictionary = rendered["initial_keys"] + var removed_keys: Dictionary = rendered["removed_keys"] + + var section := _find_section(lines, _all_headers(client)) + var header := _primary_header(client) + var new_lines: Array[String] = [header] + + if section.is_empty(): + new_lines.append_array(body) + var output_fresh: Array[String] = [] + output_fresh.append_array(lines) + if not output_fresh.is_empty() and not output_fresh[-1].strip_edges().is_empty(): + output_fresh.append("") + output_fresh.append_array(new_lines) + if not McpAtomicWrite.write(path, "\n".join(output_fresh)): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": McpClient.configured_message(client, server_url)} + + var old_items := _value_items(lines, int(section["start"]) + 1, int(section["end"])) + var old_by_key := {} + for item in old_items: + var old_key := str(item.get("key", "")) + if not old_key.is_empty() and not old_by_key.has(old_key): + old_by_key[old_key] = item + + var body_items := _value_items(body, 0, body.size()) + var emitted_keys := {} + for item in body_items: + var key := str(item.get("key", "")) + if key.is_empty(): + new_lines.append_array(item["lines"]) + continue + emitted_keys[key] = true + if initial_keys.has(key) and old_by_key.has(key): + new_lines.append_array(old_by_key[key]["lines"]) + else: + ## Pinned keys always use the freshly rendered span. A generated key + ## that is neither pinned nor initial is also rendered deterministically. + new_lines.append_array(item["lines"]) + + ## Carry unknown/user-owned assignments and standalone comments verbatim. + ## Whole item spans prevent multiline arrays/strings from being truncated. + for item in old_items: + var key := str(item.get("key", "")) + if not key.is_empty(): + if emitted_keys.has(key) or pinned_keys.has(key) or removed_keys.has(key): + continue + new_lines.append_array(item["lines"]) + continue + var item_lines: Array = item.get("lines", []) + for line in item_lines: + if not str(line).strip_edges().is_empty(): + new_lines.append(str(line)) + + var output: Array[String] = [] + output.append_array(_slice(lines, 0, int(section["start"]))) + output.append_array(new_lines) + output.append_array(_slice(lines, int(section["end"]), lines.size())) + output = _rewrite_legacy_descendant_headers(output, client) + + if not McpAtomicWrite.write(path, "\n".join(output)): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": McpClient.configured_message(client, server_url)} + + +static func check_status( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> McpClient.Status: + return check_status_details(client, server_name, server_url, launch).get("status", McpClient.Status.NOT_CONFIGURED) + + +static func check_status_details( + client: McpClient, + _server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": McpClient.Status.ERROR, "error_msg": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + var read := _read_or_init(path) + if not read["ok"]: + return {"status": McpClient.Status.ERROR, "error_msg": String(read["error"])} + var lines: Array[String] = _split_lines(String(read["data"])) + var section := _find_section(lines, _all_headers(client)) + if section.is_empty(): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + + var items := _value_items(lines, int(section["start"]) + 1, int(section["end"])) + var by_key := {} + for item in items: + var key := str(item.get("key", "")) + if not key.is_empty() and not by_key.has(key): + by_key[key] = item + + if client.command_shape != McpClient.CommandShape.NONE: + if not bool(launch.get("ok", false)): + return { + "status": McpClient.Status.ERROR, + "error_msg": str(launch.get("error", "No compatible attach launcher was found.")), + } + for legacy_key in client.command_legacy_keys: + if by_key.has(String(legacy_key)): + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + if not by_key.has("command") or not by_key.has("args"): + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + var command_value := _decode_toml_string(_item_value(by_key["command"])) + var args_value := _decode_toml_string_array(_item_value(by_key["args"])) + if not bool(command_value.get("ok", false)) or not bool(args_value.get("ok", false)): + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + if str(command_value.get("value", "")) != str(launch.get("command", "")): + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + if not _string_arrays_equal(args_value.get("value", []), launch.get("args", [])): + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + if not client.command_transport_key.is_empty(): + var transport_key := client.command_transport_key + if not by_key.has(transport_key): + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + var decoded_transport := _decode_toml_scalar(_item_value(by_key[transport_key])) + if not bool(decoded_transport.get("ok", false)) or decoded_transport.get("value") != client.command_transport_value: + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + return {"status": McpClient.Status.CONFIGURED, "error_msg": ""} + + if not by_key.has("url"): + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + var url_value := _decode_toml_string(_item_value(by_key["url"])) + if not bool(url_value.get("ok", false)) or str(url_value.get("value", "")) != server_url: + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + return {"status": McpClient.Status.CONFIGURED, "error_msg": ""} + + +static func remove(client: McpClient, _server_name: String) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": "ok", "message": "Not configured"} + var read := _read_or_init(path) + if not read["ok"]: + return {"status": "error", "message": "Refusing to rewrite %s: %s." % [path, read["error"]]} + var lines: Array[String] = _split_lines(String(read["data"])) + var headers := _all_headers(client) + var subtable_prefixes := _subtable_prefixes(headers) + + var output: Array[String] = [] + var i := 0 + while i < lines.size(): + if _matches_any_header(lines[i], headers) or _matches_subtable_prefix(lines[i], subtable_prefixes): + i += 1 + while i < lines.size() and not _is_any_section_header(lines[i]): + i += 1 + continue + output.append(lines[i]) + i += 1 + + if not McpAtomicWrite.write(path, "\n".join(output)): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + + +## Substitute `{url}` in every legacy URL body-template line. +static func format_body(template: PackedStringArray, server_url: String) -> PackedStringArray: + var out := PackedStringArray() + for line in template: + out.append(String(line).replace("{url}", server_url)) + return out + + +## Encode a TOML basic string. This is intentionally public for the +## cross-language fixture test that parses the rendered sample with tomllib. +static func encode_basic_string(value: String) -> String: + return '"%s"' % value.replace("\\", "\\\\").replace('"', '\\"').replace("\b", "\\b").replace("\t", "\\t").replace("\n", "\\n").replace("\f", "\\f").replace("\r", "\\r") + + +## Multi-line string-array encoding used by command-shape entries. +static func encode_string_array(values: Variant) -> Array[String]: + var out: Array[String] = ["["] + for value in values: + out.append(" %s," % encode_basic_string(str(value))) + out.append("]") + return out + + +static func render_body(client: McpClient, server_url: String, launch: Dictionary) -> Dictionary: + if client.command_shape == McpClient.CommandShape.NONE: + if client.toml_body_template.is_empty(): + return {"ok": false, "error": "%s descriptor missing toml_body_template" % client.display_name} + var legacy_body := format_body(client.toml_body_template, server_url) + var legacy_lines: Array[String] = [] + var pinned := {} + var initial := {} + for idx in range(legacy_body.size()): + legacy_lines.append(String(legacy_body[idx])) + var key := _line_key(String(client.toml_body_template[idx])) + if key.is_empty(): + continue + if String(client.toml_body_template[idx]).contains("{url}"): + pinned[key] = true + else: + initial[key] = true + return { + "ok": true, + "lines": legacy_lines, + "pinned_keys": pinned, + "initial_keys": initial, + "removed_keys": {}, + } + + if client.command_shape != McpClient.CommandShape.COMMAND_ARRAY: + return {"ok": false, "error": "%s uses a command shape not supported by TOML yet" % client.display_name} + if not bool(launch.get("ok", false)): + return {"ok": false, "error": str(launch.get("error", "No compatible attach launcher was found."))} + + var command_lines: Array[String] = [ + "command = %s" % encode_basic_string(str(launch.get("command", ""))), + ] + command_lines.append_array(_encode_assignment("args", launch.get("args", []))) + + var pinned_keys := {"command": true, "args": true} + if not client.command_transport_key.is_empty(): + var encoded_transport := _encode_scalar(client.command_transport_value) + if encoded_transport.is_empty(): + return { + "ok": false, + "error": "Unsupported TOML transport `%s` for %s" % [ + client.command_transport_key, client.display_name, + ], + } + command_lines.append("%s = %s" % [client.command_transport_key, encoded_transport]) + pinned_keys[client.command_transport_key] = true + + var initial_keys := {} + for key in client.command_initial_fields: + var encoded := _encode_assignment(str(key), client.command_initial_fields[key]) + if encoded.is_empty(): + return {"ok": false, "error": "Unsupported TOML default `%s` for %s" % [key, client.display_name]} + command_lines.append_array(encoded) + initial_keys[str(key)] = true + + var removed_keys := {} + for key in client.command_legacy_keys: + removed_keys[String(key)] = true + return { + "ok": true, + "lines": command_lines, + "pinned_keys": pinned_keys, + "initial_keys": initial_keys, + "removed_keys": removed_keys, + } + + +static func _encode_assignment(key: String, value: Variant) -> Array[String]: + if value is Array or value is PackedStringArray: + var lines := encode_string_array(value) + lines[0] = "%s = %s" % [key, lines[0]] + return lines + var encoded := _encode_scalar(value) + var lines: Array[String] = [] + if not encoded.is_empty(): + lines.append("%s = %s" % [key, encoded]) + return lines + + +static func _encode_scalar(value: Variant) -> String: + if value is String: + return encode_basic_string(value) + if value is bool: + return "true" if value else "false" + if value is int or value is float: + return str(value) + return "" + + +# --- span-aware merge helpers ------------------------------------------- + +static func _value_items(lines: Array[String], from: int, to: int) -> Array[Dictionary]: + var out: Array[Dictionary] = [] + var i := from + while i < to: + var key := _line_key(lines[i]) + if key.is_empty(): + out.append({"key": "", "lines": [lines[i]]}) + i += 1 + continue + var end := _value_span_end(lines, i, to) + out.append({"key": key, "lines": _slice(lines, i, end)}) + i = end + return out + + +static func _value_span_end(lines: Array[String], start: int, limit: int) -> int: + var state := {"quote": "", "square": 0, "curly": 0, "escaped": false} + for i in range(start, limit): + var begin := 0 + if i == start: + var eq := _assignment_equal(lines[i]) + begin = eq + 1 if eq >= 0 else 0 + _scan_toml_value_line(lines[i], begin, state) + if str(state["quote"]).is_empty() and int(state["square"]) == 0 and int(state["curly"]) == 0: + return i + 1 + return limit + + +static func _scan_toml_value_line(line: String, begin: int, state: Dictionary) -> void: + var i := begin + while i < line.length(): + var quote := str(state["quote"]) + if quote == '"""' or quote == "'''": + if line.substr(i).begins_with(quote): + state["quote"] = "" + i += 3 + continue + if quote == '"""' and line.unicode_at(i) == 92 and not bool(state["escaped"]): + state["escaped"] = true + i += 1 + continue + state["escaped"] = false + i += 1 + continue + if quote == '"' or quote == "'": + var c := line.unicode_at(i) + if quote == '"' and c == 92 and not bool(state["escaped"]): + state["escaped"] = true + i += 1 + continue + if c == quote.unicode_at(0) and not bool(state["escaped"]): + state["quote"] = "" + state["escaped"] = false + i += 1 + continue + + if line.substr(i).begins_with('"""'): + state["quote"] = '"""' + i += 3 + continue + if line.substr(i).begins_with("'''"): + state["quote"] = "'''" + i += 3 + continue + var c := line.unicode_at(i) + if c == 34: + state["quote"] = '"' + elif c == 39: + state["quote"] = "'" + elif c == 35: + break + elif c == 91: + state["square"] = int(state["square"]) + 1 + elif c == 93: + state["square"] = maxi(0, int(state["square"]) - 1) + elif c == 123: + state["curly"] = int(state["curly"]) + 1 + elif c == 125: + state["curly"] = maxi(0, int(state["curly"]) - 1) + i += 1 + + +static func _line_key(line: String) -> String: + var eq := _assignment_equal(line) + if eq <= 0: + return "" + return line.substr(0, eq).strip_edges() + + +static func _assignment_equal(line: String) -> int: + var quote := 0 + var escaped := false + for i in range(line.length()): + var c := line.unicode_at(i) + if quote != 0: + if quote == 34 and c == 92 and not escaped: + escaped = true + continue + if c == quote and not escaped: + quote = 0 + escaped = false + continue + if c == 34 or c == 39: + quote = c + elif c == 35: + return -1 + elif c == 61: + return i + return -1 + + +# --- semantic value decoding -------------------------------------------- + +static func _item_value(item: Dictionary) -> String: + var item_lines: Array = item.get("lines", []) + if item_lines.is_empty(): + return "" + var first := str(item_lines[0]) + var eq := _assignment_equal(first) + if eq < 0: + return "" + var parts: Array[String] = [first.substr(eq + 1)] + for i in range(1, item_lines.size()): + parts.append(str(item_lines[i])) + return "\n".join(parts) + + +static func _decode_toml_scalar(raw: String) -> Dictionary: + var cleaned := _without_comments(raw).strip_edges() + if cleaned == "true": + return {"ok": true, "value": true} + if cleaned == "false": + return {"ok": true, "value": false} + var string_value := _decode_toml_string(cleaned) + if bool(string_value.get("ok", false)): + return string_value + if cleaned.is_valid_int(): + return {"ok": true, "value": cleaned.to_int()} + if cleaned.is_valid_float(): + return {"ok": true, "value": cleaned.to_float()} + return {"ok": false} + + +static func _decode_toml_string(raw: String) -> Dictionary: + var cleaned := _without_comments(raw).strip_edges() + if cleaned.length() >= 2 and cleaned.begins_with("'") and cleaned.ends_with("'"): + return {"ok": true, "value": cleaned.substr(1, cleaned.length() - 2)} + if cleaned.length() < 2 or not cleaned.begins_with('"') or not cleaned.ends_with('"'): + return {"ok": false} + var parsed: Variant = JSON.parse_string(cleaned) + if parsed is String: + return {"ok": true, "value": parsed} + return {"ok": false} + + +static func _decode_toml_string_array(raw: String) -> Dictionary: + var cleaned := _without_comments(raw).strip_edges() + if not cleaned.begins_with("["): + return {"ok": false} + var i := 1 + var values: Array[String] = [] + while true: + i = _skip_space(cleaned, i) + if i >= cleaned.length(): + return {"ok": false} + if cleaned.unicode_at(i) == 93: + i = _skip_space(cleaned, i + 1) + return {"ok": i == cleaned.length(), "value": values} + var parsed := _parse_string_at(cleaned, i) + if not bool(parsed.get("ok", false)): + return {"ok": false} + values.append(str(parsed.get("value", ""))) + i = _skip_space(cleaned, int(parsed.get("next", i))) + if i >= cleaned.length(): + return {"ok": false} + var c := cleaned.unicode_at(i) + if c == 44: + i += 1 + continue + if c == 93: + continue + return {"ok": false} + return {"ok": false} # Unreachable; keeps GDScript's return analysis explicit. + + +static func _parse_string_at(text: String, start: int) -> Dictionary: + if start >= text.length(): + return {"ok": false} + var quote := text.unicode_at(start) + if quote != 34 and quote != 39: + return {"ok": false} + var i := start + 1 + var escaped := false + while i < text.length(): + var c := text.unicode_at(i) + if quote == 34 and c == 92 and not escaped: + escaped = true + i += 1 + continue + if c == quote and not escaped: + var raw := text.substr(start, i - start + 1) + if quote == 39: + return {"ok": true, "value": raw.substr(1, raw.length() - 2), "next": i + 1} + var parsed: Variant = JSON.parse_string(raw) + if parsed is String: + return {"ok": true, "value": parsed, "next": i + 1} + return {"ok": false} + escaped = false + i += 1 + return {"ok": false} + + +static func _without_comments(raw: String) -> String: + var out: Array[String] = [] + for line in raw.split("\n"): + var quote := 0 + var escaped := false + var kept := "" + for i in range(line.length()): + var c := line.unicode_at(i) + if quote != 0: + kept += line.substr(i, 1) + if quote == 34 and c == 92 and not escaped: + escaped = true + continue + if c == quote and not escaped: + quote = 0 + escaped = false + continue + if c == 34 or c == 39: + quote = c + kept += line.substr(i, 1) + elif c == 35: + break + else: + kept += line.substr(i, 1) + out.append(kept) + return "\n".join(out) + + +static func _skip_space(text: String, start: int) -> int: + var i := start + while i < text.length() and text.substr(i, 1) in [" ", "\t", "\r", "\n"]: + i += 1 + return i + + +static func _string_arrays_equal(left: Variant, right: Variant) -> bool: + if not (left is Array or left is PackedStringArray): + return false + if not (right is Array or right is PackedStringArray): + return false + if left.size() != right.size(): + return false + for i in range(left.size()): + if str(left[i]) != str(right[i]): + return false + return true + + +# --- file / section helpers --------------------------------------------- + +static func _read_or_init(path: String) -> Dictionary: + if not FileAccess.file_exists(path): + return {"ok": true, "data": ""} + var f := FileAccess.open(path, FileAccess.READ) + if f == null: + var err := FileAccess.get_open_error() + return {"ok": false, "error": "could not open for reading (error %d)" % err} + var text := f.get_as_text() + f.close() + return {"ok": true, "data": text} + + +static func _split_lines(content: String) -> Array[String]: + var out: Array[String] = [] + for line in content.split("\n"): + out.append(line) + return out + + +static func _slice(lines: Array[String], from: int, to: int) -> Array[String]: + var out: Array[String] = [] + for i in range(from, to): + out.append(lines[i]) + return out + + +static func _primary_header(client: McpClient) -> String: + var parts := client.toml_section_path + if parts.size() < 2: + return "[%s]" % ".".join(parts) + var section := ".".join(McpClient._packed_slice(parts, 0, parts.size() - 1)) + var name := parts[parts.size() - 1] + return "[%s.\"%s\"]" % [section, name] + + +static func _all_headers(client: McpClient) -> Array[String]: + var primary := _primary_header(client) + var out: Array[String] = [primary] + var bare := _bare_key_header(client) + if not bare.is_empty() and bare != primary: + out.append(bare) + for legacy in client.toml_legacy_section_aliases: + out.append("[%s]" % legacy) + return out + + +static func _bare_key_header(client: McpClient) -> String: + var parts := client.toml_section_path + if parts.is_empty(): + return "" + for part in parts: + if not _is_bare_key(String(part)): + return "" + return "[%s]" % ".".join(parts) + + +static func _is_bare_key(value: String) -> bool: + if value.is_empty(): + return false + for i in range(value.length()): + var c := value.unicode_at(i) + var alpha := (c >= 65 and c <= 90) or (c >= 97 and c <= 122) + var digit := c >= 48 and c <= 57 + if not (alpha or digit or c == 45 or c == 95): + return false + return true + + +static func _subtable_prefixes(headers: Array[String]) -> Array[String]: + var out: Array[String] = [] + for header in headers: + if header.length() > 2 and header.ends_with("]"): + out.append(header.substr(0, header.length() - 1) + ".") + return out + + +static func _matches_subtable_prefix(line: String, prefixes: Array[String]) -> bool: + var trimmed := line.strip_edges() + for prefix in prefixes: + if not trimmed.begins_with(prefix): + continue + var rest := trimmed.substr(prefix.length()) + var bracket := rest.find("]") + if bracket < 0: + continue + var remainder := rest.substr(bracket + 1).strip_edges() + if remainder.is_empty() or remainder.begins_with("#"): + return true + return false + + +static func _matches_any_header(line: String, headers: Array[String]) -> bool: + var trimmed := line.strip_edges() + for header in headers: + if not trimmed.begins_with(header): + continue + var remainder := trimmed.substr(header.length()).strip_edges() + if remainder.is_empty() or remainder.begins_with("#"): + return true + return false + + +static func _find_section(lines: Array[String], headers: Array[String]) -> Dictionary: + for i in range(lines.size()): + if _matches_any_header(lines[i], headers): + var end := lines.size() + for j in range(i + 1, lines.size()): + if _is_any_section_header(lines[j]): + end = j + break + return {"start": i, "end": end} + return {} + + +static func _is_any_section_header(line: String) -> bool: + var trimmed := line.strip_edges() + if not trimmed.begins_with("["): + return false + var bracket := trimmed.find("]") + if bracket < 0: + return false + var remainder := trimmed.substr(bracket + 1).strip_edges() + return remainder.is_empty() or remainder.begins_with("#") + + +static func _rewrite_legacy_descendant_headers( + lines: Array[String], client: McpClient +) -> Array[String]: + if client.toml_legacy_section_aliases.is_empty(): + return lines + var primary := _primary_header(client) + var primary_prefix := primary.substr(0, primary.length() - 1) + "." + var out: Array[String] = [] + for line in lines: + var rewritten := line + var trimmed := line.strip_edges() + var indent_length := line.find("[") + var indent := line.substr(0, indent_length) if indent_length >= 0 else "" + for alias in client.toml_legacy_section_aliases: + var legacy_prefix := "[%s." % String(alias) + if trimmed.begins_with(legacy_prefix): + rewritten = indent + primary_prefix + trimmed.substr(legacy_prefix.length()) + break + out.append(rewritten) + return out diff --git a/addons/godot_ai/clients/_toml_strategy.gd.uid b/addons/godot_ai/clients/_toml_strategy.gd.uid new file mode 100644 index 0000000..723cb79 --- /dev/null +++ b/addons/godot_ai/clients/_toml_strategy.gd.uid @@ -0,0 +1 @@ +uid://cwdvxgn0aurqv diff --git a/addons/godot_ai/clients/_yaml_strategy.gd b/addons/godot_ai/clients/_yaml_strategy.gd new file mode 100644 index 0000000..0efd515 --- /dev/null +++ b/addons/godot_ai/clients/_yaml_strategy.gd @@ -0,0 +1,549 @@ +@tool +class_name McpYamlStrategy +extends RefCounted + +## Minimal YAML upsert for Hermes Agent MCP config. +## +## Hermes reads MCP servers from ~/.hermes/config.yaml under the +## `mcp_servers` key (snake_case, YAML). HTTP entries are transport-inferred: +## just `url` (plus optional `headers`), no `type` field. We only parse the +## `mcp_servers` block and re-emit it; other top-level keys in the user's +## config.yaml are preserved verbatim by round-tripping the raw lines around +## that block. No general YAML parser — Godot has none in stdlib, and Hermes +## only needs this one shape. See issue #640. + +const INDENT := " " # YAML forbids tab indentation; match the 2-space style of ~/.hermes/config.yaml + + +static func configure( + client: McpClient, + server_name: String, + server_url: String, + launch: Dictionary = {}, +) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty(): + return {"status": "error", "message": "Could not resolve config path for %s on this OS" % client.display_name} + ## Fail closed before touching the file — same contract as JSON/TOML. + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": "error", "message": launch_error} + + var seed_path := str(resolution.get("seed_path", "")) + var read_path := seed_path if not FileAccess.file_exists(path) and not seed_path.is_empty() else path + var read := _read(read_path) + if not read["ok"]: + return {"status": "error", "message": "Refusing to overwrite %s: %s. Fix or move the file, then re-run Configure." % [read_path, read["error"]]} + + var text: String = read["data"] + var block := _extract_block(text) + var entries: Dictionary = block["entries"] + + # Preserve existing entry's user-mutable keys; force the transport keys. + var existing: Dictionary = entries.get(server_name, {}) + var new_entry := build_entry(client, server_url, existing, launch) + entries[server_name] = new_entry + + var out := _assemble(text, block["prefix_lines"], entries, block["suffix_lines"]) + if not McpAtomicWrite.write(path, out): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": McpClient.configured_message(client, server_url)} + + +static func check_status( + client: McpClient, server_name: String, server_url: String, launch: Dictionary = {} +) -> McpClient.Status: + return check_status_details(client, server_name, server_url, launch)["status"] + + +## Same contract as the JSON/TOML strategies (#711): {status, error_msg}. +## An existing-but-unreadable config is ERROR with the diagnostic — not +## NOT_CONFIGURED — so the dock row can tell "no config" from "config the +## editor can't read" instead of offering a Configure that would fail. +static func check_status_details( + client: McpClient, server_name: String, server_url: String, launch: Dictionary = {} +) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": McpClient.Status.ERROR, "error_msg": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + var read := _read(path) + if not read["ok"]: + return { + "status": McpClient.Status.ERROR, + "error_msg": "Cannot read %s: %s" % [path, read["error"]], + } + var block := _extract_block(String(read["data"])) + var entries: Dictionary = block["entries"] + if not entries.has(server_name): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + var entry: Variant = entries[server_name] + if not (entry is Dictionary): + return {"status": McpClient.Status.NOT_CONFIGURED, "error_msg": ""} + ## An entry exists but no verified launcher does — mirror JSON/TOML: this + ## is an environment ERROR, not entry drift. + var launch_error := command_launch_error(client, launch) + if not launch_error.is_empty(): + return {"status": McpClient.Status.ERROR, "error_msg": launch_error} + if verify_entry(client, entry, server_url, launch): + return {"status": McpClient.Status.CONFIGURED, "error_msg": ""} + return {"status": McpClient.Status.CONFIGURED_MISMATCH, "error_msg": ""} + + +static func remove(client: McpClient, server_name: String) -> Dictionary: + var resolution := client.resolved_config_path_details() + var path := str(resolution.get("path", "")) + var path_error := str(resolution.get("error", "")) + if not path_error.is_empty(): + return {"status": "error", "message": path_error} + if path.is_empty() or not FileAccess.file_exists(path): + return {"status": "ok", "message": "Not configured"} + var read := _read(path) + if not read["ok"]: + return {"status": "error", "message": "Refusing to rewrite %s: %s." % [path, read["error"]]} + var text: String = read["data"] + var block := _extract_block(text) + var entries: Dictionary = block["entries"] + if not entries.has(server_name): + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + entries.erase(server_name) + var out := _assemble(text, block["prefix_lines"], entries, block["suffix_lines"]) + if not McpAtomicWrite.write(path, out): + return {"status": "error", "message": "Cannot write to %s" % path} + return {"status": "ok", "message": "%s configuration removed" % client.display_name} + + +## Build the entry dict written under mcp_servers[server_name]. +## +## URL mode (`CommandShape.NONE`): Hermes HTTP entries are transport-inferred +## — { url: } plus whatever user-mutable keys (headers, enabled, tools, +## ...) the existing entry carries. Stdio-bridge keys are the one exception +## (see _STDIO_BRIDGE_KEYS). No `type` field. +## +## Command mode (`CommandShape.FLAT`, #838): flat `command` + `args` keys, +## transport inferred the same way — which is exactly why the descriptor's +## `command_legacy_keys` (url, headers) must be scrubbed: a Hermes entry with +## both a url and a command picks the wrong transport. User keys survive. +static func build_entry( + client: McpClient, + server_url: String, + existing: Variant = null, + launch: Dictionary = {}, +) -> Dictionary: + if client.command_shape == McpClient.CommandShape.FLAT: + var command_entry: Dictionary = (existing as Dictionary).duplicate(true) if existing is Dictionary else {} + command_entry["command"] = str(launch.get("command", "")) + command_entry["args"] = _array_copy(launch.get("args", [])) + if not client.command_transport_key.is_empty(): + command_entry[client.command_transport_key] = client.command_transport_value + for key in client.command_initial_fields: + if not command_entry.has(key): + command_entry[key] = client.command_initial_fields[key] + for key in client.command_legacy_keys: + command_entry.erase(String(key)) + return command_entry + if client.command_shape != McpClient.CommandShape.NONE: + ## Every production caller checks command_launch_error first. Keep this + ## builder defensive too so a future unsupported shape cannot silently + ## degrade into a flat YAML entry. + return {} + var entry: Dictionary = {} + if existing is Dictionary: + ## User-mutable keys (headers, enabled, tools, ...) survive a + ## reconfigure — the same preservation contract the JSON strategy's + ## entry_initial_fields split implements. Only the stdio-bridge keys + ## are scrubbed (see _STDIO_BRIDGE_KEYS), then the url is repointed. + entry = (existing as Dictionary).duplicate(true) + for stale_key in _STDIO_BRIDGE_KEYS: + entry.erase(stale_key) + entry[client.entry_url_field] = server_url + return entry + + +## Keys a prior stdio-bridge entry (e.g. `command: uvx mcp-proxy`) may carry. +## These must NOT survive a URL reconfigure: a Hermes entry with both a url +## and a command picks the wrong transport. +const _STDIO_BRIDGE_KEYS := ["command", "args", "env"] + + +## Empty string when this client's launch requirements are satisfied. +## Mirrors `McpJsonStrategy.command_launch_error`; YAML supports FLAT only. +static func command_launch_error(client: McpClient, launch: Dictionary) -> String: + if client.command_shape == McpClient.CommandShape.NONE: + return "" + if client.command_shape != McpClient.CommandShape.FLAT: + return "%s uses a command shape not supported by YAML yet" % client.display_name + if not bool(launch.get("ok", false)): + return str(launch.get("error", "No compatible attach launcher was found.")) + return "" + + +## Verify a stored entry matches. +## +## URL mode: Hermes entries have no transport type pin, so verification is: +## url matches. Extra keys (headers, enabled, tools) are user-mutable and +## intentionally NOT checked (mirrors json entry_initial_fields). +## +## Command mode: every launch-affecting value must match exactly and legacy +## URL-transport keys must be gone — their presence is migration drift. +static func verify_entry( + client: McpClient, + entry: Dictionary, + server_url: String, + launch: Dictionary = {}, +) -> bool: + if client.command_shape != McpClient.CommandShape.NONE: + if client.command_shape != McpClient.CommandShape.FLAT or not bool(launch.get("ok", false)): + return false + for key in client.command_legacy_keys: + if entry.has(String(key)): + return false + if entry.get("command") != launch.get("command"): + return false + if not _arrays_equal(entry.get("args", null), launch.get("args", null)): + return false + if not client.command_transport_key.is_empty(): + if entry.get(client.command_transport_key, null) != client.command_transport_value: + return false + return true + return entry.get(client.entry_url_field, "") == server_url + + +static func _array_copy(value: Variant) -> Array: + if value is Array: + return (value as Array).duplicate(true) + if value is PackedStringArray: + return McpClient._array_from_packed(value) + return [] + + +static func _arrays_equal(left: Variant, right: Variant) -> bool: + if not (left is Array or left is PackedStringArray): + return false + if not (right is Array or right is PackedStringArray): + return false + var left_array := _array_copy(left) + var right_array := _array_copy(right) + if left_array.size() != right_array.size(): + return false + for i in range(left_array.size()): + if left_array[i] != right_array[i]: + return false + return true + + +# --- YAML block handling (scoped to mcp_servers) ------------------------- + +## Parse the file into three regions: +## prefix_lines — everything before `mcp_servers:` (may be empty) +## entries — the map of server_name -> {url, ...} under mcp_servers +## suffix_lines — everything after the mcp_servers block (may be empty) +## This lets us rewrite only the mcp_servers block and keep the rest of the +## user's config.yaml byte-for-byte intact. +static func _extract_block(text: String) -> Dictionary: + ## allow_empty must stay true: dropping empty splits would silently strip + ## the user's blank lines from the preserved prefix/suffix regions on + ## every rewrite. The parse loops below already skip blank lines. + var lines := text.split("\n") + var prefix: PackedStringArray = [] + var entries: Dictionary = {} + var suffix: PackedStringArray = [] + var header_idx := -1 + for i in range(lines.size()): + if lines[i].strip_edges().begins_with("mcp_servers:"): + header_idx = i + break + if header_idx < 0: + # No mcp_servers yet — whole file is prefix; block will be appended. + prefix = lines.duplicate() + return {"prefix_lines": prefix, "entries": entries, "suffix_lines": [], "header_idx": -1} + + for i in range(0, header_idx): + prefix.append(lines[i]) + + # Determine the indent of the first entry so we can tell sibling + # entries (same indent) apart from nested keys (deeper indent) and + # parent-level keys (less indent). All server entries under + # `mcp_servers:` share one indent level; breaking on 0-indent alone + # mis-nests 2-space-indented siblings under the first entry. + var entry_indent := -1 + var probe := header_idx + 1 + while probe < lines.size() and _is_blank_or_comment(lines[probe]): + probe += 1 + if probe < lines.size(): + entry_indent = _indent_of(lines[probe]) + + # Empty block guard: the first nonblank line after the header must sit + # DEEPER than the header itself to be an entry. At or above the header's + # indent it is a sibling/parent key — parsing it as an entry would + # swallow the user's next top-level key and re-emit it nested under + # mcp_servers, corrupting the file. + if probe < lines.size() and entry_indent <= _indent_of(lines[header_idx]): + for j in range(header_idx + 1, lines.size()): + suffix.append(lines[j]) + return {"prefix_lines": prefix, "entries": entries, "suffix_lines": suffix, "header_idx": header_idx} + + var i := header_idx + 1 + while i < lines.size(): + var raw := lines[i] + ## Comment-only lines inside the block are skipped like blanks — + ## treating one as an entry header would re-emit it as a bogus + ## `# comment:` server on rewrite. (Comments INSIDE the rewritten + ## block are consequently dropped; comments outside the block live + ## in prefix/suffix and survive verbatim.) + if _is_blank_or_comment(raw): + i += 1 + continue + # Stop at any line indented less than a sibling entry (parent key + # or a new top-level section), or at the header's own level. + if _indent_of(raw) < entry_indent: + break + var entry := _parse_entry(raw, lines, i, entry_indent) + if not entry["name"].is_empty(): + entries[entry["name"]] = entry["data"] + i = entry["next_idx"] + + for j in range(i, lines.size()): + suffix.append(lines[j]) + + return {"prefix_lines": prefix, "entries": entries, "suffix_lines": suffix, "header_idx": header_idx} + + +## Parse one ` name:` entry starting at `lines[start]`. Consumes all deeper- +## indented sublines (url, headers, etc.) and returns the next sibling index. +static func _parse_entry(raw: String, lines: PackedStringArray, start: int, entry_indent: int) -> Dictionary: + var name := raw.strip_edges().trim_suffix(":").strip_edges() + var data: Dictionary = {} + var i := start + 1 + while i < lines.size(): + var l := lines[i] + ## Comments inside an entry (e.g. ` # auth for CI`) would parse + ## as a `# auth for CI` key — skip them like blanks. + if _is_blank_or_comment(l): + i += 1 + continue + # A line at or above the entry's indent is a sibling/parent key. + if _indent_of(l) <= entry_indent: + break + var stripped := l.strip_edges() + var colon := stripped.find(":") + if colon < 0: + i += 1 + continue + var key := stripped.substr(0, colon).strip_edges() + var val := stripped.substr(colon + 1).strip_edges() + if val.is_empty(): + # Nested block (e.g. headers:). Parse as raw sub-dict lines for + # preservation; we don't introspect deeper than url at the top. + var sub := _parse_subblock(lines, i + 1, entry_indent) + data[key] = sub["value"] + i = sub["next_idx"] + else: + data[key] = coerce_scalar(val) + i += 1 + return {"name": name, "data": data, "next_idx": i} + + +## Parse a nested block (e.g. headers:) as a preserved sub-dictionary of +## scalar key/values. Deeper nesting is flattened into scalar strings — fine +## for Hermes' known shape (headers are flat key: value). +static func _parse_subblock(lines: PackedStringArray, start: int, entry_indent: int) -> Dictionary: + var sub: Dictionary = {} + var i := start + while i < lines.size(): + var l := lines[i] + if _is_blank_or_comment(l): + i += 1 + continue + # A line at or above the parent entry's indent ends the nested block. + if _indent_of(l) <= entry_indent: + break + var stripped := l.strip_edges() + var colon := stripped.find(":") + if colon < 0: + i += 1 + continue + var key := stripped.substr(0, colon).strip_edges() + var val := stripped.substr(colon + 1).strip_edges() + if val.is_empty(): + i += 1 + continue + sub[key] = coerce_scalar(val) + i += 1 + return {"value": sub, "next_idx": i} + + +## Reassemble the full file text from prefix + a freshly built mcp_servers +## block + suffix. If the block didn't exist before, it is appended. +static func _assemble(_text: String, prefix: PackedStringArray, entries: Dictionary, suffix: PackedStringArray) -> String: + var out: PackedStringArray = [] + for l in prefix: + out.append(l) + # Trim trailing blank lines from prefix so we don't stack double blanks. + while out.size() > 0 and out[out.size() - 1].strip_edges().is_empty(): + out.remove_at(out.size() - 1) + + if not _text.contains("mcp_servers:"): + # File existed but had no mcp_servers block — append it. + if out.size() > 0: + out.append("") + out.append("mcp_servers:") + for name in entries: + out.append_array(_emit_entry(name, entries[name])) + else: + out.append("mcp_servers:") + for name in entries: + out.append_array(_emit_entry(name, entries[name])) + + # Suffix: keep as-is. + for l in suffix: + out.append(l) + return "\n".join(out) + + +## Public rendering seam for the dock's manual-instruction text, so the +## pasted YAML matches what Configure would write byte-for-byte. +static func render_entry_lines(name: String, data: Dictionary) -> PackedStringArray: + return _emit_entry(name, data) + + +## Emit one ` name:` entry with its scalar keys (top level only; headers +## sub-dict is re-emitted as nested scalars; arrays — the command entry's +## `args` — are emitted in flow style on one line). +static func _emit_entry(name: String, data: Dictionary) -> PackedStringArray: + var lines: PackedStringArray = [] + lines.append(INDENT + "%s:" % name) + for key in data: + var val = data[key] + if val is Dictionary: + lines.append(INDENT + INDENT + "%s:" % key) + for sk in val: + lines.append(INDENT + INDENT + INDENT + "%s: %s" % [sk, emit_scalar(val[sk])]) + elif val is Array or val is PackedStringArray: + lines.append(INDENT + INDENT + "%s: %s" % [key, emit_flow_array(_array_copy(val))]) + else: + lines.append(INDENT + INDENT + "%s: %s" % [key, emit_scalar(val)]) + return lines + + +## Flow-style sequence with every item double-quoted. JSON string quoting is +## valid YAML double-quote style (shared escape set), so the same encoding +## both writes the file and — via JSON.parse_string in `coerce_scalar` — +## reads it back for verification. Shared with `McpDshStrategy` for the +## DeepSeek Harness patch-list `args` lines. +static func emit_flow_array(values: Array) -> String: + var parts: Array[String] = [] + for v in values: + parts.append(JSON.stringify(str(v))) + return "[%s]" % ", ".join(parts) + + +static func emit_scalar(v: Variant) -> String: + match typeof(v): + TYPE_BOOL: + return "true" if bool(v) else "false" + TYPE_INT: + return str(int(v)) + TYPE_FLOAT: + return str(float(v)) + _: + return emit_string_scalar(str(v)) + + +## Plain YAML scalars cannot safely carry ": ", " #", quotes, flow +## indicators, or leading indicator characters — a Windows launcher path with +## spaces would silently corrupt the entry. Quote exactly when needed so +## existing plain values (urls, bools-as-strings) keep their current +## byte-shape on rewrite. Backslashes are quoted too: a Windows path parses +## either way, but quoting makes the written shape unambiguous for any +## consumer. Shared with `McpDshStrategy` for DeepSeek Harness patch entries. +static func emit_string_scalar(s: String) -> String: + if s.is_empty(): + return "\"\"" + var needs_quote := s.begins_with(" ") or s.ends_with(" ") + if not needs_quote: + for needle in [": ", " #", "\"", "'", "\n", "\t", "\\", "{", "}", "[", "]", ","]: + if s.contains(needle): + needs_quote = true + break + if not needs_quote: + for prefix in ["#", "-", "?", "&", "*", "!", "|", ">", "%", "@", "`"]: + if s.begins_with(prefix): + needs_quote = true + break + return JSON.stringify(s) if needs_quote else s + + +## Blank and comment-only lines carry no structure — every scan loop skips +## them the same way so a `# comment` can never be mistaken for an entry +## header or a key/value line. +static func _is_blank_or_comment(line: String) -> bool: + var stripped := line.strip_edges() + return stripped.is_empty() or stripped.begins_with("#") + + +## Returns the leading-whitespace indent width of a line (spaces + tabs +## counted as 1 each). Used to distinguish sibling entries (same indent) +## from nested keys (deeper indent) and parent-level keys (less indent). +static func _indent_of(line: String) -> int: + var n := 0 + while n < line.length() and (line[n] == " " or line[n] == "\t"): + n += 1 + return n + + +## Minimal scalar coercion for parsed YAML values. Quotes are stripped; +## bare true/false/numbers are typed; double-quoted flow sequences (the +## command entry's `args`) parse back into an Array. Good enough for Hermes' +## url/headers/command/args. A hand-edited args in block style or with +## unquoted items doesn't JSON-parse — it stays a raw string, compares +## unequal, and surfaces as CONFIGURED_MISMATCH, which Reconfigure +## normalizes back to the flow form. Public: the dsh strategy parses its +## patch-list scalars with the same rules, so both YAML dialects share one +## coercion (#867 review). +static func coerce_scalar(s: String) -> Variant: + var t := s.strip_edges() + if t.begins_with("[") and t.ends_with("]"): + var parsed_array: Variant = JSON.parse_string(t) + if parsed_array is Array: + return parsed_array + return t + if t.begins_with("\"") and t.ends_with("\""): + var parsed_string: Variant = JSON.parse_string(t) + if parsed_string is String: + return parsed_string + return t.substr(1, t.length() - 2) + if t.begins_with("'") and t.ends_with("'"): + return t.substr(1, t.length() - 2) + if t == "true": + return true + if t == "false": + return false + if t.is_valid_int(): + return t.to_int() + if t.is_valid_float(): + return t.to_float() + return t + + +## Returns {"ok": true, "data": String} when the file is absent or readable, +## and {"ok": false, "error": String} when unreadable. Callers must NOT fall +## back to an empty string on the error path — doing so blows away the user's +## other config.yaml entries on the next write. +static func _read(path: String) -> Dictionary: + if not FileAccess.file_exists(path): + return {"ok": true, "data": ""} + var f := FileAccess.open(path, FileAccess.READ) + if f == null: + var err := FileAccess.get_open_error() + return {"ok": false, "error": "could not open for reading (%s)" % error_string(err)} + var t := f.get_as_text() + f.close() + return {"ok": true, "data": t} diff --git a/addons/godot_ai/clients/_yaml_strategy.gd.uid b/addons/godot_ai/clients/_yaml_strategy.gd.uid new file mode 100644 index 0000000..d8adce8 --- /dev/null +++ b/addons/godot_ai/clients/_yaml_strategy.gd.uid @@ -0,0 +1 @@ +uid://cfnw4oe71ra1l diff --git a/addons/godot_ai/clients/antigravity.gd b/addons/godot_ai/clients/antigravity.gd new file mode 100644 index 0000000..a707735 --- /dev/null +++ b/addons/godot_ai/clients/antigravity.gd @@ -0,0 +1,39 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "antigravity" + display_name = "Antigravity" + config_type = "json" + ## Antigravity moved its shared MCP config from `~/.gemini/antigravity/` + ## to `~/.gemini/config/` (IDE + CLI now read the same file there); the + ## old path is left in `detect_paths` below so an existing install is + ## still recognized, but new/updated entries write to the current path. + path_template = { + "unix": "~/.gemini/config/mcp_config.json", + "windows": "$USERPROFILE/.gemini/config/mcp_config.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + entry_url_field = "serverUrl" + ## `disabled` is user-state (they may have flipped the entry off in the + ## UI); seeded on first Configure but preserved across reconfigure. + entry_initial_fields = {"disabled": false} + ## Attach migration (#838). Antigravity stdio entries are flat + ## command/args/env with no type discriminator — transport is inferred + ## from `command` vs `serverUrl` presence (antigravity.google/docs/mcp), + ## so the legacy `serverUrl` must not survive next to a command. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["serverUrl"]) + command_initial_fields = {"disabled": false} + command_user_fields = PackedStringArray(["disabled", "disabledTools", "authProviderType", "env"]) + command_supports_url_fallback = true + ## Antigravity's spawner hangs stdio tool calls when the entry launches a + ## GUI-subsystem pythonw.exe (#863), and it hides child console windows + ## itself, so the visible-terminal problem the bootstrap solves (#827) + ## never applies. Write the plain console launcher on Windows. + needs_consoleless_launcher = false + detect_paths = PackedStringArray(path_template.values() + [ + "~/.gemini/antigravity/mcp_config.json", + "$USERPROFILE/.gemini/antigravity/mcp_config.json", + ]) diff --git a/addons/godot_ai/clients/antigravity.gd.uid b/addons/godot_ai/clients/antigravity.gd.uid new file mode 100644 index 0000000..0721a2f --- /dev/null +++ b/addons/godot_ai/clients/antigravity.gd.uid @@ -0,0 +1 @@ +uid://b4l1g0apa2hch diff --git a/addons/godot_ai/clients/cherry_studio.gd b/addons/godot_ai/clients/cherry_studio.gd new file mode 100644 index 0000000..873b9fe --- /dev/null +++ b/addons/godot_ai/clients/cherry_studio.gd @@ -0,0 +1,18 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "cherry_studio" + display_name = "Cherry Studio" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/CherryStudio/mcp_servers.json", + "windows": "$APPDATA/CherryStudio/mcp_servers.json", + "linux": "$XDG_CONFIG_HOME/CherryStudio/mcp_servers.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + entry_extra_fields = {"type": "streamableHttp"} + ## `isActive` is user-state (they may have toggled the server off in the UI). + ## Seed on first Configure but preserve across reconfigure. + entry_initial_fields = {"isActive": true} diff --git a/addons/godot_ai/clients/cherry_studio.gd.uid b/addons/godot_ai/clients/cherry_studio.gd.uid new file mode 100644 index 0000000..7ada8cd --- /dev/null +++ b/addons/godot_ai/clients/cherry_studio.gd.uid @@ -0,0 +1 @@ +uid://dwbuykxvbv5f7 diff --git a/addons/godot_ai/clients/claude_code.gd b/addons/godot_ai/clients/claude_code.gd new file mode 100644 index 0000000..d0378b6 --- /dev/null +++ b/addons/godot_ai/clients/claude_code.gd @@ -0,0 +1,84 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "claude_code" + display_name = "Claude Code" + config_type = "cli" + cli_names = PackedStringArray(["claude", "claude.exe"] if OS.get_name() == "Windows" else ["claude"]) + ## Stdio registration through the client-owned `godot-ai attach` bridge + ## (#838). `--` stops claude's own flag parsing so the attach argv passes + ## through verbatim; stdio is the CLI's default transport. Scope comes from + ## the `godot_ai/mcp_client_scope` EditorSetting via the `{scope}` token; it + ## defaults to `user` — the same ~/.claude.json the pre-attach HTTP entry + ## lived in — and can be set to `project` to write /.mcp.json so the + ## server is not loaded in every unrelated workspace. + cli_register_template = PackedStringArray( + ["mcp", "add", "--scope", "{scope}", "{name}", "--", "{command}", "{args...}"] + ) + ## Explicit scope: an unscoped `mcp remove` deletes from whichever scope + ## matches first, so the flag keeps each removal aimed at one known place. + ## Note what that does and does not protect (#877): the dock's **Remove** + ## button runs this once, at the selected scope only. **Configure** runs it + ## once per scope in `CLIENT_SCOPES` before registering, so a Configure at + ## any setting does delete a `godot-ai` entry from /.mcp.json if one is + ## there — see the cwd caveat below for which directory that actually is. + cli_unregister_template = PackedStringArray(["mcp", "remove", "--scope", "{scope}", "{name}"]) + ## Scope caveat: `--scope project` resolves `.mcp.json` against the + ## *spawned CLI's* working directory, which is whatever the editor process + ## inherited at launch — not necessarily `res://`. Godot has no API to set + ## a child's cwd (`OS.execute_with_pipe` takes none), so this is an + ## accepted limitation rather than something the descriptor can pin. It is + ## self-consistent: `cli_status_args` runs from the same cwd, so the + ## read-back finds whatever the register wrote (see + ## `_scope_diverges_from_json_fallback` in client_configurator.gd). + cli_status_args = PackedStringArray(["mcp", "list"]) + ## `mcp list` prints the resolved entry for the cwd without saying which + ## scope won, so it cannot tell "registered at project scope" from "an old + ## user-scope entry is shadowing an empty project scope". `mcp get` prints + ## both the command and a `Scope: …` line, in the same single subprocess, + ## so scope-token clients probe with it instead (#872). Verified against + ## claude 2.1.241, which prints one of: + ## Scope: User config (available in all your projects) + ## Scope: Project config (shared via .mcp.json) + ## Scope: Local config (private to you in this project) + ## and exits 1 with "No MCP server named …" when the entry is absent. + cli_scope_status_template = PackedStringArray(["mcp", "get", "{name}"]) + ## #463: JSON fallback for when the `claude` binary isn't on PATH — e.g. + ## Claude Code installed only as a VS Code / Cursor extension. The CLI is + ## still preferred for Configure whenever it resolves; this is what gets + ## written otherwise. `claude mcp add --scope user -- ` + ## produces exactly this shape under `mcpServers` in ~/.claude.json + ## (verified live against claude CLI in an isolated CLAUDE_CONFIG_DIR): + ## "godot-ai": { "type": "stdio", "command": "", "args": [...], "env": {} } + ## The fallback writer omits the empty `env`; the verifier accepts both. + ## Status reads this file only while the selected scope is still `user` — + ## it is the CLI's own store for that scope, and file reads give exact + ## launch-drift detection that `mcp list` stdout scanning cannot. At + ## `project`/`local` the entry is somewhere `path_template` cannot see, so + ## `_scope_diverges_from_json_fallback` (client_configurator.gd) routes + ## status to `cli_scope_status_template` instead and this file is not read. + path_template = {"unix": "~/.claude.json", "windows": "~/.claude.json"} + server_key_path = PackedStringArray(["mcpServers"]) + ## URL-mode shape, used only for the manual-instruction fallback text — + ## `claude mcp add --scope --transport http` writes {type: http, url}, + ## where is whatever `godot_ai/mcp_client_scope` resolves to. + entry_extra_fields = {"type": "http"} + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "type" + command_transport_value = "stdio" + ## Legacy HTTP entries carried a `url`; Claude Code rejects an entry mixing + ## url with command fields, and the stale `type: "http"` is repinned to + ## "stdio" by the transport key above. + command_legacy_keys = PackedStringArray(["url"]) + command_user_fields = PackedStringArray(["env"]) + command_supports_url_fallback = true + ## Documented: $CLAUDE_CONFIG_DIR relocates Claude Code's config home, + ## including .claude.json ($CLAUDE_CONFIG_DIR/.claude.json). The preferred + ## CLI path needs no help — the spawned `claude` binary inherits the + ## editor's environment and resolves the dir itself — but the JSON + ## fallback above would otherwise write ~/.claude.json that a relocated + ## install never reads (#617). + config_home_env = "CLAUDE_CONFIG_DIR" + config_home_env_subpath = ".claude.json" diff --git a/addons/godot_ai/clients/claude_code.gd.uid b/addons/godot_ai/clients/claude_code.gd.uid new file mode 100644 index 0000000..3d3335f --- /dev/null +++ b/addons/godot_ai/clients/claude_code.gd.uid @@ -0,0 +1 @@ +uid://cp1u1hdpa6f8d diff --git a/addons/godot_ai/clients/claude_desktop.gd b/addons/godot_ai/clients/claude_desktop.gd new file mode 100644 index 0000000..c1aa9bb --- /dev/null +++ b/addons/godot_ai/clients/claude_desktop.gd @@ -0,0 +1,38 @@ +@tool +extends McpClient + +## Claude Desktop's mcpServers entries launch a local stdio process. The +## client-owned `godot-ai attach` bridge keeps that stdio session stable while +## adopting or starting the shared HTTP backend as Godot editors come and go. + + +func _init() -> void: + id = "claude_desktop" + display_name = "Claude Desktop" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Claude/claude_desktop_config.json", + "windows": "$APPDATA/Claude/claude_desktop_config.json", + "linux": "$XDG_CONFIG_HOME/Claude/claude_desktop_config.json", + } + ## Store-installed Claude runs inside MSIX AppData virtualization. Godot is + ## outside that container, so `%APPDATA%` names a different physical file + ## once Claude has created its private copy. A unique Store package root is + ## authoritative even before the config leaf exists: create the private file + ## directly so a later copy-on-write cannot hide an entry written to roaming. + ## With no Store package, use the conventional roaming path. The wildcard + ## avoids coupling to the publisher-hash suffix. + config_path_candidates = { + "windows": [ + "$LOCALAPPDATA/Packages/Claude_*/LocalCache/Roaming/Claude/claude_desktop_config.json", + "$APPDATA/Claude/claude_desktop_config.json", + ], + } + detect_paths = PackedStringArray([ + "$LOCALAPPDATA/Packages/Claude_*", + ]) + server_key_path = PackedStringArray(["mcpServers"]) + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url"]) + command_env_legacy_keys = PackedStringArray(["UV_LINK_MODE"]) + command_user_fields = PackedStringArray(["env", "disabled"]) diff --git a/addons/godot_ai/clients/claude_desktop.gd.uid b/addons/godot_ai/clients/claude_desktop.gd.uid new file mode 100644 index 0000000..9759a1a --- /dev/null +++ b/addons/godot_ai/clients/claude_desktop.gd.uid @@ -0,0 +1 @@ +uid://bilntn5n8oqe3 diff --git a/addons/godot_ai/clients/cline.gd b/addons/godot_ai/clients/cline.gd new file mode 100644 index 0000000..2a1f025 --- /dev/null +++ b/addons/godot_ai/clients/cline.gd @@ -0,0 +1,43 @@ +@tool +extends McpClient + +## Cline is a VS Code extension. Its MCP settings live in VS Code's +## globalStorage under the extension id `saoudrizwan.claude-dev`. + + +func _init() -> void: + id = "cline" + display_name = "Cline" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json", + "windows": "$APPDATA/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json", + "linux": "$XDG_CONFIG_HOME/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + ## Cline (like Roo) defaults a typeless entry to SSE transport, which + ## returns HTTP 400 against our streamable-http endpoint on `/mcp`. Pin + ## the type explicitly. Cline's schema uses "streamableHttp" (camelCase, + ## see src/services/mcp/schemas.ts in the cline repo) — distinct from + ## Roo's "streamable-http" string. Parallel to the Roo fix in #190. + entry_extra_fields = {"type": "streamableHttp"} + ## `disabled` and `autoApprove` are user-state (they may have flipped the + ## entry off, or auto-approved specific tools). Seed on first Configure + ## but preserve across reconfigure — see `entry_initial_fields` in `_base.gd`. + entry_initial_fields = {"disabled": false, "autoApprove": []} + ## Attach migration (#838). Cline stdio entries are flat command/args/env; + ## its schema accepts `type: "stdio"` and normalizes typeless command + ## entries to it (apps/vscode/src/services/mcp/schemas.ts), so pin the + ## type — that also repins the legacy "streamableHttp" value instead of + ## letting it survive the deep-copy and misroute the transport. + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "type" + command_transport_value = "stdio" + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_initial_fields = {"disabled": false, "autoApprove": []} + command_user_fields = PackedStringArray([ + "disabled", "autoApprove", "timeout", "oauth", "metadata", + "remoteConfigured", "env", "cwd", + ]) + command_timeout_fields = PackedStringArray(["timeout"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/cline.gd.uid b/addons/godot_ai/clients/cline.gd.uid new file mode 100644 index 0000000..95e20f1 --- /dev/null +++ b/addons/godot_ai/clients/cline.gd.uid @@ -0,0 +1 @@ +uid://d36nywn2nkgts diff --git a/addons/godot_ai/clients/codex.gd b/addons/godot_ai/clients/codex.gd new file mode 100644 index 0000000..b8231bc --- /dev/null +++ b/addons/godot_ai/clients/codex.gd @@ -0,0 +1,45 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "codex" + display_name = "Codex" + config_type = "toml" + path_template = {"unix": "~/.codex/config.toml", "windows": "$USERPROFILE/.codex/config.toml"} + ## Documented: when $CODEX_HOME is set, Codex reads config.toml directly + ## from it instead of ~/.codex (#617). + config_home_env = "CODEX_HOME" + config_home_env_subpath = "config.toml" + toml_section_path = PackedStringArray(["mcp_servers", "godot-ai"]) + # Older Codex builds used the unquoted form with underscore-substituted ids. + toml_legacy_section_aliases = PackedStringArray(["mcp_servers.godot_ai"]) + command_shape = McpClient.CommandShape.COMMAND_ARRAY + command_supports_url_fallback = true + command_legacy_keys = PackedStringArray(["url"]) + ## Initial-only: users may disable the entry or tune either timeout and + ## Configure preserves that choice. Codex currently defaults to 10s for + ## startup and 60s per tool; test_run legitimately has a 300s server + ## budget, so the generated config leaves transport margin at the client. + command_initial_fields = { + "enabled": true, + "startup_timeout_sec": 60, + "tool_timeout_sec": 360, + } + command_timeout_fields = PackedStringArray([ + "startup_timeout_sec", + "tool_timeout_sec", + ]) + command_user_fields = PackedStringArray([ + "enabled", + "required", + "startup_timeout_sec", + "tool_timeout_sec", + "enabled_tools", + "disabled_tools", + "default_tools_approval_mode", + "env", + "env_vars", + "cwd", + ]) + detect_paths = PackedStringArray(path_template.values()) diff --git a/addons/godot_ai/clients/codex.gd.uid b/addons/godot_ai/clients/codex.gd.uid new file mode 100644 index 0000000..1e1c3ae --- /dev/null +++ b/addons/godot_ai/clients/codex.gd.uid @@ -0,0 +1 @@ +uid://hdlwcfdr8mdk diff --git a/addons/godot_ai/clients/cursor.gd b/addons/godot_ai/clients/cursor.gd new file mode 100644 index 0000000..e4fe98d --- /dev/null +++ b/addons/godot_ai/clients/cursor.gd @@ -0,0 +1,21 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "cursor" + display_name = "Cursor" + config_type = "json" + path_template = {"unix": "~/.cursor/mcp.json", "windows": "$USERPROFILE/.cursor/mcp.json"} + server_key_path = PackedStringArray(["mcpServers"]) + ## Attach migration (#838). Cursor's stdio entries are flat command/args/env + ## (cursor.com/docs/context/mcp). The docs' reference table documents + ## `type: "stdio"`; pinning it also repins any hand-added `type: "http"` + ## left on the legacy URL entry, which would otherwise survive the + ## deep-copy migration and misroute the transport. + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "type" + command_transport_value = "stdio" + command_legacy_keys = PackedStringArray(["url"]) + command_user_fields = PackedStringArray(["env", "envFile"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/cursor.gd.uid b/addons/godot_ai/clients/cursor.gd.uid new file mode 100644 index 0000000..e0c7ddf --- /dev/null +++ b/addons/godot_ai/clients/cursor.gd.uid @@ -0,0 +1 @@ +uid://bvpbssfanukef diff --git a/addons/godot_ai/clients/deepseek_harness.gd b/addons/godot_ai/clients/deepseek_harness.gd new file mode 100644 index 0000000..b9db2a5 --- /dev/null +++ b/addons/godot_ai/clients/deepseek_harness.gd @@ -0,0 +1,45 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "deepseek_harness" + display_name = "DeepSeek Harness" + ## DeepSeek Harness (dsh) has no `mcp` CLI verb — MCP servers register as + ## `@deepseek-ai/dsh-mcp-client` plugin entries in the HOME patch layer + ## `$DSH_HOME/cordis.patch.yml`, which dsh applies over every profile's + ## own patch layer (the web GUI included). config_type "dsh" routes to + ## `McpDshStrategy`. Verified live against dsh 0.1.0-rc.6: new entries + ## must be `insert` rows; plain rows only override existing bundle ids. + config_type = "dsh" + ## Home patch layer, not a per-profile file: one entry covers the web + ## GUI, headless, tui, and any custom profile. + path_template = { + "unix": "~/.dsh/cordis.patch.yml", + "windows": "~/.dsh/cordis.patch.yml", + } + ## Documented: `$DSH_HOME` relocates the whole harness home, and the + ## loader reads `$DSH_HOME/cordis.patch.yml` (homePatchPath) — same + ## false-success-write class as CODEX_HOME (#617), so the override must + ## be declared. + config_home_env = "DSH_HOME" + config_home_env_subpath = "cordis.patch.yml" + ## Installed detection: the harness home directory itself (dsh GUI and + ## CLI both live there), or the config file once one exists. + detect_paths = PackedStringArray(["~/.dsh"]) + ## Attach migration (#838). The loader entry nests the launch under + ## `config`; the mcp-client plugin requires `transport` next to + ## command/args, and a `url` must never coexist with command fields. + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "transport" + command_transport_value = "stdio" + command_legacy_keys = PackedStringArray(["url"]) + ## Fields the mcp-client plugin documents as user-owned; preserved on + ## reconfigure and never drift-checked. + command_user_fields = PackedStringArray([ + "env", "cwd", "toolCallTimeoutMs", "failOnStartupError", "reconnect", + ]) + command_timeout_fields = PackedStringArray(["toolCallTimeoutMs"]) + ## The bridge accepts `transport: streamable-http` with a `url`, so the + ## manual instructions may offer the HTTP alternative. + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/deepseek_harness.gd.uid b/addons/godot_ai/clients/deepseek_harness.gd.uid new file mode 100644 index 0000000..8cc2ed3 --- /dev/null +++ b/addons/godot_ai/clients/deepseek_harness.gd.uid @@ -0,0 +1 @@ +uid://cw3pghlevtql8 diff --git a/addons/godot_ai/clients/gemini_cli.gd b/addons/godot_ai/clients/gemini_cli.gd new file mode 100644 index 0000000..fda58a3 --- /dev/null +++ b/addons/godot_ai/clients/gemini_cli.gd @@ -0,0 +1,25 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "gemini_cli" + display_name = "Gemini CLI" + config_type = "json" + path_template = { + "unix": "~/.gemini/settings.json", + "windows": "$USERPROFILE/.gemini/settings.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + entry_url_field = "httpUrl" + ## Attach migration (#838). Gemini CLI stdio entries are flat + ## command/args/env(+cwd); the config is one-of `command` | `url` (SSE) | + ## `httpUrl` (docs/tools/mcp-server.md), so BOTH URL keys are legacy next + ## to a command. `trust` bypasses tool confirmations — never seed it. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["httpUrl", "url"]) + command_user_fields = PackedStringArray([ + "timeout", "trust", "includeTools", "excludeTools", "env", "cwd", + ]) + command_timeout_fields = PackedStringArray(["timeout"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/gemini_cli.gd.uid b/addons/godot_ai/clients/gemini_cli.gd.uid new file mode 100644 index 0000000..2d4e85a --- /dev/null +++ b/addons/godot_ai/clients/gemini_cli.gd.uid @@ -0,0 +1 @@ +uid://b8288pxninajy diff --git a/addons/godot_ai/clients/grok.gd b/addons/godot_ai/clients/grok.gd new file mode 100644 index 0000000..7b6710e --- /dev/null +++ b/addons/godot_ai/clients/grok.gd @@ -0,0 +1,35 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "grok" + display_name = "Grok Build" + config_type = "toml" + # Grok Build reads MCP servers from ~/.grok/config.toml + # (https://x.ai / Grok user guide: MCP servers section). + path_template = { + "unix": "~/.grok/config.toml", + "windows": "$USERPROFILE/.grok/config.toml", + } + toml_section_path = PackedStringArray(["mcp_servers", "godot-ai"]) + # Some docs / older notes used an underscore form. + toml_legacy_section_aliases = PackedStringArray(["mcp_servers.godot_ai"]) + ## Attach migration (#838). Grok's stdio sections are flat command/args/env + ## with no type discriminator (docs.x.ai/build/features/mcp-servers); + ## url/headers are the HTTP form and must not survive next to a command. + ## Docs default startup_timeout_sec to 30 — a cold `uvx` install of the + ## pinned package can exceed that, so new entries seed 60 (preserved once + ## the user tunes it). tool_timeout_sec's documented 6000s default already + ## clears test_run's 300s budget, so it is left alone. The old body + ## template's `enabled = true` line was never documented for Grok — it is + ## no longer seeded, and an existing value survives as a user key. + command_shape = McpClient.CommandShape.COMMAND_ARRAY + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_initial_fields = {"startup_timeout_sec": 60} + command_user_fields = PackedStringArray([ + "env", "enabled", "startup_timeout_sec", "tool_timeout_sec", + ]) + command_timeout_fields = PackedStringArray(["startup_timeout_sec", "tool_timeout_sec"]) + command_supports_url_fallback = true + detect_paths = PackedStringArray(path_template.values()) diff --git a/addons/godot_ai/clients/grok.gd.uid b/addons/godot_ai/clients/grok.gd.uid new file mode 100644 index 0000000..f2d12c2 --- /dev/null +++ b/addons/godot_ai/clients/grok.gd.uid @@ -0,0 +1 @@ +uid://ckchsj5s3q1b0 diff --git a/addons/godot_ai/clients/hermes.gd b/addons/godot_ai/clients/hermes.gd new file mode 100644 index 0000000..64a66bb --- /dev/null +++ b/addons/godot_ai/clients/hermes.gd @@ -0,0 +1,46 @@ +@tool +extends McpClient + +func _init() -> void: + id = "hermes" + display_name = "Hermes Agent" + config_type = "yaml" + + # Hermes reads MCP config from ~/.hermes/config.yaml (YAML), NOT mcp.json. + # Verified against the official docs: + # https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp + # Windows: Hermes stores config under $LOCALAPPDATA/hermes (NOT $APPDATA, + # which is Roaming) — confirmed by where the running Hermes process reads. + # NOTE: _path_template.expand() only substitutes $VAR tokens, not %VAR%. + path_template = { + "unix": "~/.hermes/config.yaml", + "windows": "$LOCALAPPDATA/hermes/config.yaml" + } + + # Hermes uses the snake_case `mcp_servers` key (not `mcpServers`). + # PackedStringArray explicitly, matching every other descriptor — an + # untyped Array literal relies on implicit conversion that newer Godot + # builds enforce more strictly (the #722 CI lesson for Array[String]). + server_key_path = PackedStringArray(["mcp_servers"]) + + # HTTP entries use `url` (+ optional `headers`); transport is inferred — + # there is no `type` field in Hermes MCP config. + entry_url_field = "url" + + # No transport pin: Hermes infers streamable-http from the URL. + entry_extra_fields = {} + entry_initial_fields = {} + + ## Attach migration (#838). Hermes stdio entries are flat command/args/env + ## (hermes-agent.nousresearch.com/docs/user-guide/features/mcp), transport + ## inferred exactly like the URL form — which is why `url` and the + ## HTTP-only `headers` must not survive next to a command: an entry with + ## both picks the wrong transport. `enabled`/`tools`/`env` stay user-owned. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_user_fields = PackedStringArray(["enabled", "tools", "env"]) + command_supports_url_fallback = true + + # Hermes is "installed" wherever the config.yaml lives; presence of the + # file is sufficient for the dock's installed badge. + detect_paths = PackedStringArray() diff --git a/addons/godot_ai/clients/hermes.gd.uid b/addons/godot_ai/clients/hermes.gd.uid new file mode 100644 index 0000000..14cabd8 --- /dev/null +++ b/addons/godot_ai/clients/hermes.gd.uid @@ -0,0 +1 @@ +uid://ewmadhrvs5d7 diff --git a/addons/godot_ai/clients/kilo_code.gd b/addons/godot_ai/clients/kilo_code.gd new file mode 100644 index 0000000..4f7b3f7 --- /dev/null +++ b/addons/godot_ai/clients/kilo_code.gd @@ -0,0 +1,38 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "kilo_code" + display_name = "Kilo Code" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json", + "windows": "$APPDATA/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json", + "linux": "$XDG_CONFIG_HOME/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + ## Kilo Code (like Roo) defaults a typeless entry to SSE transport, which + ## returns HTTP 400 against our streamable-http endpoint on `/mcp`. Pin + ## the type explicitly. Parallel to the Roo fix in #190. + entry_extra_fields = {"type": "streamable-http"} + ## `disabled` and `alwaysAllow` are user-state (they may have flipped the + ## entry off, or auto-approved specific tools). Seed on first Configure + ## but preserve across reconfigure — see `entry_initial_fields` in `_base.gd`. + entry_initial_fields = {"disabled": false, "alwaysAllow": []} + ## Attach migration (#838). UNLIKE its Roo siblings the stdio entry must be + ## TYPELESS: Kilo's v7 platform treats this file as a migration source and + ## routes on `type` — any http type value sends the entry down the remote + ## branch where it is dropped for lack of a url, and only a bare + ## command/args/env entry is verified to work in BOTH the legacy extension + ## and the v7 migrator (packages/opencode/src/kilocode/mcp-migrator.ts). + ## `type` therefore joins the legacy keys instead of being repinned. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url", "type", "headers"]) + command_initial_fields = {"disabled": false, "alwaysAllow": []} + command_user_fields = PackedStringArray([ + "disabled", "alwaysAllow", "timeout", "cwd", "watchPaths", + "disabledTools", "env", + ]) + command_timeout_fields = PackedStringArray(["timeout"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/kilo_code.gd.uid b/addons/godot_ai/clients/kilo_code.gd.uid new file mode 100644 index 0000000..3ee5152 --- /dev/null +++ b/addons/godot_ai/clients/kilo_code.gd.uid @@ -0,0 +1 @@ +uid://dc1x77i1cmb6w diff --git a/addons/godot_ai/clients/kimi_code.gd b/addons/godot_ai/clients/kimi_code.gd new file mode 100644 index 0000000..a80fef8 --- /dev/null +++ b/addons/godot_ai/clients/kimi_code.gd @@ -0,0 +1,34 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "kimi_code" + display_name = "Kimi Code" + ## Kimi Code has no `mcp` CLI subcommand (verified against v0.28.1 — + ## `kimi mcp` falls through to the root --help, and the docs at + ## moonshotai.github.io/kimi-code/en/customization/mcp confirm servers are + ## managed via ~/.kimi-code/mcp.json, not a CLI verb). JSON is therefore + ## the only working config method, not a fallback. + config_type = "json" + path_template = {"unix": "~/.kimi-code/mcp.json", "windows": "~/.kimi-code/mcp.json"} + server_key_path = PackedStringArray(["mcpServers"]) + entry_extra_fields = {"transport": "http"} + ## Documented: `$KIMI_CODE_HOME/mcp.json` relocates the config + ## (moonshotai.github.io/kimi-code/en/customization/mcp) — same + ## false-success-write class as CODEX_HOME (#617). + config_home_env = "KIMI_CODE_HOME" + config_home_env_subpath = "mcp.json" + ## Attach migration (#838). Kimi Code stdio entries are flat + ## command/args/env(+cwd): "Entries with a `command` field are stdio + ## servers". `transport` is only defined for SSE-with-url, so the legacy + ## `transport: "http"` must be removed alongside `url`. Timeout fields are + ## camelCase, unlike Codex's snake_case. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url", "transport"]) + command_user_fields = PackedStringArray([ + "enabled", "startupTimeoutMs", "toolTimeoutMs", "enabledTools", + "disabledTools", "env", "cwd", + ]) + command_timeout_fields = PackedStringArray(["startupTimeoutMs", "toolTimeoutMs"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/kimi_code.gd.uid b/addons/godot_ai/clients/kimi_code.gd.uid new file mode 100644 index 0000000..5a05a0e --- /dev/null +++ b/addons/godot_ai/clients/kimi_code.gd.uid @@ -0,0 +1 @@ +uid://d2whd6a5fofhg diff --git a/addons/godot_ai/clients/kiro.gd b/addons/godot_ai/clients/kiro.gd new file mode 100644 index 0000000..c9d4247 --- /dev/null +++ b/addons/godot_ai/clients/kiro.gd @@ -0,0 +1,23 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "kiro" + display_name = "Kiro" + config_type = "json" + path_template = { + "unix": "~/.kiro/settings/mcp.json", + "windows": "$USERPROFILE/.kiro/settings/mcp.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + ## `disabled` is user-state — preserved across reconfigure. + entry_initial_fields = {"disabled": false} + ## Attach migration (#838). Kiro stdio entries are flat command/args/env + ## with no type discriminator (kiro.dev/docs/mcp/configuration). + ## `autoApprove` is user-state, same contract as the URL entry's fields. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url"]) + command_initial_fields = {"disabled": false} + command_user_fields = PackedStringArray(["disabled", "autoApprove", "disabledTools", "env"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/kiro.gd.uid b/addons/godot_ai/clients/kiro.gd.uid new file mode 100644 index 0000000..dde3e87 --- /dev/null +++ b/addons/godot_ai/clients/kiro.gd.uid @@ -0,0 +1 @@ +uid://dqdmd2jw5qen7 diff --git a/addons/godot_ai/clients/opencode.gd b/addons/godot_ai/clients/opencode.gd new file mode 100644 index 0000000..cee555b --- /dev/null +++ b/addons/godot_ai/clients/opencode.gd @@ -0,0 +1,39 @@ +@tool +extends McpClient + +## OpenCode stores MCP servers under `mcp.` (not the typical mcpServers +## map) and uses `type: "remote"` for HTTP servers. + + +func _init() -> void: + id = "opencode" + display_name = "OpenCode" + config_type = "json" + ## `$HOME` on Windows is deliberate: OpenCode reads ~/.config/... on ALL + ## platforms (verified via `opencode debug paths`), and + ## McpPathTemplate._home() falls back to USERPROFILE when HOME is unset — + ## pinned by test_opencode_client_uses_home_config_on_windows. The documented + ## `OPENCODE_CONFIG` override names an exact file and must win over this + ## default for configure, status, remove, and manual instructions. + path_template = { + "unix": "~/.config/opencode/opencode.json", + "windows": "$HOME/.config/opencode/opencode.json", + } + config_file_env = "OPENCODE_CONFIG" + server_key_path = PackedStringArray(["mcp"]) + entry_extra_fields = {"type": "remote"} + ## `enabled` is user-state (they may have toggled the server off). + entry_initial_fields = {"enabled": true} + ## Attach migration (#838). OpenCode local entries carry the launch as ONE + ## argv array — `"command": ["uvx", …]` with no separate args key — plus a + ## schema-REQUIRED `type: "local"` (McpLocalConfig in opencode.ai/config.json; + ## env lives under `environment`, not `env`). The pin rewrites the legacy + ## `type: "remote"` in place; url/headers are remote-only and must go. + command_shape = McpClient.CommandShape.COMMAND_ARRAY + command_transport_key = "type" + command_transport_value = "local" + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_initial_fields = {"enabled": true} + command_user_fields = PackedStringArray(["enabled", "timeout", "environment", "cwd"]) + command_timeout_fields = PackedStringArray(["timeout"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/opencode.gd.uid b/addons/godot_ai/clients/opencode.gd.uid new file mode 100644 index 0000000..dc2ad00 --- /dev/null +++ b/addons/godot_ai/clients/opencode.gd.uid @@ -0,0 +1 @@ +uid://s8n0vfirf2pj diff --git a/addons/godot_ai/clients/pi.gd b/addons/godot_ai/clients/pi.gd new file mode 100644 index 0000000..849fbb4 --- /dev/null +++ b/addons/godot_ai/clients/pi.gd @@ -0,0 +1,63 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "pi" + display_name = "Pi Agent" + config_type = "json" + # pi-codemode-mcp reads MCP server definitions from ~/.pi/agent/mcp.json + # (first merge tier; ~/.pi/agent/.mcp.json, .pi/mcp.json, and + # .mcp.json merge after, project-scope last). Documented at + # github.com/mitsuhiko/pi-codemode-mcp README "Configuration files" + # section. Windows path mirrors antigravity's $USERPROFILE choice so + # the descriptor round-trips on every supported platform. + path_template = { + "unix": "~/.pi/agent/mcp.json", + "windows": "$USERPROFILE/.pi/agent/mcp.json", + } + # Pi merges these files in order; later definitions of the same server win. + # Keep this separate from config_path_candidates, whose entries are alternatives + # rather than merge tiers. + config_merge_path_templates = { + "unix": PackedStringArray([ + "~/.pi/agent/mcp.json", + "~/.pi/agent/.mcp.json", + ]), + "windows": PackedStringArray([ + "$USERPROFILE/.pi/agent/mcp.json", + "$USERPROFILE/.pi/agent/.mcp.json", + ]), + } + config_merge_project_paths = PackedStringArray([".pi/mcp.json", ".mcp.json"]) + server_key_path = PackedStringArray(["mcpServers"]) + # pi-codemode-mcp resolves these with nullish precedence: + # mcpServers ?? mcp-servers ?? servers. Reuse whichever map already exists + # so Configure cannot shadow and deactivate the user's existing servers. + var aliases: Array[PackedStringArray] = [ + PackedStringArray(["mcp-servers"]), + PackedStringArray(["servers"]), + ] + server_key_path_aliases = aliases + entry_url_field = "url" + # pi-codemode-mcp selects stdio from `command` and remote transport from + # `url`; it ignores `type`. Keep generated stdio entries minimal and typeless. + entry_extra_fields = {} + entry_initial_fields = {} + # Attach migration (#838). Pi stdio entries are flat command/args/env. + # When Configure replaces a legacy URL entry, remove `url`, `headers`, and + # any redundant `type` field so the generated stdio entry stays canonical. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url", "headers", "type"]) + # `env` is the only user-mutable field pi's docs surface. Future + # fields still survive — the strategy deep-copies unknown keys. + command_user_fields = PackedStringArray(["env"]) + # Pi's loader also accepts pure-URL entries (the example mcp.json in + # the pi-codemode-mcp repo ships stdio + URL entries side-by-side). + # Keep the manual-instruction URL fallback alive. + command_supports_url_fallback = true + # ~/.pi/agent/mcp.json is created by the first pi launch, so its + # presence is the strongest install signal. Mirror antigravity's + # `detect_paths = path_template.values()` pattern so the dock shows + # the installed badge before Configure has run. + detect_paths = PackedStringArray(path_template.values()) \ No newline at end of file diff --git a/addons/godot_ai/clients/pi.gd.uid b/addons/godot_ai/clients/pi.gd.uid new file mode 100644 index 0000000..53aeb7c --- /dev/null +++ b/addons/godot_ai/clients/pi.gd.uid @@ -0,0 +1 @@ +uid://it00ohwkm2nd diff --git a/addons/godot_ai/clients/qwen_code.gd b/addons/godot_ai/clients/qwen_code.gd new file mode 100644 index 0000000..63bc7b2 --- /dev/null +++ b/addons/godot_ai/clients/qwen_code.gd @@ -0,0 +1,26 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "qwen_code" + display_name = "Qwen Code" + config_type = "json" + path_template = { + "unix": "~/.qwen/settings.json", + "windows": "$USERPROFILE/.qwen/settings.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + entry_url_field = "httpUrl" + ## Attach migration (#838). Qwen Code is a gemini-cli fork with the same + ## flat stdio shape and one-of `command` | `url` | `httpUrl` rule + ## (docs/users/features/mcp.md). Qwen adds `discoveryTimeoutMs` (stdio + ## discovery handshake cap, default 30s). + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["httpUrl", "url"]) + command_user_fields = PackedStringArray([ + "timeout", "trust", "includeTools", "excludeTools", "env", "cwd", + "discoveryTimeoutMs", + ]) + command_timeout_fields = PackedStringArray(["timeout", "discoveryTimeoutMs"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/qwen_code.gd.uid b/addons/godot_ai/clients/qwen_code.gd.uid new file mode 100644 index 0000000..5f2eb1a --- /dev/null +++ b/addons/godot_ai/clients/qwen_code.gd.uid @@ -0,0 +1 @@ +uid://qwb5udkf423q diff --git a/addons/godot_ai/clients/roo_code.gd b/addons/godot_ai/clients/roo_code.gd new file mode 100644 index 0000000..5d7bd6a --- /dev/null +++ b/addons/godot_ai/clients/roo_code.gd @@ -0,0 +1,42 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "roo_code" + display_name = "Roo Code" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json", + "windows": "$APPDATA/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json", + "linux": "$XDG_CONFIG_HOME/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + ## Roo defaults an entry with no "type" to SSE transport — which returns + ## HTTP 400 against our streamable-http endpoint on `/mcp`. Pin the type + ## explicitly so Roo negotiates streamable-http (the current MCP spec's + ## recommended remote transport). See issue #189. The default verifier + ## requires every entry_extra_fields key to match, so a pre-#189 typeless + ## entry surfaces as drift instead of silently passing as configured. + entry_extra_fields = {"type": "streamable-http"} + ## `disabled` and `alwaysAllow` are user-state (they may have flipped the + ## entry off, or auto-approved specific tools like `session_manage`). + ## Seed on first Configure but preserve across reconfigure — without this + ## split, the Configure-All-Mismatched sweep silently wipes the user's + ## auto-approval list every time the type pin or URL drifts. + entry_initial_fields = {"disabled": false, "alwaysAllow": []} + ## Attach migration (#838). Roo stdio entries are flat command/args/env + ## (+cwd); docs state `type` defaults to "stdio" for command configs and + ## the stdio schema forbids url/headers. Pin type=stdio — it is documented + ## and repins the legacy "streamable-http" value in place. + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "type" + command_transport_value = "stdio" + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_initial_fields = {"disabled": false, "alwaysAllow": []} + command_user_fields = PackedStringArray([ + "disabled", "alwaysAllow", "timeout", "disabledTools", "watchPaths", + "env", "cwd", + ]) + command_timeout_fields = PackedStringArray(["timeout"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/roo_code.gd.uid b/addons/godot_ai/clients/roo_code.gd.uid new file mode 100644 index 0000000..1dcae84 --- /dev/null +++ b/addons/godot_ai/clients/roo_code.gd.uid @@ -0,0 +1 @@ +uid://denjdf50qrf66 diff --git a/addons/godot_ai/clients/trae.gd b/addons/godot_ai/clients/trae.gd new file mode 100644 index 0000000..afc7a68 --- /dev/null +++ b/addons/godot_ai/clients/trae.gd @@ -0,0 +1,23 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "trae" + display_name = "Trae" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Trae/User/mcp.json", + "windows": "$APPDATA/Trae/User/mcp.json", + "linux": "$XDG_CONFIG_HOME/Trae/User/mcp.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + ## Attach migration (#838). Trae stdio entries are flat command/args/env + ## with no type discriminator (docs.trae.cn/ide/add-mcp-servers); transport + ## is inferred from `command` vs `url`, so url/headers are legacy next to a + ## command. Entry stays minimal — Trae manages enable/disable in its UI, + ## and its startup/run timeouts ride user-owned env vars, which survive. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_user_fields = PackedStringArray(["env"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/trae.gd.uid b/addons/godot_ai/clients/trae.gd.uid new file mode 100644 index 0000000..f10046e --- /dev/null +++ b/addons/godot_ai/clients/trae.gd.uid @@ -0,0 +1 @@ +uid://cwpu48772vfj1 diff --git a/addons/godot_ai/clients/vscode.gd b/addons/godot_ai/clients/vscode.gd new file mode 100644 index 0000000..a18b97d --- /dev/null +++ b/addons/godot_ai/clients/vscode.gd @@ -0,0 +1,30 @@ +@tool +extends McpClient + +## VS Code (stable) reads MCP servers from per-user mcp.json under +## `servers.` with `{ "type": "http", "url": ... }`. + + +func _init() -> void: + id = "vscode" + display_name = "VS Code" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Code/User/mcp.json", + "windows": "$APPDATA/Code/User/mcp.json", + "linux": "$XDG_CONFIG_HOME/Code/User/mcp.json", + } + server_key_path = PackedStringArray(["servers"]) + entry_extra_fields = {"type": "http"} + ## Attach migration (#838). VS Code stdio entries are flat command/args/env + ## under `servers` with a documented `type: "stdio"` discriminator + ## (code.visualstudio.com/docs/agents/reference/mcp-configuration). The + ## stdio schema is `additionalProperties: false` (mcpConfiguration.ts), so + ## removing the legacy url/headers is load-bearing — leftovers invalidate + ## the whole entry, and the pin flips the legacy `type: "http"` in place. + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "type" + command_transport_value = "stdio" + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_user_fields = PackedStringArray(["env", "envFile", "cwd", "sandboxEnabled", "dev"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/vscode.gd.uid b/addons/godot_ai/clients/vscode.gd.uid new file mode 100644 index 0000000..1c79881 --- /dev/null +++ b/addons/godot_ai/clients/vscode.gd.uid @@ -0,0 +1 @@ +uid://dl6cm044pihub diff --git a/addons/godot_ai/clients/vscode_insiders.gd b/addons/godot_ai/clients/vscode_insiders.gd new file mode 100644 index 0000000..7f6a65b --- /dev/null +++ b/addons/godot_ai/clients/vscode_insiders.gd @@ -0,0 +1,23 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "vscode_insiders" + display_name = "VS Code Insiders" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Code - Insiders/User/mcp.json", + "windows": "$APPDATA/Code - Insiders/User/mcp.json", + "linux": "$XDG_CONFIG_HOME/Code - Insiders/User/mcp.json", + } + server_key_path = PackedStringArray(["servers"]) + entry_extra_fields = {"type": "http"} + ## Attach migration (#838). Identical format to vscode.gd — Insiders ships + ## the same mcpConfiguration.ts schema; see that descriptor for citations. + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "type" + command_transport_value = "stdio" + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_user_fields = PackedStringArray(["env", "envFile", "cwd", "sandboxEnabled", "dev"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/vscode_insiders.gd.uid b/addons/godot_ai/clients/vscode_insiders.gd.uid new file mode 100644 index 0000000..c763703 --- /dev/null +++ b/addons/godot_ai/clients/vscode_insiders.gd.uid @@ -0,0 +1 @@ +uid://cad5w4ofyg8a2 diff --git a/addons/godot_ai/clients/windsurf.gd b/addons/godot_ai/clients/windsurf.gd new file mode 100644 index 0000000..b3ef210 --- /dev/null +++ b/addons/godot_ai/clients/windsurf.gd @@ -0,0 +1,29 @@ +@tool +extends McpClient + + +func _init() -> void: + # #623: Windsurf was rebranded to Devin Desktop by Cognition (June 2026). + # The id stays "windsurf" — it is the stable registry key used for + # configured-status lookups. The MCP config path is unchanged by the + # rebrand: per the official docs (docs.devin.ai/desktop/cascade/mcp) the + # global config still lives under the platform's `.codeium/windsurf/` + # directory (~/.codeium/windsurf/ on unix, $USERPROFILE/.codeium/windsurf/ + # on Windows), and migrated installs carry their settings over in place. + id = "windsurf" + display_name = "Devin Desktop (Windsurf)" + config_type = "json" + path_template = { + "unix": "~/.codeium/windsurf/mcp_config.json", + "windows": "$USERPROFILE/.codeium/windsurf/mcp_config.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + entry_url_field = "serverUrl" + ## Attach migration (#838). Stdio entries are flat command/args/env + ## (docs.devin.ai/desktop/cascade/mcp); transport is inferred from + ## `command` vs `serverUrl` presence and no type field is documented — + ## do not write one. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["serverUrl"]) + command_user_fields = PackedStringArray(["env"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/windsurf.gd.uid b/addons/godot_ai/clients/windsurf.gd.uid new file mode 100644 index 0000000..af34b60 --- /dev/null +++ b/addons/godot_ai/clients/windsurf.gd.uid @@ -0,0 +1 @@ +uid://b6pqiok2mlsmg diff --git a/addons/godot_ai/clients/zed.gd b/addons/godot_ai/clients/zed.gd new file mode 100644 index 0000000..fbd5f29 --- /dev/null +++ b/addons/godot_ai/clients/zed.gd @@ -0,0 +1,29 @@ +@tool +extends McpClient + +## Zed registers MCP servers under `context_servers.` and supports both +## stdio and streamable http transports. + + +func _init() -> void: + id = "zed" + display_name = "Zed" + config_type = "json" + path_template = { + "darwin": "~/.config/zed/settings.json", + "linux": "$XDG_CONFIG_HOME/zed/settings.json", + "windows": "$APPDATA/Zed/settings.json", + } + server_key_path = PackedStringArray(["context_servers"]) + ## Attach migration (#838). Current Zed's context_servers entries are an + ## untagged serde enum discriminated by shape: `command` (string) + args/env + ## → stdio, `url` → HTTP (zed.dev/docs/ai/mcp; settings_content/project.rs). + ## BECAUSE the enum is untagged, HTTP-only keys left next to `command` + ## (`url`, `headers`, `oauth`) make the entry match no variant and break it — + ## removing them on migration is load-bearing, not cosmetic. `enabled`, + ## `remote`, and `timeout` are user-state on the stdio variant. + command_shape = McpClient.CommandShape.FLAT + command_legacy_keys = PackedStringArray(["url", "headers", "oauth"]) + command_user_fields = PackedStringArray(["enabled", "remote", "timeout", "env"]) + command_timeout_fields = PackedStringArray(["timeout"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/zed.gd.uid b/addons/godot_ai/clients/zed.gd.uid new file mode 100644 index 0000000..b9b313a --- /dev/null +++ b/addons/godot_ai/clients/zed.gd.uid @@ -0,0 +1 @@ +uid://d152l0u0r6fsc diff --git a/addons/godot_ai/clients/zoo_code.gd b/addons/godot_ai/clients/zoo_code.gd new file mode 100644 index 0000000..870ff39 --- /dev/null +++ b/addons/godot_ai/clients/zoo_code.gd @@ -0,0 +1,36 @@ +@tool +extends McpClient + + +func _init() -> void: + id = "zoo_code" + display_name = "Zoo Code" + config_type = "json" + path_template = { + "darwin": "~/Library/Application Support/Code/User/globalStorage/zoocodeorganization.zoo-code/settings/mcp_settings.json", + "windows": "$APPDATA/Code/User/globalStorage/zoocodeorganization.zoo-code/settings/mcp_settings.json", + "linux": "$XDG_CONFIG_HOME/Code/User/globalStorage/zoocodeorganization.zoo-code/settings/mcp_settings.json", + } + server_key_path = PackedStringArray(["mcpServers"]) + ## Local validation against the installed extension shows Zoo stores MCP + ## entries in `settings/mcp_settings.json` under `mcpServers`, matching Roo's + ## shape. Its changelog also references Streamable HTTP support, so pin the + ## transport explicitly to avoid any typeless entry falling back to SSE. + entry_extra_fields = {"type": "streamable-http"} + ## Preserve user-controlled state across reconfigure, parallel to Roo/Kilo. + entry_initial_fields = {"disabled": false, "alwaysAllow": []} + ## Attach migration (#838). Zoo's stdio zod schema is Roo's: flat + ## command/args/env(+cwd), `type: z.enum(["stdio"]).optional()`, and + ## url/headers explicitly forbidden on stdio entries (McpHub.ts) — so both + ## are legacy keys and the documented type pin repins "streamable-http". + command_shape = McpClient.CommandShape.FLAT + command_transport_key = "type" + command_transport_value = "stdio" + command_legacy_keys = PackedStringArray(["url", "headers"]) + command_initial_fields = {"disabled": false, "alwaysAllow": []} + command_user_fields = PackedStringArray([ + "disabled", "alwaysAllow", "timeout", "watchPaths", "disabledTools", + "env", "cwd", + ]) + command_timeout_fields = PackedStringArray(["timeout"]) + command_supports_url_fallback = true diff --git a/addons/godot_ai/clients/zoo_code.gd.uid b/addons/godot_ai/clients/zoo_code.gd.uid new file mode 100644 index 0000000..dd3713e --- /dev/null +++ b/addons/godot_ai/clients/zoo_code.gd.uid @@ -0,0 +1 @@ +uid://fmp0nlzcm3ukl diff --git a/addons/godot_ai/connection.gd b/addons/godot_ai/connection.gd new file mode 100644 index 0000000..753a49e --- /dev/null +++ b/addons/godot_ai/connection.gd @@ -0,0 +1,1058 @@ +@tool +class_name McpConnection +extends Node + +## WebSocket transport to the Godot AI Python server. +## Only handles connect, reconnect, send, and receive. +## Command dispatch is owned by McpDispatcher. + +const RECONNECT_DELAYS: Array[float] = [1.0, 2.0, 4.0, 8.0, 16.0, 30.0, 60.0] +const RECONNECT_VERBOSE_ATTEMPTS := 5 +const RECONNECT_LOG_HEARTBEAT_MSEC := 60_000 +## Backpressure policy: do not queue responses once the WebSocket's current +## outbound buffer plus the next payload would exceed this cap. Command +## responses get a compact structured error when that can still be sent; +## state events report failure so their callers can retry on a later tick. +const OUTBOUND_BUFFER_LIMIT_BYTES := 4 * 1024 * 1024 +## Cap the inbound packet drain per `_process` tick. A flooding peer or a +## fast batch could otherwise saturate `_handle_message` in one frame and +## blow the documented 4ms budget. Packets beyond this cap spill to the +## next frame; the cumulative spill counter is logged so flood patterns +## are observable in `logs_read`. See audit-v2 finding #12 (issue #356). +const PACKET_DRAIN_CAP_PER_TICK := 32 +## Mirror of the server's application close code for a handshake carrying a +## wrong auth token (#690; `websocket.py::_CLOSE_CODE_AUTH_TOKEN_MISMATCH`). +const CLOSE_CODE_AUTH_TOKEN_MISMATCH := 4003 +## After this many consecutive post-OPEN token-mismatch rejections, drop the +## token and handshake token-less (see `_note_post_open_close`). Two, not +## one: a transient stale-record race during a server swap gets one chance +## to resolve before the token is given up. +const AUTH_MISMATCH_FALLBACK_CLOSES := 2 +const ClientConfigurator := preload("res://addons/godot_ai/client_configurator.gd") +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Emitted whenever the underlying WebSocket open/closed state flips. +## Subscribers (e.g. the plugin-side telemetry helper) use this to drain +## events that were enqueued before the socket was ready. Emitted with +## ``true`` on first OPEN per connect, ``false`` on transition to CLOSED +## (including ``disconnect_from_server()``). +signal connection_state_changed(is_open: bool) + +var _peer := WebSocketPeer.new() +## Seeded by plugin.gd from the configured EditorSettings port before the +## first dial, then republished with the fully resolved port once the +## deferred startup walk (#678) finishes resolving/spawning. Each connect +## attempt recomputes the URL from the latest value, so reconnects keep +## dialing the port the Python server was asked to bind. +var ws_port := ClientConfigurator.DEFAULT_WS_PORT +## Per-launch handshake auth token (#690). Set by plugin.gd from the value +## it generated for the server spawn (also persisted in the managed-server +## editor-settings record so a reloaded plugin instance adopting the same +## server keeps sending it). Empty means "don't send the field" — servers +## we didn't spawn (dev servers, older servers) have no token to match. +var auth_token := "" +var _url := "" +var _connected := false +var _reconnect_attempt := 0 +var _reconnect_timer := 0.0 +## Pull-based reconnect observability. The peer owns CONNECTING/CLOSING +## timing; tracking entry time here lets logs and the dock distinguish those +## phases from the plugin-owned CLOSED-state backoff without changing policy. +var _observed_peer_state := WebSocketPeer.STATE_CLOSED +var _peer_state_entered_msec := 0 +var _last_reconnect_transition_log_msec := -1 +var _transient_diagnostic: Dictionary = {} +## One pre-OPEN failure diagnostic per WebSocketPeer. Without this guard the +## CLOSED state is polled every frame and would flood the editor log. +var _preopen_failure_logged_for_peer := false +var _session_id := "" +## Consecutive post-OPEN closes with CLOSE_CODE_AUTH_TOKEN_MISMATCH. NOT +## reset by `_clear_on_disconnect` — the streak is counted exactly at the +## close events it exists to observe, across reconnect attempts. Reset on +## any other close code and on a successful `handshake_ack`. +var _auth_mismatch_closes := 0 +## Godot-AI Python package version reported by the server in its `handshake_ack` +## reply. Empty until the ack lands. Older servers (pre-handshake_ack) leave +## this empty forever — callers that gate on it (the dock's mismatch banner) +## must treat empty as "unknown, don't raise a false alarm". +var server_version := "" + +var dispatcher +var log_buffer +var surfaced_error_tracker +## Set by plugin.gd. Lets the per-frame play-state poll end game-run +## bookkeeping when the game exits on its own (self-quit, crash) — the +## debugger session's stopped signal is not reliably connected, and no MCP +## stop op runs in that path (#642). +var debugger_plugin +## Set by plugin.gd when the HTTP port is occupied by an incompatible or +## unverified server. Keeping the Connection node alive lets handlers and the +## dock share one object, but no WebSocket is opened to the wrong server. +var connect_blocked := false +var connect_block_reason := "" +var _blocked_notice_logged := false +## Compatibility property used by existing handlers. Setting true increments +## the pause depth; setting false decrements it. Processing stays paused until +## every nested pause has resumed. +var pause_processing: bool: + get: return _pause_depth > 0 + set(value): + if value: + pause() + else: + resume() +var _pause_depth := 0 +## Cumulative count of inbound packets that didn't fit in their tick's drain +## budget and got deferred to a subsequent tick. Reset on disconnect so each +## connection starts with a clean spillover history. Logged whenever new +## spillover occurs so flood patterns surface in `logs_read`. +var _packet_spillover_total := 0 + + +func _ready() -> void: + _session_id = _make_session_id(ProjectSettings.globalize_path("res://")) + ## Increase outbound buffer for large messages (e.g. screenshot base64). + ## Default is 64 KB; screenshots can be several MB. + _peer.outbound_buffer_size = OUTBOUND_BUFFER_LIMIT_BYTES + ## Symmetric inbound bump (#690): the server sends up to 4 MB + ## (websocket.py max_size), but Godot's inbound default is 64 KB — a + ## large script/text write or batch_execute payload used to overflow + ## the peer buffer, drop the frame, and surface as an opaque 5s + ## timeout + reconnect with no error naming the size. + _peer.inbound_buffer_size = OUTBOUND_BUFFER_LIMIT_BYTES + if connect_blocked: + _log_blocked_notice_once() + set_process(false) + return + _connect_to_server() + _hook_editor_signals() + + +func _process(delta: float) -> void: + if pause_processing: + return + _peer.poll() + ## Run-stop bookkeeping must not wait behind the socket-state machine: + ## if the game stops while disconnected, the first command drained on + ## reconnect would still observe stale "live" state (PR #642 review). + _check_game_run_play_state(EditorInterface.is_playing_scene()) + + var peer_state := _peer.get_ready_state() + var transition := _observe_peer_state(peer_state, Time.get_ticks_msec()) + match peer_state: + WebSocketPeer.STATE_OPEN: + if not _connected: + _connected = true + _reconnect_attempt = 0 + log_buffer.log("connected to server") + _send_handshake() + ## Reset the edge detectors so the next _check_state_changes + ## tick re-emits any non-default scene/play state — the + ## handshake carries readiness only, so without this a + ## (re)connected server never learns the current scene. + _last_scene_path = "" + _last_play_state = false + connection_state_changed.emit(true) + + _drain_inbound_packets(_peer) + + _check_state_changes() + + if dispatcher: + for response in dispatcher.tick(): + _send_json(response) + + WebSocketPeer.STATE_CLOSED: + if _connected: + _connected = false + ## This peer reached OPEN, so its one close diagnostic is the + ## post-OPEN line below. Mark the peer consumed; otherwise a + ## stale reconnect delay leaves it in CLOSED for another frame + ## and the pre-OPEN branch emits a mislabeled duplicate. + _preopen_failure_logged_for_peer = true + _clear_on_disconnect() + var code := _peer.get_close_code() + var reason := _peer.get_close_reason() + var open_elapsed_sec := float(transition.get("previous_elapsed_sec", 0.0)) + var close_diagnostic := _note_post_open_close(code) + if close_diagnostic.is_empty(): + close_diagnostic = { + "reason_code": "connection_lost", + "reason": _close_reason_text(code, reason), + } + _transient_diagnostic = close_diagnostic + _log_reconnect_transition( + _postopen_close_diagnostic( + open_elapsed_sec, + code, + reason, + _url, + close_diagnostic, + ), + maxi(1, _reconnect_attempt), + true, + ) + connection_state_changed.emit(false) + elif not _preopen_failure_logged_for_peer: + _preopen_failure_logged_for_peer = true + ## A failed attempt never reached OPEN, so any post-OPEN reason + ## belongs to the previous peer and must not describe this one. + _transient_diagnostic.clear() + ## Initial failure is attempt 1 for diagnostics. Later transition + ## summaries are time-throttled so a missing listener stays + ## observable without tying log volume to attempt duration. + var failed_attempt := maxi(1, _reconnect_attempt) + var connecting_elapsed_sec := float( + transition.get("previous_elapsed_sec", 0.0) + ) + _log_reconnect_transition( + _preopen_failure_diagnostic( + failed_attempt, + connecting_elapsed_sec, + _reconnect_timer, + _peer.get_close_code(), + _peer.get_close_reason(), + _url + ), + failed_attempt, + ) + _reconnect_timer -= delta + if _reconnect_timer <= 0.0: + _attempt_reconnect() + + WebSocketPeer.STATE_CLOSING: + pass + WebSocketPeer.STATE_CONNECTING: + pass + +func get_session_id() -> String: + return _session_id + +## Drain up to PACKET_DRAIN_CAP_PER_TICK inbound packets and dispatch each +## via `_handle_message`. Anything past the cap stays in the peer's queue +## and gets picked up next tick. The cumulative spillover count is logged +## (via `log_buffer`) only when the cap was actually hit AND packets remain +## — sustained flood thus emits one log line per tick with the running +## total, while a normal-traffic frame stays silent. +## +## `peer` is untyped (Variant) so tests can inject a duck-typed fake with +## `get_available_packet_count()` + `get_packet()`. Production passes the +## real `_peer: WebSocketPeer`. +func _drain_inbound_packets(peer) -> Dictionary: + var drained := 0 + while peer.get_available_packet_count() > 0 and drained < PACKET_DRAIN_CAP_PER_TICK: + var raw: String = peer.get_packet().get_string_from_utf8() + _handle_message(raw) + drained += 1 + + var spilled := 0 + if drained >= PACKET_DRAIN_CAP_PER_TICK and peer.get_available_packet_count() > 0: + spilled = peer.get_available_packet_count() + _packet_spillover_total += spilled + if log_buffer: + log_buffer.log( + ( + "[backpressure] inbound drain capped at %d/tick;" + + " %d packets spilled to next frame (cumulative %d)" + ) + % [PACKET_DRAIN_CAP_PER_TICK, spilled, _packet_spillover_total] + ) + + return {"drained": drained, "spilled": spilled} + + +var is_connected: bool: + get: return _connected + + +func disconnect_from_server() -> void: + if _connected: + _peer.close(1000, "Plugin unloading") + _connected = false + ## This peer reached OPEN and is being closed deliberately, so neither + ## the post-OPEN nor pre-OPEN close diagnostic applies. Consume its one + ## diagnostic before the CLOSED tick observes the pre-cleared flag. + _preopen_failure_logged_for_peer = true + ## Pre-clearing _connected makes the STATE_CLOSED branch skip its + ## _clear_on_disconnect() — run it here so deliberate closes don't + ## leak the old server's version/deferred state into the next one. + _clear_on_disconnect() + connection_state_changed.emit(false) + + +## Reset per-connection state that was filled in by the previous server +## and must NOT bleed into the next one. `force_restart_server` swaps +## servers without reloading the plugin, so without this reset the dock +## would keep showing the killed server's version until the next ack. +## Also fires on plain reconnect-loop drops — correct either way. +func _clear_on_disconnect() -> void: + server_version = "" + ## Reset the spillover counter so a flood pattern from the previous + ## connection doesn't pollute the next one's `logs_read` baseline. + _packet_spillover_total = 0 + if dispatcher: + dispatcher.clear_deferred_responses() + ## Queued-but-unexecuted commands from the dead connection must not + ## run under the next one (#712): their requester's futures were + ## already failed server-side, so executing them after reconnect is + ## an uncorrelatable surprise write. + dispatcher.clear_command_queue() + + +## Full pre-free cleanup for plugin unload: stop _process, close the +## socket, and drop dispatcher/log_buffer refs so their Callable-held +## RefCounted handlers decref before plugin.gd clears _handlers. +## See issue #46 and plugin.gd::_exit_tree. +func teardown() -> void: + set_process(false) + disconnect_from_server() + dispatcher = null + log_buffer = null + + +func _connect_to_server() -> void: + _url = "ws://127.0.0.1:%d" % ws_port + var err := _peer.connect_to_url(_url) + if err != OK: + log_buffer.log("failed to initiate connection (error %d)" % err) + _observed_peer_state = _peer.get_ready_state() + _peer_state_entered_msec = Time.get_ticks_msec() + + +func _attempt_reconnect() -> void: + if connect_blocked: + _log_blocked_notice_once() + set_process(false) + return + var delay := _reconnect_delay_for_attempt(_reconnect_attempt) + _reconnect_attempt += 1 + _reconnect_timer = delay + _log_reconnect_transition( + "connecting to server (attempt %d)" % _reconnect_attempt, + _reconnect_attempt, + ) + ## Always create a fresh WebSocketPeer before reconnecting. A peer that has + ## reached STATE_CLOSED is terminal; reusing it can leave the editor stuck in + ## a quiet reconnect loop after the Python server restarts. + _peer = WebSocketPeer.new() + _preopen_failure_logged_for_peer = false + _peer.outbound_buffer_size = OUTBOUND_BUFFER_LIMIT_BYTES + ## Keep the reconnect peer symmetric with _ready()'s (#690). + _peer.inbound_buffer_size = OUTBOUND_BUFFER_LIMIT_BYTES + _connect_to_server() + + +func pause() -> void: + _pause_depth += 1 + + +func resume() -> void: + _pause_depth = maxi(0, _pause_depth - 1) + + +func pause_depth() -> int: + return _pause_depth + + +static func _reconnect_delay_for_attempt(attempt_index: int) -> float: + var delay_idx := mini(attempt_index, RECONNECT_DELAYS.size() - 1) + return RECONNECT_DELAYS[delay_idx] + + +static func _should_log_reconnect_transition( + attempt_number: int, + now_msec: int, + last_log_msec: int +) -> bool: + ## Keep the first few transitions visible, then emit at most one summary per + ## minute. Attempt-number throttling goes quiet for minutes when the engine + ## spends a long time in CONNECTING, which is the state this log explains. + return ( + attempt_number <= RECONNECT_VERBOSE_ATTEMPTS + or last_log_msec < 0 + or now_msec - last_log_msec >= RECONNECT_LOG_HEARTBEAT_MSEC + ) + + +func _log_reconnect_transition(message: String, attempt_number: int, force := false) -> void: + if not log_buffer: + return + var now_msec := Time.get_ticks_msec() + if not force and not _should_log_reconnect_transition( + attempt_number, + now_msec, + _last_reconnect_transition_log_msec, + ): + return + _last_reconnect_transition_log_msec = now_msec + log_buffer.log(message) + + +static func _preopen_failure_diagnostic( + attempt_number: int, + connecting_elapsed_sec: float, + retry_in_sec: float, + code: int, + reason: String, + url: String +) -> String: + var retry_text := "retrying now" + if retry_in_sec > 0.0: + retry_text = "retrying in %.0fs" % retry_in_sec + return ( + "connection attempt %d failed before OPEN after %.1fs; %s" + + " (code %d, reason %s, url %s)" + ) % [ + attempt_number, + maxf(0.0, connecting_elapsed_sec), + retry_text, + code, + _sanitized_close_reason(reason), + url, + ] + + +static func _postopen_close_diagnostic( + open_elapsed_sec: float, + code: int, + reason: String, + url: String, + diagnostic: Dictionary = {} +) -> String: + var message := ( + "connection lost after being open for %.1fs (code %d, reason %s, url %s); reconnecting" + % [maxf(0.0, open_elapsed_sec), code, _sanitized_close_reason(reason), url] + ) + match str(diagnostic.get("recovery_action", "")): + "retry_authenticated": + message += " with the current auth token (rejection 1/%d)" % AUTH_MISMATCH_FALLBACK_CLOSES + "retry_tokenless": + message += " with a token-less handshake (rejection %d/%d)" % [ + int(diagnostic.get("occurrence", AUTH_MISMATCH_FALLBACK_CLOSES)), + AUTH_MISMATCH_FALLBACK_CLOSES, + ] + return message + + +static func _sanitized_close_reason(reason: String) -> String: + var reason_label := reason.strip_edges() + if reason_label.is_empty(): + return "" + return reason_label.replace("\r", "\\r").replace("\n", "\\n") + + +static func _close_reason_text(code: int, reason: String) -> String: + return "Close code %d: %s" % [code, _sanitized_close_reason(reason)] + + +## Token-mismatch fallback (#690 follow-up). The server's auth token is +## fixed for its whole launch, so redialing with the same wrong token can +## never succeed — without this the reconnect loop 4003s forever. The +## reproduced multi-editor failure: a duplicate spawn overwrites the shared +## managed-server record with its fresh token, dies unable to bind, and +## this editor is left holding a token the surviving server never saw. +## After AUTH_MISMATCH_FALLBACK_CLOSES consecutive rejections, drop to a +## token-less handshake, which the server accepts by design (older plugins +## and adopted servers have no token, and the field is attacker-omittable — +## see websocket.py; omitting it gives up no security). Scope note: only +## this connection's copy of the token is dropped — the plugin static and +## the persisted record heal via the startup walk's adoption arms. +func _note_post_open_close(code: int) -> Dictionary: + if code != CLOSE_CODE_AUTH_TOKEN_MISMATCH or auth_token.is_empty(): + _auth_mismatch_closes = 0 + return {} + _auth_mismatch_closes += 1 + var occurrence := _auth_mismatch_closes + if _auth_mismatch_closes < AUTH_MISMATCH_FALLBACK_CLOSES: + return { + "reason_code": "auth_token_mismatch", + "reason": "Server rejected the editor auth token; retrying once in case of a server-swap race.", + "occurrence": occurrence, + "recovery_action": "retry_authenticated", + } + auth_token = "" + _auth_mismatch_closes = 0 + return { + "reason_code": "auth_token_mismatch", + "reason": "Server rejected the editor auth token twice; the next handshake will omit it.", + "occurrence": occurrence, + "recovery_action": "retry_tokenless", + } + + +## Record one peer-state transition and return the duration of the state that +## just ended. Kept separate from `_transport_status_snapshot` so tests can +## exercise the status contract with injected values and no live socket. +func _observe_peer_state(state: int, now_msec: int) -> Dictionary: + if _peer_state_entered_msec <= 0: + _observed_peer_state = state + _peer_state_entered_msec = now_msec + return {"changed": false, "previous_elapsed_sec": 0.0} + if state == _observed_peer_state: + return {"changed": false, "previous_elapsed_sec": 0.0} + var previous_elapsed_sec := maxf( + 0.0, + (now_msec - _peer_state_entered_msec) / 1000.0, + ) + var previous_state := _observed_peer_state + _observed_peer_state = state + _peer_state_entered_msec = now_msec + return { + "changed": true, + "previous_state": previous_state, + "previous_elapsed_sec": previous_elapsed_sec, + } + + +## Pure transport-status contract shared by the connection log and dock. It +## intentionally knows nothing about lifecycle diagnoses; the thin public +## wrapper below applies generic `blocked`, while server_lifecycle.gd remains +## authoritative for exact terminal states such as incompatible/foreign port. +static func _transport_status_snapshot( + state: int, + state_elapsed_sec: float, + attempt: int, + retry_timer: float +) -> Dictionary: + var phase := "closing" + match state: + WebSocketPeer.STATE_OPEN: + phase = "connected" + WebSocketPeer.STATE_CONNECTING: + phase = "connecting" + WebSocketPeer.STATE_CLOSED: + phase = "retrying" + WebSocketPeer.STATE_CLOSING: + phase = "closing" + var snapshot := { + "phase": phase, + "attempt": maxi(0, attempt), + "state_elapsed_sec": maxf(0.0, state_elapsed_sec), + } + ## `retry_in_sec` is deliberately unrepresentable outside CLOSED-state + ## backoff. CONNECTING is an in-flight attempt, never "retrying in 0s". + if phase == "retrying": + snapshot["retry_in_sec"] = maxf(0.0, retry_timer) + return snapshot + + +func get_transport_status() -> Dictionary: + var now_msec := Time.get_ticks_msec() + var elapsed_sec := 0.0 + if _peer_state_entered_msec > 0: + elapsed_sec = maxf(0.0, (now_msec - _peer_state_entered_msec) / 1000.0) + var snapshot := _transport_status_snapshot( + _peer.get_ready_state(), + elapsed_sec, + _reconnect_attempt, + _reconnect_timer, + ) + if connect_blocked: + snapshot["phase"] = "blocked" + snapshot.erase("retry_in_sec") + snapshot["reason_code"] = "connection_blocked" + if not connect_block_reason.is_empty(): + snapshot["reason"] = connect_block_reason + elif not _transient_diagnostic.is_empty(): + for key in _transient_diagnostic: + snapshot[key] = _transient_diagnostic[key] + return snapshot + + +func _log_blocked_notice_once() -> void: + if _blocked_notice_logged: + return + _blocked_notice_logged = true + if log_buffer and not connect_block_reason.is_empty(): + log_buffer.log(connect_block_reason) + + +func _send_handshake() -> void: + _last_readiness = get_readiness() + _send_json(_build_handshake()) + + +## Split from _send_handshake so tests can assert the payload shape +## without a live WebSocket peer. +func _build_handshake() -> Dictionary: + var payload := { + "type": "handshake", + "session_id": _session_id, + "godot_version": Engine.get_version_info().get("string", "unknown"), + "project_path": ProjectSettings.globalize_path("res://"), + "plugin_version": ClientConfigurator.get_plugin_version(), + "protocol_version": 1, + "readiness": _last_readiness, + "editor_pid": OS.get_process_id(), + "server_launch_mode": ClientConfigurator.get_server_launch_mode(), + } + ## Omit rather than send "" — the server treats an ABSENT token as a + ## compat-accepted older plugin, but a PRESENT wrong one as hostile. + if not auth_token.is_empty(): + payload["auth_token"] = auth_token + return payload + + +## Classify one raw inbound frame. Shared by the normal dispatch path +## (`_handle_message`, which enqueues commands) and the exclusive-run +## service path (`_service_handle_message`, which rejects them) — one +## parser, two sinks, so the paths can't drift. `kind` is one of: +## "ack", "command", "malformed_command", "ignore". +func _classify_message(raw: String) -> Dictionary: + var parsed = JSON.parse_string(raw) + if parsed == null: + push_warning("MCP: failed to parse message: %s" % raw) + return {"kind": "ignore", "parsed": null} + if not (parsed is Dictionary): + return {"kind": "ignore", "parsed": null} + if parsed.get("type", "") == "handshake_ack": + return {"kind": "ack", "parsed": parsed} + if parsed.has("request_id") and parsed.has("command"): + if ( + parsed.get("request_id") is String + and parsed.get("command") is String + and (not parsed.has("params") or parsed.get("params") is Dictionary) + ): + return {"kind": "command", "parsed": parsed} + return {"kind": "malformed_command", "parsed": parsed} + return {"kind": "ignore", "parsed": parsed} + + +func _handle_message(raw: String) -> void: + var classified := _classify_message(raw) + match classified["kind"]: + "ack": + _handle_handshake_ack(classified["parsed"]) + "command": + if dispatcher: + dispatcher.enqueue(classified["parsed"]) + "malformed_command": + _reply_malformed_command(classified["parsed"]) + + +func _handle_handshake_ack(parsed: Dictionary) -> void: + server_version = str(parsed.get("server_version", "")) + ## The server accepted our handshake — any token-mismatch streak is + ## over; a later unrelated 4003 starts a fresh one. + _auth_mismatch_closes = 0 + _transient_diagnostic.clear() + + +## Never enqueue a malformed command frame: the dispatcher's typed casts +## would error on the queue head every tick, wedging every later command +## behind it. Reply with an error when the request_id is usable so the +## server's pending future resolves instead of waiting out the full +## command timeout. +func _reply_malformed_command(parsed: Dictionary) -> void: + push_warning("MCP: dropping malformed command frame (request_id/command must be String, params a Dictionary)") + var rid: Variant = parsed.get("request_id") + if rid is String and not String(rid).is_empty(): + var response := ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Malformed command frame: request_id/command must be strings and params a dict" + ) + response["request_id"] = rid + response["readiness"] = get_readiness() + _stamp_error_watermark(response) + _send_json(response) + + +## Send a state event to the server (not a command response). +func send_event(event_name: String, data: Dictionary = {}) -> bool: + return _send_json({"type": "event", "event": event_name, "data": data}) + + +## Push a command response for a request_id whose handler deferred its reply +## (see McpDispatcher.DEFERRED_RESPONSE). `payload` must carry either a `data` +## or `error` field in the same shape handlers normally return. +func send_deferred_response(request_id: String, payload: Dictionary) -> void: + if dispatcher != null and not dispatcher.has_pending_deferred_response(request_id): + if log_buffer: + log_buffer.log("[defer] dropped late response for expired request %s" % request_id) + return + var response := payload.duplicate() + response["request_id"] = request_id + if not response.has("status"): + response["status"] = "ok" if payload.has("data") else "error" + ## Symmetric with McpDispatcher::_dispatch — stamp live readiness on the + ## deferred reply so the server's session cache self-heals from any + ## response, not just the synchronous ones. Lets `project_stop` (the + ## main deferred-response producer) stay correct even if its bespoke + ## `readiness_after` payload field were ever dropped. + if not response.has("readiness"): + response["readiness"] = get_readiness() + if not response.has("error_watermark"): + _stamp_error_watermark(response) + if _send_json(response) and dispatcher != null: + dispatcher.complete_deferred_response(request_id) + + +## Result of one cooperative transport-servicing pass during an exclusive +## synchronous run (currently only the test runner). PAUSED is an +## invariant violation for callers, not a healthy state: a pause held +## across servicing checkpoints would silently starve the heartbeat. +enum ServiceStatus { SERVICED, DISCONNECTED, PAUSED, BLOCKED } + +## Cumulative cap on application packets processed across ONE exclusive +## run. Counts every drained packet — valid command, malformed frame, or +## ack-like — so no frame kind evades it. Past the cap the connection is +## closed (1013): bounded rejects, never unbounded stale buffering. 2048 +## leaves headroom under Godot's default max_queued_packets (4096) and +## sits above stormtest's ~1000-call default workload; tune with +## telemetry/benchmarks if rejection traffic ever extends a checkpoint. +const EXCLUSIVE_RUN_PACKET_CAP := 2048 +const CLOSE_CODE_EXCLUSIVE_RUN_FLOOD := 1013 +## Reject-log throttle: first few rejects verbatim, then periodic totals. +const _SERVICE_REJECT_LOG_FIRST := 5 +const _SERVICE_REJECT_LOG_EVERY := 100 + +## Service the WebSocket transport from inside a long synchronous handler +## (an "exclusive run" — the test runner). The editor main thread is +## blocked, so `_process` cannot poll; without this the server keepalive +## (20s ping interval / 20s timeout) closes the session mid-run. See +## docs/test-run-transport-starvation-plan.md. +## +## Contract — do NOT extend this method to dispatch: +## - `WebSocketPeer.poll()` has no heartbeat-only mode; it also buffers +## application frames. Buffering them past this call would replay them +## STALE after their server-side futures expire (the #712 hazard), so +## every drained command frame is REJECTED immediately with a retryable +## EDITOR_NOT_READY / EDITOR_TEST_RUNNING error instead. +## - Drains to quiescence: poll → drain everything available → poll again, +## until no packets remain. A full packet queue could hide a ping deeper +## in the TCP stream, so nothing may spill to a later checkpoint. +## - `run_state` is caller-owned mutable state carrying the cumulative +## packet counter under "packets_serviced" — no connection-global +## lifecycle that could leak if the run dies. +func service_transport_during_exclusive_run(run_state: Dictionary) -> ServiceStatus: + if connect_blocked: + return ServiceStatus.BLOCKED + if pause_processing: + return ServiceStatus.PAUSED + while true: + _peer.poll() + if _peer.get_ready_state() != WebSocketPeer.STATE_OPEN: + return ServiceStatus.DISCONNECTED + if _peer.get_available_packet_count() == 0: + return ServiceStatus.SERVICED + while _peer.get_available_packet_count() > 0: + var raw: String = _peer.get_packet().get_string_from_utf8() + if _service_note_packet(run_state): + if log_buffer: + log_buffer.log( + "[busy] packet flood during test run (%d > cap %d) — closing connection" + % [int(run_state.get("packets_serviced", 0)), EXCLUSIVE_RUN_PACKET_CAP] + ) + _peer.close(CLOSE_CODE_EXCLUSIVE_RUN_FLOOD, "command flood during test run") + return ServiceStatus.DISCONNECTED + _service_handle_message(raw, int(run_state.get("packets_serviced", 0))) + ## Unreachable: every exit above returns. Keeps the typed signature happy. + return ServiceStatus.SERVICED + + +## Shared between-phase checkpoint for exclusive runs: deadline first +## (cheap), then transport servicing via `service_cb`. Returns "" to +## continue, or a terminal outcome: "timeout" | "transport_lost" | +## "paused". Static and stateless so the runner's between-test checkpoints +## and the handler's discovery checkpoints share ONE outcome mapping — +## PAUSED is abort-worthy (a held pause would silently skip every later +## poll and starve the heartbeat), and DISCONNECTED/BLOCKED both mean "no +## live transport". +static func exclusive_run_checkpoint( + service_cb: Callable, deadline_ticks_ms: int, run_state: Dictionary +) -> String: + if deadline_ticks_ms > 0 and Time.get_ticks_msec() >= deadline_ticks_ms: + return "timeout" + if not service_cb.is_valid(): + return "" + var status: int = service_cb.call(run_state) + if status == ServiceStatus.SERVICED: + return "" + if status == ServiceStatus.PAUSED: + return "paused" + return "transport_lost" + + +## Count one application packet against the exclusive-run cap. Counts EVERY +## drained packet regardless of kind (valid command, malformed, ack-like) +## so no frame kind can evade the flood limit. Returns true once the cap is +## exceeded — the caller closes the connection. +static func _service_note_packet(run_state: Dictionary) -> bool: + var count: int = int(run_state.get("packets_serviced", 0)) + 1 + run_state["packets_serviced"] = count + return count > EXCLUSIVE_RUN_PACKET_CAP + + +## Exclusive-run sink for `_classify_message`: acks are still processed, +## malformed frames keep their normal reply, and valid commands are +## rejected without touching the dispatcher. +func _service_handle_message(raw: String, packets_serviced: int) -> void: + var classified := _classify_message(raw) + match classified["kind"]: + "ack": + _handle_handshake_ack(classified["parsed"]) + "command": + _service_reject_command(classified["parsed"], packets_serviced) + "malformed_command": + _reply_malformed_command(classified["parsed"]) + + +func _service_reject_command(parsed: Dictionary, packets_serviced: int) -> void: + _send_json(_build_service_reject(parsed)) + if log_buffer and ( + packets_serviced <= _SERVICE_REJECT_LOG_FIRST + or packets_serviced % _SERVICE_REJECT_LOG_EVERY == 0 + ): + ## Ring-buffer only (echo=false): a flood must not bury the console. + log_buffer.log( + "[busy] rejected '%s' during test run (packet %d)" + % [parsed.get("command", ""), packets_serviced], + false, + ) + + +## Build the busy-reject response for a valid command frame that arrived +## mid-run. Split from the send so tests can assert the exact wire shape. +func _build_service_reject(parsed: Dictionary) -> Dictionary: + var command: String = parsed.get("command", "") + var response := ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_TEST_RUNNING, + ( + "A test run is in progress on this editor — '%s' was not executed. " + + "Retry when the run completes, or fetch results afterward with " + + "test_manage(op=\"results_get\")." + ) % command, + true, + ) + response["request_id"] = parsed.get("request_id", "") + response["readiness"] = get_readiness() + _stamp_error_watermark(response) + return response + + +func _hook_editor_signals() -> void: + # Scene change: poll in _process since there's no direct signal for scene switch + # Play state: EditorInterface signals + EditorInterface.get_editor_settings() # ensure interface is ready + _last_scene_path = _get_current_scene_path() + _last_play_state = EditorInterface.is_playing_scene() + _last_play_state_for_run = _last_play_state + + +var _last_scene_path := "" +var _last_play_state := false +## Separate edge tracker for game-run bookkeeping: _last_play_state only +## advances when the play_state_changed event sends successfully, but ending +## run tracking must not depend on the websocket being up. +var _last_play_state_for_run := false +var _last_readiness := "" + + +## Compute current editor readiness from live Godot state. +static func get_readiness() -> String: + if EditorInterface.get_resource_filesystem().is_scanning(): + return "importing" + if EditorInterface.is_playing_scene(): + return "playing" + if EditorInterface.get_edited_scene_root() == null: + return "no_scene" + return "ready" + + +## Check for scene/play state changes each frame (lightweight polling). +func _check_state_changes() -> void: + var scene_path := _get_current_scene_path() + if scene_path != _last_scene_path: + if send_event("scene_changed", {"current_scene": scene_path}): + _last_scene_path = scene_path + if log_buffer: + log_buffer.log("[event] scene_changed -> %s" % scene_path) + + var playing := EditorInterface.is_playing_scene() + if playing != _last_play_state: + var state := "playing" if playing else "stopped" + if send_event("play_state_changed", {"play_state": state}): + _last_play_state = playing + if log_buffer: + log_buffer.log("[event] play_state_changed -> %s" % state) + + var readiness := get_readiness() + if readiness != _last_readiness: + if send_event("readiness_changed", {"readiness": readiness}): + _last_readiness = readiness + if log_buffer: + ## echo=false: readiness flips on every filesystem scan + ## (each import cycles importing -> ready), so echoing to + ## console spams every install during normal editing (#626). + ## The line stays in the ring for the dock's log panel. + log_buffer.log("[event] readiness -> %s" % readiness, false) + + +## Stopped↔playing edge handler for game-run bookkeeping. Handles both the +## stopped→playing edge (adopting editor-started runs) and the playing→stopped +## edge (ending runs). Runs every process tick (any socket state) so a +## self-quit game's run ends even while the transport is down or reconnecting. +func _check_game_run_play_state(playing: bool) -> void: + if playing == _last_play_state_for_run: + return + if debugger_plugin != null: + if playing: + ## #891: adopt a play the user started from the editor. The + ## debugger session's own adoption in `_setup_session` only fires + ## when `is_playing_scene()` is already true when the session + ## attaches, which an F5/F6 launch routinely misses; this edge is + ## the other half of that race. Polled every tick regardless of + ## socket state, same as the stop edge below. + debugger_plugin.note_editor_play_started() + else: + debugger_plugin.note_editor_play_stopped() + _last_play_state_for_run = playing + + +func _get_current_scene_path() -> String: + var scene_root := EditorInterface.get_edited_scene_root() + return scene_root.scene_file_path if scene_root else "" + + +func _send_json(data: Dictionary) -> bool: + if not _connected: + return false + var text := JSON.stringify(data) + var buffered_bytes := _peer.get_current_outbound_buffered_amount() + ## `send_text` encodes the string to UTF-8 internally, so an exact + ## `to_utf8_buffer().size()` here would encode every payload twice. Almost + ## all payloads sit far below the limit, so gate on a cheap upper bound + ## (<= 4 UTF-8 bytes per code point) and only pay for the exact count when + ## the estimate lands near the backpressure ceiling. + if _might_exceed_outbound_backpressure(buffered_bytes, text.length()): + var message_bytes := text.to_utf8_buffer().size() + if _would_exceed_outbound_backpressure(buffered_bytes, message_bytes): + return _handle_outbound_backpressure(data, buffered_bytes, message_bytes) + var err := _peer.send_text(text) + if err != OK: + if log_buffer: + log_buffer.log("[send] websocket send_text failed: %s" % error_string(err)) + return false + return true + + +static func _would_exceed_outbound_backpressure(buffered_bytes: int, message_bytes: int) -> bool: + return buffered_bytes + message_bytes > OUTBOUND_BUFFER_LIMIT_BYTES + + +## Cheap pre-check on the code-point count: UTF-8 uses at most 4 bytes per code +## point, so `char_count * 4` upper-bounds the encoded size. When even that +## upper bound fits under the ceiling the payload is definitely safe and we can +## skip the exact encode; only a positive here warrants `to_utf8_buffer()`. +static func _might_exceed_outbound_backpressure(buffered_bytes: int, char_count: int) -> bool: + return buffered_bytes + char_count * 4 > OUTBOUND_BUFFER_LIMIT_BYTES + + +func _handle_outbound_backpressure( + data: Dictionary, + buffered_bytes: int, + message_bytes: int, +) -> bool: + var request_id: String = data.get("request_id", "") + if request_id.is_empty(): + if log_buffer: + log_buffer.log( + "[send] requestless payload blocked by websocket backpressure " + + "(buffered=%d, message=%d, limit=%d)" + % [buffered_bytes, message_bytes, OUTBOUND_BUFFER_LIMIT_BYTES] + ) + return false + + var err_response := _make_backpressure_error(request_id, buffered_bytes, message_bytes) + _stamp_error_watermark(err_response) + var err_text := JSON.stringify(err_response) + var err_bytes := err_text.to_utf8_buffer().size() + if _would_exceed_outbound_backpressure(buffered_bytes, err_bytes): + if log_buffer: + log_buffer.log( + "[send] dropped response for request %s due to websocket backpressure " + + "(buffered=%d, message=%d, limit=%d)" + % [request_id, buffered_bytes, message_bytes, OUTBOUND_BUFFER_LIMIT_BYTES] + ) + return false + + var send_err := _peer.send_text(err_text) + if send_err != OK: + if log_buffer: + log_buffer.log("[send] websocket backpressure error send failed: %s" % error_string(send_err)) + return false + if log_buffer: + log_buffer.log( + "[send] %s -> error: outbound websocket backpressure" + % data.get("command", "response") + ) + return true + + +static func _make_backpressure_error( + request_id: String, + buffered_bytes: int, + message_bytes: int, +) -> Dictionary: + return { + "request_id": request_id, + "status": "error", + "data": {}, + ## Stamp readiness on the backpressure error too — the server's + ## per-response self-heal applies to every response shape the + ## plugin emits, and the next legitimate reply may already be + ## queued behind this one. + "readiness": get_readiness(), + "error": { + "code": ErrorCodes.INTERNAL_ERROR, + "message": ( + "Outbound WebSocket buffer is full; dropped response before queueing " + + "more data. Retry with a smaller payload (for screenshots, lower " + + "max_resolution or set include_image=false)." + ), + "data": { + "buffered_bytes": buffered_bytes, + "message_bytes": message_bytes, + "limit_bytes": OUTBOUND_BUFFER_LIMIT_BYTES, + }, + }, + } + + +func _stamp_error_watermark(response: Dictionary) -> void: + McpSurfacedErrorTracker.stamp_watermark(response, surfaced_error_tracker) + + +## Build a human-readable session ID of form "@<4hex>" from the project path. +## The slug is derived from the project directory name so agents can recognize +## which editor they're targeting; the hex suffix disambiguates same-project twins. +static func _make_session_id(project_path: String) -> String: + var base := project_path.rstrip("/\\").get_file() + if base == "": + base = "project" + var slug := _slugify(base) + if slug == "": + slug = "project" + var suffix := _rand_hex(4) + return "%s@%s" % [slug, suffix] + + +static func _slugify(s: String) -> String: + var out := "" + var prev_dash := false + for c in s.to_lower(): + if (c >= "a" and c <= "z") or (c >= "0" and c <= "9"): + out += c + prev_dash = false + elif not prev_dash and out != "": + out += "-" + prev_dash = true + return out.trim_suffix("-") + + +static func _rand_hex(n: int) -> String: + var bytes := PackedByteArray() + var byte_count := int(ceil(float(n) / 2.0)) + for i in byte_count: + bytes.append(randi() % 256) + return bytes.hex_encode().substr(0, n) diff --git a/addons/godot_ai/connection.gd.uid b/addons/godot_ai/connection.gd.uid new file mode 100644 index 0000000..ff78405 --- /dev/null +++ b/addons/godot_ai/connection.gd.uid @@ -0,0 +1 @@ +uid://bmnk8rsotiks2 diff --git a/addons/godot_ai/custom_tools/custom_tool_wrapper.gd b/addons/godot_ai/custom_tools/custom_tool_wrapper.gd new file mode 100644 index 0000000..45ace63 --- /dev/null +++ b/addons/godot_ai/custom_tools/custom_tool_wrapper.gd @@ -0,0 +1,66 @@ +@tool +extends RefCounted + +## bridge between dispatcher and addon handler + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +var _spec: McpCustomToolSpec +var _locator: McpServiceLocator +var _handler_instance = null # lazily loaded from _spec.script_path + +func _init(spec: McpCustomToolSpec, locator: McpServiceLocator) -> void: + _spec = spec + _locator = locator + +## Invoked by dispatcher._call_handler as .call(params) — SINGLE ARG. +## Internally splits into (clean_params, ctx) for the addon handler. +func invoke(params: Dictionary) -> Dictionary: + ## Dock enable/disable gate: a disabled tool is dropped from the + ## catalog push, but a client holding a stale list (or batch_execute) + ## can still name it — reject at dispatch too. + var registry := McpToolRegistry.get_instance() + if registry != null and not registry.is_tool_enabled(_spec.name): + return ErrorCodes.make(ErrorCodes.CUSTOM_TOOL_DISABLED, + "Custom tool '%s' is disabled in the Godot AI dock" % _spec.name) + ## Readiness gate (https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #1): block writes during play/import. + ## Checked BEFORE the lazy load so a gated tool's handler script (and any + ## _init side effects) never runs while the editor is busy. + var _readiness := McpConnection.get_readiness() + if _spec.requires_writable and (_readiness == "importing" or _readiness == "playing"): + return ErrorCodes.make(ErrorCodes.EDITOR_NOT_READY, "Editor is '%s' — write blocked for custom tool '%s'" % [_readiness, _spec.name]) + if _handler_instance == null: + var script := load(_spec.script_path) as GDScript + if script == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Cannot load %s" % _spec.script_path) + _handler_instance = script.new() # no-arg; per-call context arrives via ctx + if not _handler_instance.has_method(_spec.method): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "%s has no method '%s' for custom tool '%s'" % [_spec.script_path, _spec.method, _spec.name]) + ## Extract _request_id (dispatcher injected it) and strip from params + ## so the addon sees clean params matching its declared schema (https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #2). + var request_id: String= params.get("_request_id", "") + var clean_params := params.duplicate() + clean_params.erase("_request_id") + ## Construct ctx with transport metadata + live-object locator. + var ctx := McpCallContext.new() + ctx.request_id = request_id + ctx.session_id = _locator.get_connection().get_session_id() + ctx.spec = _spec + ctx.attach_locator(_locator) + ctx.deadline_msec = Time.get_ticks_msec() + _spec.timeout_ms + var result: Dictionary = _handler_instance.call(_spec.method, clean_params, ctx) + if result.get("_deferred", false): + ## Enforce the declared contract: batch_execute and the server's + ## timeout budget both trust spec.deferred, so a non-deferred spec + ## whose handler defers anyway would report success while its real + ## reply arrives uncorrelated later. + if not _spec.deferred: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Custom tool '%s' returned a deferred response but its spec declares deferred=false" % _spec.name) + if _spec.timeout_ms > 0: + ## Handlers return the SHARED McpDispatcher.DEFERRED_RESPONSE + ## const, which Godot makes read-only — stamping the per-spec + ## budget on it directly is a script error that aborts the call. + result = result.duplicate() + result["_deferred_timeout_ms"] = _spec.timeout_ms + return result diff --git a/addons/godot_ai/custom_tools/custom_tool_wrapper.gd.uid b/addons/godot_ai/custom_tools/custom_tool_wrapper.gd.uid new file mode 100644 index 0000000..ff02cb9 --- /dev/null +++ b/addons/godot_ai/custom_tools/custom_tool_wrapper.gd.uid @@ -0,0 +1 @@ +uid://b68uel6lsb7jr diff --git a/addons/godot_ai/custom_tools/mcp_call_context.gd b/addons/godot_ai/custom_tools/mcp_call_context.gd new file mode 100644 index 0000000..6e40d86 --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_call_context.gd @@ -0,0 +1,44 @@ +@tool +class_name McpCallContext +extends RefCounted + +## Per-call context handed to addon handlers. +## +## STABLE addon-facing surface (see AGENTS.md — published class_names are +## permanent compat surface): `request_id`, `session_id`, `deadline_msec`, +## `spec` (read-only), `is_expired()`, `send_deferred()`. Anything +## underscore-prefixed is internal wiring owned by the wrapper and may +## change between releases — addons must not reach into it. Keeping this +## surface narrow now is deliberate: it is much cheaper than breaking +## published addons later (#875 review). + +var request_id: String = "" +var session_id: String = "" +var deadline_msec: int = 0 +var spec: McpCustomToolSpec = null + +## Internal — injected by custom_tool_wrapper via attach_locator(). Do not +## use from addon code; the capability methods below are the contract. +var _locator: McpServiceLocator = null + + +## Internal — called by the wrapper during ctx construction. +func attach_locator(locator: McpServiceLocator) -> void: + _locator = locator + + +func is_expired() -> bool: + if deadline_msec == 0: + return false + return Time.get_ticks_msec() > deadline_msec + + +func send_deferred(payload: Dictionary) -> void: + if _locator == null: + push_error("McpCallContext: cannot send deferred response, locator is null") + return + var conn := _locator.get_connection() + if conn == null: + push_error("McpCallContext: cannot send deferred response, connection is null") + return + conn.send_deferred_response(request_id, payload) diff --git a/addons/godot_ai/custom_tools/mcp_call_context.gd.uid b/addons/godot_ai/custom_tools/mcp_call_context.gd.uid new file mode 100644 index 0000000..e37765b --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_call_context.gd.uid @@ -0,0 +1 @@ +uid://bdgqe4gyian2o diff --git a/addons/godot_ai/custom_tools/mcp_custom_tool_spec.gd b/addons/godot_ai/custom_tools/mcp_custom_tool_spec.gd new file mode 100644 index 0000000..8c5a551 --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_custom_tool_spec.gd @@ -0,0 +1,66 @@ +@tool +class_name McpCustomToolSpec +extends RefCounted + +## Descriptor for one custom tool registered by an addon. Mirrors the +## clients/_base.gd data-only descriptor pattern: fields are set by the +## caller, NO Callables (handler instance is materialized lazily by the +## dispatcher from script_path + method, so hot-reload can't SEGV a +## worker mid-call — same rationale as McpClient, issue #229). +## +## Construction: instantiate and set fields, then pass to +## McpToolRegistry.register(spec). Do NOT subclass — custom tools are +## dynamic (one addon may register several), not file-system-scanned +## like clients. + +# --- identity --- +var name: String = "" ## tool name, e.g. "gdunit_run". Must not shadow a built-in. +var description: String = "" ## shown to the agent by the MCP server +var params_schema: Dictionary = {} ## JSON Schema; advertised to the agent for shaping calls. Params are forwarded UNVALIDATED — the handler must validate its own input. + +# --- handler resolution (lazy materialization by dispatcher) --- +var script_path: String = "" ## "res://addons/.../handler.gd"; load()ed on first call +var method: StringName = &"" ## method on the handler; signature: (params: Dictionary, ctx: McpCallContext) -> Dictionary + +# --- source identity (https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #8) --- +var source_path: String = "" ## "plugin.cfg" path: "res://addons/gdunit4_mcp/plugin.cfg". Same path = same addon (replace allowed); different path colliding = reject + dock warning. NOTE: self-declared — a collision/ownership policy for cooperating addons, NOT a security boundary (any in-editor code can claim any path). +var source: String = "" ## display: "gdunit4_mcp". If empty, registry reads [plugin] name from source_path. + +# --- exposure --- +var promoted: bool = false ## opt-in: ask the server to ALSO register this tool as a first-class MCP tool ("custom_") with params_schema attached, so agents get native schemas/validation instead of the custom_manage indirection. The server caps promoted count; overflow stays reachable via custom_manage. + +# --- execution contract --- +var timeout_ms: int = 4500 ## deferred timeout → DEFERRED_TIMEOUT_MS_BY_COMMAND["custom:"] +var deferred: bool = false ## true → handler may return DEFERRED_RESPONSE, push later via ctx.send_deferred(payload) +var requires_writable: bool = false ## https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #1: readiness gate. false → reads run any time; true → blocks during play/import +var undoable: bool = false ## https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #6: must be true to participate in undo=true batch_execute + +# --- budgets (https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #5, enforced at register time) --- +const MAX_DESCRIPTION_CHARS := 600 +const MAX_SCHEMA_BYTES := 8192 +const MAX_TIMEOUT_MS := 120000 +const MIN_TIMEOUT_MS := 500 + + +## Returns an array of human-readable validation errors (empty = valid). +## Called by McpToolRegistry.register() and usable standalone for early +## feedback in addon _enter_tree before the registry is even live. +func validate() -> Array[String]: + var errors: Array[String] = [] + if name.is_empty(): + errors.append("name is empty\n") + if not name.is_valid_ascii_identifier(): + errors.append("name '%s' is not a valid identifier\n" % name) + if description.length() > MAX_DESCRIPTION_CHARS: + errors.append("description exceeds %d chars\n" % MAX_DESCRIPTION_CHARS) + if JSON.stringify(params_schema).to_utf8_buffer().size() > MAX_SCHEMA_BYTES: + errors.append("params_schema exceeds %d bytes\n" % MAX_SCHEMA_BYTES) + if script_path.is_empty() or not ResourceLoader.exists(script_path): + errors.append("script_path '%s' does not exist" % script_path) + if method.is_empty(): + errors.append("method is empty") + if timeout_ms < MIN_TIMEOUT_MS or timeout_ms > MAX_TIMEOUT_MS: + errors.append("timeout_ms %d out of range [%d, %d]" % [timeout_ms, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS]) + if source_path.is_empty() or not source_path.ends_with("plugin.cfg") or not FileAccess.file_exists(source_path): + errors.append("source_path '%s' must be an existing plugin.cfg path" % source_path) + return errors diff --git a/addons/godot_ai/custom_tools/mcp_custom_tool_spec.gd.uid b/addons/godot_ai/custom_tools/mcp_custom_tool_spec.gd.uid new file mode 100644 index 0000000..42fe408 --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_custom_tool_spec.gd.uid @@ -0,0 +1 @@ +uid://h7k8j5tpscwy diff --git a/addons/godot_ai/custom_tools/mcp_service_locator.gd b/addons/godot_ai/custom_tools/mcp_service_locator.gd new file mode 100644 index 0000000..4e50ac5 --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_service_locator.gd @@ -0,0 +1,16 @@ +@tool +class_name McpServiceLocator +extends RefCounted + +var _connection: McpConnection = null +var _log_buffer: McpLogBuffer = null + +func setup(connection: McpConnection, log_buffer: McpLogBuffer) -> void: + _connection = connection + _log_buffer = log_buffer + +func get_connection() -> McpConnection: + return _connection + +func get_log_buffer() -> McpLogBuffer: + return _log_buffer diff --git a/addons/godot_ai/custom_tools/mcp_service_locator.gd.uid b/addons/godot_ai/custom_tools/mcp_service_locator.gd.uid new file mode 100644 index 0000000..1815007 --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_service_locator.gd.uid @@ -0,0 +1 @@ +uid://dfvphmvo7en3i diff --git a/addons/godot_ai/custom_tools/mcp_tool_registry.gd b/addons/godot_ai/custom_tools/mcp_tool_registry.gd new file mode 100644 index 0000000..407d405 --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_tool_registry.gd @@ -0,0 +1,277 @@ +@tool +class_name McpToolRegistry +extends RefCounted + +## Central registry for custom tools. INSTANCE SINGLETON (not static) — +## unlike McpClientRegistry which is read-only/loaded-once/query-only (static +## is fine there), this registry is MUTABLE, has LIFECYCLE (clear on teardown), +## must EMIT SIGNALS to multiple consumers, and needs DEPENDENCY INJECTION +## (dispatcher, locator). Static funcs can't emit instance signals in GDScript, +## and static vars create #46 freed-instance regressions across reloads. +## +## plugin.gd owns the instance (new + setup + clear). Addons access it via +## get_instance() so they don't hold a reference. Source identity is +## spec.source_path (explicit plugin.cfg path, https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #8) — same source_path +## = same addon (hot-reload replace); different source_path colliding on +## a name = reject + dock warning. + +## singleton instance +static var _instance: McpToolRegistry = null + +## Singleton accessor for addons. Returns null if Godot AI isn't loaded. +static func get_instance() -> McpToolRegistry: + return _instance + + +## Instance fields (NOT static — lifecycle tied to plugin.gd) +var _specs: Dictionary = {} # name -> McpCustomToolSpec +var _by_source_path: Dictionary = {} # source_path -> Array[McpCustomToolSpec] (batch unregister index) +var _dispatcher: McpDispatcher = null # injected by plugin.gd via setup() +var _locator: McpServiceLocator = null # injected by plugin.gd via setup() +var _ready: bool = false +var _promoted_cnt = 0 + +## Instance signals (LEGAL — instance funcs can emit these). Multiple consumers +## (plugin.gd, dock, addons) can connect. +signal tools_changed # triggers custom_tools_changed push to server +signal registry_ready # https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #8: emit after Godot AI reload so addons can re-register + + +## Called by plugin.gd in _enter_tree. Injects live dependencies and registers +## the singleton. Addons can now reach the registry via get_instance(). +func setup(dispatcher: McpDispatcher, locator: McpServiceLocator) -> void: + _dispatcher = dispatcher + _locator = locator + _load_disabled_tools() + _instance = self + + +func register(spec: McpCustomToolSpec) -> bool: + if not _validate_one(spec): + return false + _commit_one(spec) + tools_changed.emit() + return true + + +## Atomic batch registration: validate ALL specs first (phase 1, zero +## mutation), then commit ALL (phase 2, cannot fail), then emit ONCE. +## A phase-1 failure leaves the registry AND dispatcher untouched — a +## per-spec register-then-bail loop would leave earlier specs committed +## and dispatchable while the server's tool list never hears about them. +func batch_register(specs: Array[McpCustomToolSpec]) -> bool: + if specs.is_empty(): + return true + ## Phase 1 — validate only. Also reject duplicate names WITHIN the + ## batch: _validate_one checks against committed state (nothing from + ## this batch is committed yet), and silently letting the last + ## duplicate win would hide an addon packaging bug. + var batch_names := {} + for spec in specs: + if not _validate_one(spec): + return false + if batch_names.has(spec.name): + push_warning("McpToolRegistry: duplicate name '%s' within batch — rejected" % spec.name) + return false + batch_names[spec.name] = true + ## Phase 2 — commit everything, emit once. + for spec in specs: + _commit_one(spec) + tools_changed.emit() + return true + + +## Phase 1 helper: validation + collision policy. NO registry/dispatcher +## mutation — the only side effect is filling the display-source fallback +## on the spec itself, which is harmless on reject. +func _validate_one(spec: McpCustomToolSpec) -> bool: + var errors := spec.validate() + if not errors.is_empty(): + push_error("McpToolRegistry: rejecting spec '%s': %s" % [spec.name, ", ".join(errors)]) + return false + ## Fill display source from plugin.cfg if addon left it empty. + if spec.source.is_empty(): + spec.source = _read_plugin_name(spec.source_path) + ## reject-on-collision: same source_path (hot-reload) replaces, different rejects + var existing: McpCustomToolSpec= _specs.get(spec.name) + if existing != null and existing.source_path != spec.source_path: + push_warning("McpToolRegistry: name '%s' collision between %s and %s — rejected" % [spec.name, existing.source_path, spec.source_path]) + return false + return true + + +## Phase 2 helper: commit one ALREADY-VALIDATED spec. Handles the +## hot-reload replace (same source_path — guaranteed by _validate_one). +## Never fails, never emits — callers own the tools_changed emit. +func _commit_one(spec: McpCustomToolSpec) -> void: + var existing: McpCustomToolSpec = _specs.get(spec.name) + if existing != null: + ## Replace: purge the OLD registration from all four dispatcher + ## dicts. Command name is "custom_tool:" — passing the bare + ## name would leave a materialized Callable in _handlers and the + ## hot-reloaded spec would silently never take effect. + _dispatcher.unregister("custom_tool:" + existing.name, "custom:" + existing.name) + _erase_from_source_path_index_locked(existing) + _specs[spec.name] = spec + _by_source_path.get_or_add(spec.source_path, []).append(spec) + ## Bridge to dispatcher lazy registration: register_lazy_handler + register_lazy. + ## handler_key = "custom:"; wrapper is CustomToolWrapper (https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #2). + + var handler_key := "custom:" + spec.name + var wrapper_path := "res://addons/godot_ai/custom_tools/custom_tool_wrapper.gd" + _dispatcher.register_lazy_handler(handler_key, wrapper_path, [spec, _locator]) + _dispatcher.register_lazy("custom_tool:" + spec.name, handler_key, &"invoke") + + +func unregister(name: String) -> bool: + var spec: McpCustomToolSpec = _specs.get(name) + if spec == null: + return false + if _dispatcher != null: + _dispatcher.unregister("custom_tool:" + name, "custom:" + name) + _specs.erase(name) + _erase_from_source_path_index_locked(spec) + tools_changed.emit() + return true + + +## https://github.com/hi-godot/godot-ai/issues/781#issuecomment-5036376599 #8: batch-unregister all tools from one addon. Pass the source_path +## (plugin.cfg path) — the registry removes every spec whose source_path matches. +func unregister_source(source_path: String) -> int: + var specs: Array = _by_source_path.get(source_path, []) + var count := specs.size() + for spec in specs.duplicate(): + if _dispatcher != null: + _dispatcher.unregister("custom_tool:" + spec.name, "custom:" + spec.name) + _specs.erase(spec.name) + _by_source_path.erase(source_path) + if count > 0: + tools_changed.emit() + return count + + +func all() -> Array[McpCustomToolSpec]: + var out: Array[McpCustomToolSpec] = [] + for spec in _specs.values(): + out.append(spec) + return out + + +## Enabled specs only — the catalog-push source. Disabled tools stay +## registered (the dock still lists them for re-enabling) but are never +## advertised to the server and are rejected at dispatch. +func enabled() -> Array[McpCustomToolSpec]: + var out: Array[McpCustomToolSpec] = [] + for spec in _specs.values(): + if is_tool_enabled(spec.name): + out.append(spec) + return out + + +# --- per-tool enable state (dock UI) --- +## Persisted per-project via EditorSettings project metadata (the same +## store the editor uses for per-project UI state — no project.godot +## churn, no cross-project bleed). Applies LIVE: toggling re-emits +## tools_changed, which re-pushes the filtered catalog to the server. + +const _META_SECTION := "godot_ai" +const _META_KEY_DISABLED := "disabled_custom_tools" + +var _disabled_tools: Dictionary = {} # name -> true + + +func is_tool_enabled(name: String) -> bool: + return not _disabled_tools.has(name) + + +func set_tool_enabled(name: String, tool_enabled: bool) -> void: + if tool_enabled: + if not _disabled_tools.has(name): + return + _disabled_tools.erase(name) + else: + if _disabled_tools.has(name): + return + _disabled_tools[name] = true + _save_disabled_tools() + tools_changed.emit() + + +func _load_disabled_tools() -> void: + _disabled_tools.clear() + var es := _editor_settings() + if es == null: + return + var stored: Variant = es.get_project_metadata(_META_SECTION, _META_KEY_DISABLED, PackedStringArray()) + for name in PackedStringArray(stored): + _disabled_tools[String(name)] = true + + +func _save_disabled_tools() -> void: + var es := _editor_settings() + if es == null: + return + var names := PackedStringArray() + for name in _disabled_tools.keys(): + names.append(String(name)) + es.set_project_metadata(_META_SECTION, _META_KEY_DISABLED, names) + + +static func _editor_settings() -> EditorSettings: + if not Engine.is_editor_hint(): + return null + return EditorInterface.get_editor_settings() + + +func get_spec(name: String) -> McpCustomToolSpec: + var out: McpCustomToolSpec = _specs.get(name) + return out + + +func is_ready() -> bool: + return _ready + + +## Called from plugin.gd teardown — wipes everything so stale specs/Callables +## don't survive a Godot AI reload (#46 regression class). Signals die with +## the instance (consumers disconnect via plugin.gd's own teardown). +func clear() -> void: + _specs.clear() + _by_source_path.clear() + _disabled_tools.clear() # in-memory only; persistence reloads on next setup() + _ready = false + _dispatcher = null + _locator = null + _instance = null + + +## Called from plugin.gd _enter_tree after setup(). Addons that missed +## _enter_tree during a Godot AI reload listen for registry_ready (via +## get_instance().registry_ready.connect(...)) and re-register deterministically. +func mark_ready() -> void: + _ready = true + registry_ready.emit() + + +# --- internal helpers --- + +func _erase_from_source_path_index_locked(spec: McpCustomToolSpec) -> void: + var specs: Array = _by_source_path.get(spec.source_path, []) + specs.erase(spec) + if specs.is_empty(): + _by_source_path.erase(spec.source_path) + + +## Read [plugin] name from a plugin.cfg for display purposes. +## Returns "" on any error — display source is best-effort. +static func _read_plugin_name(plugin_cfg_path: String) -> String: + var cfg := ConfigFile.new() + if cfg.load(plugin_cfg_path) != OK: + return "" + return cfg.get_value("plugin", "name", "") + +static func _get_command_name(spec: McpCustomToolSpec) -> String: + return "custom_tool:" + spec.name + +static func _get_handler_name(spec: McpCustomToolSpec) -> String: + return "custom:" + spec.name diff --git a/addons/godot_ai/custom_tools/mcp_tool_registry.gd.uid b/addons/godot_ai/custom_tools/mcp_tool_registry.gd.uid new file mode 100644 index 0000000..23b9822 --- /dev/null +++ b/addons/godot_ai/custom_tools/mcp_tool_registry.gd.uid @@ -0,0 +1 @@ +uid://bq2btxtm8flhb diff --git a/addons/godot_ai/debugger/mcp_debugger_plugin.gd b/addons/godot_ai/debugger/mcp_debugger_plugin.gd new file mode 100644 index 0000000..bfa8e10 --- /dev/null +++ b/addons/godot_ai/debugger/mcp_debugger_plugin.gd @@ -0,0 +1,1699 @@ +@tool +class_name McpDebuggerPlugin +extends EditorDebuggerPlugin + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Editor-side half of the game-process capture bridge. +## +## The game-side counterpart (`plugin/addons/godot_ai/runtime/game_helper.gd`, +## registered as autoload `_mcp_game_helper`) listens on EngineDebugger's +## message channel. This plugin sends "mcp:take_screenshot" requests and +## routes the replies back through the WebSocket McpConnection using the +## request_id the MCP dispatcher threaded through params. +## +## Why this exists: the game always runs as a separate OS process. Even +## "Embed Game Mode" on Windows/Linux (and macOS 4.5+) just reparents the +## game's window into the editor — the game's framebuffer is never reachable +## from the editor's Viewport. The debugger channel is the engine's own +## supported IPC and works identically regardless of embed mode. + +const CAPTURE_PREFIX := "mcp" +## CI runners under xvfb can be slow to spin up the game subprocess and +## register the autoload's capture. 8s keeps the message responsive for +## interactive users while still covering slow-CI startup. +const DEFAULT_TIMEOUT_SEC := 8.0 +## How long to wait for the game-side autoload to beacon mcp:hello +## before sending the screenshot request. Godot's debugger drops +## messages whose prefix has no registered capture, so sending +## take_screenshot before the game registers its "mcp" capture is a +## silent black hole. On CI the game subprocess has been observed +## taking ~15s to boot + register. +const GAME_READY_WAIT_SEC := 20.0 +## #500: how long to wait for the game-side autoload to beacon mcp:hello before +## issuing a game_eval. This is deliberately MUCH shorter than the 20s +## screenshot wait above: the eval path's total editor-side budget is this wait +## plus the 250ms liveness probe and 10s eval backstop +## (request_game_eval's timeout_sec), and that total MUST stay below the 15s +## game_eval timeout enforced at two layers: the Python server's send_command +## budget (src/godot_ai/handlers/editor.py::game_eval) and this plugin's own +## deferred budget (dispatcher.gd's 15000ms game_eval entry, editor/plugin-side +## — not server-side). Either firing produces the opaque tail. +## With the 20s screenshot wait, a not-yet-ready game made the editor poll past +## the 15s deadline, so the server gave up first with an opaque +## ~15s TimeoutError instead of the actionable "Is the game actually running?" +## error below ever reaching the client (#500's residual TimeoutError bucket). +## 3s wait + 0.25s probe + 10s backstop = 13.25s, comfortably under the 15s +## server timeout, so the actionable error always wins. A game launched moments +## before the eval still has the 3s grace to register; if it needs longer, the +## user gets a fast, clear "is it running?" rather than a 15s hang. +const EVAL_READY_WAIT_SEC := 3.0 +## #859: once the helper has registered, confirm its game loop is still +## advancing before dispatching an eval. The helper replies synchronously from +## the debugger capture, so 250ms is ample while keeping not-ready failures +## below the telemetry target of 0.5s. +const EVAL_LIVENESS_WAIT_SEC := 0.25 +## #490: how long to wait for the game's mcp:eval_compiled beacon before +## concluding the eval source failed to compile. A parse error aborts the +## game-side handler before it can reply, so without this we'd wait the +## full eval timeout for a syntax mistake. reload() of valid source is +## sub-millisecond, so 3s is comfortably clear of false positives. +const EVAL_COMPILE_GRACE_SEC := 3.0 +## #490: once an eval compiles, the editor polls the game every this many +## seconds with mcp:eval_check. A backgrounded play-in-editor game has a +## frozen idle loop (no _process / SceneTreeTimer ticks) so it can't +## self-report a runtime error that aborted the eval — but its debugger +## capture callback still answers a probe. The editor's own loop keeps +## ticking, so it drives the poll. 0.35s keeps detection well under a second +## without flooding the channel; most evals reply before the first probe. +const EVAL_PROBE_INTERVAL_SEC := 0.35 + +const VisionRoutingScript := preload("res://addons/godot_ai/vision_routing.gd") + +var _log_buffer: McpLogBuffer +var _game_log_buffer: McpGameLogBuffer +var _editor_log_buffer: McpEditorLogBuffer +var _surfaced_error_tracker +var vision_routing: VisionRoutingScript = null + +## Pending request_id -> phase-specific data. Every eval phase carries kind +## and connection; timer-backed phases also retain their bound timeout lambda +## so `_clear_pending` can disconnect it on success/error. Otherwise the +## SceneTreeTimer pins the captured request_id until its timeout elapses. +var _pending: Dictionary = {} + +## Testing seam for the readiness wait below. Production leaves this invalid +## and awaits SceneTree.process_frame; editor tests inject a synchronous +## callable because their runner does not pump frames while a test is running. +var _eval_ready_frame_waiter: Callable = Callable() + +## Flipped true when the game-side autoload sends its "mcp:hello" boot +## beacon for the current project_run. Reset as soon as a new run is +## requested, before Godot has attached the fresh debugger session, so +## editor_state cannot leak readiness from the previous game process. +var _game_ready := false +var _game_run_token := 0 +var _ready_run_token := -1 +var _game_session_id := -1 +var _game_run_active := false +## Debugger session id of an `mcp:hello` that arrived before the run was +## adopted, or -1 when none is held (#891). A manually started play can beat +## its own adoption: the helper's boot beacon is a one-shot, so discarding it +## left the runtime bridge dead for the whole run with no retry. Buffer it and +## replay on adoption instead. Cleared whenever a run ends, so a beacon can +## never carry across into a later run. +var _pending_hello_session_id := -1 +## True when holding a beacon already rotated the game-log run id, so the +## adoption that consumes it must not rotate again (#891 review). +var _pre_adoption_log_rotated := false +var _manual_run_armed := false +var _game_run_started_msec := 0 +var _game_run_started_editor_cursor := 0 +var _game_run_started_debugger_cursor := 0 +var _game_helper_expected := true + +## #645: a GDScript parse error hit while an editor-launched game boots calls +## GDScriptLanguage::debug_break_parse — the game parks in a remote-debugger +## break BEFORE the helper's mcp:hello and before any record reaches the +## Errors tab, the editor Logger, or the game log. The only editor-side traces +## are the debugger break signals; the stack frames land in the Stack Trace +## panel a few frames later. Track the break here so game_status can report +## status="break" and a synthesized error record can name the failure. +var _break_active := false +var _break_can_debug := false +var _break_reason := "" +var _break_pre_live := false +var _break_run_token := -1 +var _break_record_synthesized := false + +## #645: how long after the break signal to scrape the Stack Trace panel for +## frames. The editor requests the stack dump from the game separately, so the +## panel is empty at signal time; ~0.5s has it populated. The late tick +## synthesizes with whatever is available so a scrape failure still yields a +## record carrying the break reason. +const BREAK_FRAME_SCRAPE_DELAYS_SEC: Array[float] = [0.5, 2.0] + + + +func _init(log_buffer: McpLogBuffer = null, game_log_buffer: McpGameLogBuffer = null, editor_log_buffer: McpEditorLogBuffer = null, surfaced_error_tracker = null, vision_routing: VisionRoutingScript = null) -> void: + _log_buffer = log_buffer + _game_log_buffer = game_log_buffer + _editor_log_buffer = editor_log_buffer + _surfaced_error_tracker = surfaced_error_tracker + self.vision_routing = vision_routing + + +func _has_capture(prefix: String) -> bool: + return prefix == CAPTURE_PREFIX + + +## Fires when a debugger session attaches — once for the editor's own +## self-session at startup, and again each time the user hits Play and a +## new game subprocess connects. Reset _game_ready so the next capture +## request waits for the (new) game's mcp:hello beacon before sending, +## avoiding stale-flag timeouts across Play→Stop→Play cycles. +## +## Do NOT log here: add_debugger_plugin() triggers this virtual before +## plugin.gd's _enter_tree logs "plugin loaded", and ci-reload-test +## asserts "plugin loaded" is the first line after a plugin reload. +func _setup_session(session_id: int) -> void: + _connect_session_stopped(session_id) + _connect_session_break_signals(session_id) + if EditorInterface.is_playing_scene() and not _game_run_active: + _begin_game_run_tracking(_editor_log_cursor(), true, true, true, true, true) + else: + _game_ready = false + _ready_run_token = -1 + _game_session_id = session_id + + +func begin_game_run(editor_log_cursor: int = 0, helper_expected: bool = true) -> void: + _begin_game_run_tracking(editor_log_cursor, helper_expected, true, true) + + +func _begin_game_run_tracking( + editor_log_cursor: int = 0, + helper_expected: bool = true, + rotate_game_log: bool = true, + sticky_debugger_scan: bool = true, + quiet: bool = false, + manual_armed: bool = false, + keep_session_id: int = -1, +) -> void: + _game_run_token += 1 + _game_run_active = true + _manual_run_armed = manual_armed + _game_ready = false + _ready_run_token = -1 + ## Adopting a run whose game is ALREADY attached keeps that session id + ## (#891 review): clearing it would leave every staleness guard comparing + ## against -1, so a foreign session's `stopped` could end this live run — + ## `_on_debugger_session_stopped` lets a manual-armed run end on any + ## session while the id is unknown. Spawn-first callers pass -1 and keep + ## the historical clear, since their game has not attached yet. + _game_session_id = keep_session_id + clear_debug_break() + _game_run_started_msec = Time.get_ticks_msec() + _game_run_started_editor_cursor = maxi(0, editor_log_cursor) + if _surfaced_error_tracker != null: + _surfaced_error_tracker.note_game_run_started(sticky_debugger_scan) + _game_run_started_debugger_cursor = _surfaced_error_tracker.debugger_promoted_total() + else: + _game_run_started_debugger_cursor = 0 + _game_helper_expected = helper_expected + var run_id := "" + if _game_log_buffer and rotate_game_log: + if _pre_adoption_log_rotated: + ## Already rotated when this game's beacon was held, so its boot + ## output is tagged with the run id this adoption is about to + ## announce. Rotating again here would orphan those lines under a + ## superseded id and `logs_read(source="game")` — which returns the + ## CURRENT run only — would report an empty log for a game whose + ## only output happens in `_ready()` (#891 review). + run_id = _game_log_buffer.run_id() + else: + run_id = _game_log_buffer.clear_for_new_run() + _pre_adoption_log_rotated = false + if _log_buffer and not quiet: + var log_text := "[debug] game capture pending run token %d" % _game_run_token + if not run_id.is_empty(): + log_text += " (run %s)" % run_id + _log_buffer.log(log_text) + ## #891: a beacon that beat this adoption is held rather than dropped — + ## consume it now so the bridge comes up without waiting for a second + ## hello the game will never send. + _replay_pending_hello() + + +func _editor_log_cursor() -> int: + return _editor_log_buffer.appended_total() if _editor_log_buffer != null else 0 + + +func end_game_run() -> void: + _fail_pending_evals_not_ready( + "The game run ended before game_eval completed — the game stopped, crashed, or is restarting. Confirm it is running and retry." + ) + ## Never carry a held beacon across a run boundary (#891). + _pending_hello_session_id = -1 + _pre_adoption_log_rotated = false + _game_run_active = false + _manual_run_armed = false + _game_ready = false + _ready_run_token = -1 + _game_session_id = -1 + clear_debug_break() + if _surfaced_error_tracker != null: + _surfaced_error_tracker.note_game_run_stopped() + + +## Editor play-state edge, stopped -> playing (#891). `_setup_session` adopts a +## manually started play only when `EditorInterface.is_playing_scene()` is +## ALREADY true at the instant Godot attaches the debugger session — an F5/F6 +## launch routinely loses that race, and the run was then never adopted at all, +## leaving game_eval, game logs and runtime inspection silently dead for its +## whole lifetime. This closes the race from the other side: whichever of the +## two edges lands second performs the adoption. No-op for MCP-started runs, +## which `project_run` already adopted via `begin_game_run`. +func note_editor_play_started() -> void: + if _game_run_active: + return + ## State belonging to the game that is already talking must survive the + ## adoption that is about to reset run bookkeeping (#891 review). + var attached_session := _game_session_id + var had_break := _break_active + var break_can_debug := _break_can_debug + var break_reason := _break_reason + _begin_game_run_tracking( + _editor_log_cursor(), true, true, true, true, true, attached_session + ) + if had_break: + ## A boot parse error can break the game before the play-state edge + ## lands. `_begin_game_run_tracking` clears break state, which would + ## drop the actionable #645 diagnosis and leave game_status reporting + ## "not_live" instead of "break". Re-record it against the new run so + ## `_break_pre_live` and the synthetic-error scan are computed for THIS + ## run — the beacon will never arrive for a game parked at a break. + note_debug_break(break_can_debug, break_reason) + + +## Authoritative fallback for runs whose debugger `stopped` signal never +## fired or was never connected: the editor's play state falling to stopped +## means the game process is gone. A game that exits on its own +## (get_tree().quit(), crash) has no MCP stop op to run the bookkeeping, and +## without this game_status stayed "live" until the next run (#642 smoke). +## Called on the playing→stopped edge only, so the pre-play launch window +## (run tracking begun, is_playing_scene() not yet true) is never clipped. +func note_editor_play_stopped() -> void: + if not _game_run_active: + ## A beacon held for an adoption that never happened must not survive + ## into the next run (#891). + _pending_hello_session_id = -1 + _pre_adoption_log_rotated = false + return + end_game_run() + + +## Apply the game helper's boot beacon: the game has registered its "mcp" +## capture and is safe to send take_screenshot / eval requests to — before +## this, Godot's debugger drops our messages silently. Shared by the live +## `mcp:hello` branch in `_capture` and by the buffered replay in +## `_replay_pending_hello`, so a held beacon produces exactly the same state +## and side effects as one that arrived after adoption (#891). +func _accept_game_hello(session_id: int) -> void: + _pending_hello_session_id = -1 + ## Bind the run to the game that actually announced itself. Adoption + ## clears `_game_session_id`, so without this a replayed beacon would + ## leave the run bound to nothing and the staleness checks toothless + ## until Godot's next `_setup_session` (#891 review). + if session_id != -1: + _game_session_id = session_id + _game_ready = true + _ready_run_token = _game_run_token + ## #641: boot-time parse errors race the hello beacon — both ride + ## the same debugger channel, and the editor inserts Errors-tab + ## rows with a per-frame throttle, so rows can land moments after + ## the run is declared live. Arm forced scans so those rows get + ## promoted into the watermark even if no tool call follows. + if _surfaced_error_tracker != null: + _surfaced_error_tracker.schedule_deferred_scans() + if _log_buffer: + if _game_log_buffer: + _log_buffer.log("[debug] <- mcp:hello from game_helper (run %s)" % _game_log_buffer.run_id()) + else: + _log_buffer.log("[debug] <- mcp:hello from game_helper") + + +## Consume a beacon that arrived before this run was adopted. Called at the end +## of run-tracking setup; no-op when nothing is held (#891). +func _replay_pending_hello() -> void: + if _pending_hello_session_id == -1: + return + var held := _pending_hello_session_id + if _game_session_id != -1 and held != _game_session_id: + ## Belongs to a different debugger session than the one this run is + ## bound to — drop it rather than declare the wrong game live. + _pending_hello_session_id = -1 + if _log_buffer: + _log_buffer.log("[debug] dropped held mcp:hello from debugger session %d (current %d)" % [held, _game_session_id]) + return + if _log_buffer: + _log_buffer.log("[debug] replaying held mcp:hello from debugger session %d" % held) + _accept_game_hello(held) + + +func _connect_session_stopped(session_id: int) -> void: + var session = get_session(session_id) + if session == null: + return + var stopped := Callable(self, "_on_debugger_session_stopped").bind(session_id) + if not session.stopped.is_connected(stopped): + session.stopped.connect(stopped) + + +func _on_debugger_session_stopped(session_id: int) -> void: + if _game_session_id != -1 and session_id != _game_session_id: + return + ## MCP-started runs normally end via project_manage(op="stop"), but a game + ## that exits on its own (get_tree().quit(), crash) emits only this signal. + ## Without ending the run here, game_status stays "live" until the next + ## run's bookkeeping rewrites it (#642 live smoke). Before the game session + ## attaches (_game_session_id == -1) only manual runs may end on this + ## signal — a foreign session's stop must not cancel a launching MCP run. + if not _manual_run_armed and _game_session_id == -1: + return + end_game_run() + + +## #859: a closed debugger session is authoritative. Do not leave evals on +## their 10s backstop after the game process has already gone away. Other +## pending request kinds keep their existing ownership and timeout behavior. +func _fail_pending_evals_not_ready(message: String) -> void: + for request_id in _pending.keys(): + var pending: Dictionary = _pending.get(request_id, {}) + if str(pending.get("kind", "")) not in [ + "eval_ready_wait", "eval_liveness", "eval" + ]: + continue + var connection: McpConnection = pending.get("connection") + _clear_pending(str(request_id)) + if connection != null and is_instance_valid(connection): + _send_error(connection, str(request_id), ErrorCodes.EVAL_GAME_NOT_READY, message) + + +func _is_current_game_run(run_token: int) -> bool: + return _game_run_active and _game_run_token == run_token + + +func _fail_eval_not_ready(request_id: String, message: String) -> void: + var pending: Dictionary = _pending.get(request_id, {}) + var connection: McpConnection = pending.get("connection") + _clear_pending(request_id) + if connection != null and is_instance_valid(connection): + _send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY, message) + + +## --- #645: boot-time debugger breaks --------------------------------------- + +func _connect_session_break_signals(session_id: int) -> void: + var session = get_session(session_id) + if session != null: + var breaked_cb := Callable(self, "_on_debugger_session_breaked").bind(session_id) + if not session.breaked.is_connected(breaked_cb): + session.breaked.connect(breaked_cb) + var continued_cb := Callable(self, "_on_debugger_session_continued").bind(session_id) + if not session.continued.is_connected(continued_cb): + session.continued.connect(continued_cb) + _connect_script_debugger_breaked() + + +## The session-level `breaked` signal carries only can_debug; the underlying +## ScriptEditorDebugger's own `breaked` also carries the human-readable break +## reason ("Parser Error: ..."), which is otherwise visible only in the +## Debugger UI. EditorDebuggerSession does not expose its debugger node, so +## locate ScriptEditorDebugger instances by walking the editor UI — the same +## approach as the tracker's Errors-tab scrape. +func _connect_script_debugger_breaked() -> void: + var base := EditorInterface.get_base_control() + if base == null: + return + var debuggers: Array[Node] = [] + _collect_nodes_of_class(base, "ScriptEditorDebugger", debuggers) + for dbg in debuggers: + if not dbg.has_signal("breaked"): + continue + var cb := Callable(self, "_on_script_debugger_breaked") + if not dbg.is_connected("breaked", cb): + dbg.connect("breaked", cb) + + +static func _collect_nodes_of_class(node: Node, klass: String, out: Array[Node]) -> void: + if node.get_class() == klass: + out.append(node) + for child in node.get_children(): + _collect_nodes_of_class(child, klass, out) + + +func _on_debugger_session_breaked(can_debug: bool, session_id: int) -> void: + if _game_session_id != -1 and session_id != _game_session_id: + return + note_debug_break(can_debug, "") + + +func _on_debugger_session_continued(session_id: int) -> void: + if _game_session_id != -1 and session_id != _game_session_id: + return + clear_debug_break() + + +## reallydid=false is Godot's "left the break" notification (debug_exit). +func _on_script_debugger_breaked(reallydid: bool, can_debug: bool, reason: String, _has_stackdump: bool) -> void: + if not reallydid: + clear_debug_break() + return + note_debug_break(can_debug, reason) + + +## Record that the game process is parked in a remote-debugger break. Fires +## once per break from the session signal (no reason text) and again moments +## later from the ScriptEditorDebugger signal (with reason) — the notices +## merge into one break. Public so tests can drive break state directly. +func note_debug_break(can_debug: bool, reason: String) -> void: + var first_notice := not _break_active + _break_active = true + _break_can_debug = can_debug + if not reason.is_empty(): + _break_reason = reason + if not first_notice: + return + _break_run_token = _game_run_token + _break_pre_live = _game_run_active and not is_game_capture_ready() + _break_record_synthesized = false + if _log_buffer: + _log_buffer.log("[debug] debugger break (pre_live=%s can_debug=%s)" % [str(_break_pre_live), str(can_debug)]) + if _break_pre_live: + _schedule_break_record_synthesis() + + +func clear_debug_break() -> void: + _break_active = false + _break_can_debug = false + _break_reason = "" + _break_pre_live = false + _break_run_token = -1 + _break_record_synthesized = false + + +## Stack frames land in the Stack Trace panel a few frames after the break +## signal (the editor requests the stack dump separately), so the record is +## synthesized on short timers rather than at signal time. +func _schedule_break_record_synthesis() -> void: + var tree := Engine.get_main_loop() as SceneTree + if tree == null: + return + var token := _break_run_token + for i in BREAK_FRAME_SCRAPE_DELAYS_SEC.size(): + var final := i == BREAK_FRAME_SCRAPE_DELAYS_SEC.size() - 1 + var timer := tree.create_timer(BREAK_FRAME_SCRAPE_DELAYS_SEC[i]) + timer.timeout.connect(func() -> void: _on_break_scrape_tick(token, final)) + + +func _on_break_scrape_tick(run_token: int, final: bool) -> void: + if not _break_active or _break_record_synthesized or run_token != _break_run_token: + return + var frames := _scrape_break_stack_frames() + if frames.is_empty() and not final: + return + synthesize_break_error_record(frames) + + +## Read the debugger's Stack Trace panel rows. Row metadata is a Dictionary +## {frame, file, function, line} regardless of editor locale, so stack trees +## are identified by metadata shape rather than the translated column title. +func _scrape_break_stack_frames() -> Array[Dictionary]: + var base := EditorInterface.get_base_control() + if base == null: + return [] + var debuggers: Array[Node] = [] + _collect_nodes_of_class(base, "ScriptEditorDebugger", debuggers) + for dbg in debuggers: + var trees: Array[Node] = [] + _collect_nodes_of_class(dbg, "Tree", trees) + for t in trees: + var frames := _frames_from_stack_tree(t as Tree) + if not frames.is_empty(): + return frames + return [] + + +static func _frames_from_stack_tree(tree: Tree) -> Array[Dictionary]: + var frames: Array[Dictionary] = [] + var root := tree.get_root() + if root == null: + return frames + var item := root.get_first_child() + while item != null: + var meta = item.get_metadata(0) + if not (meta is Dictionary and meta.has("file") and meta.has("frame")): + return [] + frames.append({ + "path": str(meta.get("file", "")), + "line": int(meta.get("line", 0)), + "function": str(meta.get("function", "")), + }) + item = item.get_next() + return frames + + +## Build the Errors-tab-shaped record for a boot-time break and promote it via +## the tracker so recent_editor_errors_since / logs_read / the watermark all +## surface it — the break itself produces no record anywhere else (#645). +## Public so tests can synthesize without waiting on scrape timers. +func synthesize_break_error_record(frames: Array[Dictionary]) -> void: + if _break_record_synthesized: + return + _break_record_synthesized = true + if _surfaced_error_tracker == null: + return + var reason := _break_reason + if reason.is_empty(): + reason = "Game process broke into the debugger during startup (script parse/load error; reason not captured)" + var top: Dictionary = frames[0] if not frames.is_empty() else {} + var location := { + "path": str(top.get("path", "")), + "line": int(top.get("line", 0)), + "function": str(top.get("function", "")), + } + var entry := { + "source": "editor", + "level": "error", + "text": reason, + "path": location["path"], + "line": location["line"], + "function": location["function"], + "details": { + "debugger_tab": "Stack Trace", + "message": reason, + "error_type_name": "debugger_break", + "source": location.duplicate(true), + "resolved": location.duplicate(true), + "frames": frames.duplicate(true), + }, + } + _surfaced_error_tracker.record_synthetic_error(entry) + if _log_buffer: + _log_buffer.log("[debug] synthesized boot-break error record: %s" % McpSurfacedErrorTracker.format_editor_error_summary(entry)) + + +## --- end #645 --------------------------------------------------------------- + + +func is_game_capture_ready() -> bool: + return _game_run_active and _game_ready and _ready_run_token == _game_run_token + + +static func with_liveness_flags(status: Dictionary) -> Dictionary: + var enriched := status.duplicate(true) + var state := str(enriched.get("status", "stopped")) + enriched["helper_live"] = state == "live" + enriched["session_active"] = not state in ["not_live", "stopped"] + return enriched + + +func get_game_status(now_msec: int = -1, ready_wait_sec: float = GAME_READY_WAIT_SEC) -> Dictionary: + var resolved_now := Time.get_ticks_msec() if now_msec < 0 else now_msec + var ready_wait_msec := maxi(0, int(ready_wait_sec * 1000.0)) + var elapsed_msec := maxi(0, resolved_now - _game_run_started_msec) if _game_run_active else 0 + ## "stopped" also covers idle/never-ran; no game run is currently active. + var status := "stopped" + if _game_run_active: + ## #645: a parked process takes precedence over "live" — a game frozen + ## in a remote-debugger break cannot service game-side tools even when + ## its helper registered before the break. + if _break_active: + status = "break" + elif is_game_capture_ready(): + status = "live" + elif not _game_helper_expected: + status = "no_helper" + elif elapsed_msec >= ready_wait_msec: + status = "not_live" + else: + status = "launching" + var out := { + "status": status, + "run_token": _game_run_token, + "active": _game_run_active, + "ready": is_game_capture_ready(), + "helper_expected": _game_helper_expected, + "run_started_msec": _game_run_started_msec, + "elapsed_msec": elapsed_msec, + "ready_wait_msec": ready_wait_msec, + "editor_log_cursor": _game_run_started_editor_cursor, + } + if status == "break": + out["break"] = { + "reason": _break_reason, + "can_debug": _break_can_debug, + "pre_live": _break_pre_live, + } + return with_liveness_flags(out) + + +func _explain_not_live(status: Dictionary, code: String = ErrorCodes.INTERNAL_ERROR) -> Dictionary: + var state := str(status.get("status", "stopped")) + var errors_info := recent_editor_errors_since(int(status.get("editor_log_cursor", 0))) + var recent_errors: Array = errors_info.get("errors", []) + var recent_errors_scope := str(errors_info.get("scope", "none")) + var truncated := bool(errors_info.get("truncated", false)) + var data := { + "game_status": status.duplicate(true), + "recent_errors": recent_errors, + "recent_errors_scope": recent_errors_scope, + "recent_errors_may_predate_run": recent_errors_scope == "retained_recent", + "recent_errors_truncated": truncated, + } + data.merge(split_errors_by_scope(recent_errors, recent_errors_scope), true) + var message := "" + match state: + "not_live": + if not recent_errors.is_empty() and recent_errors_scope == "run": + message = "The game failed to load or crashed before the Godot AI game helper registered: %s. Check logs_read(source='editor', include_details=true)." % _format_editor_error_summary(recent_errors[0]) + if truncated: + message += " Editor logs since this run may be truncated; showing retained errors." + elif not recent_errors.is_empty(): + message = "The game is not responding and reported no load errors during this run. A recent editor error may be related, but may predate this run: %s. Check logs_read(source='editor', include_details=true)." % _format_editor_error_summary(recent_errors[0]) + else: + message = "The game is not responding and reported no load errors before the helper-ready window elapsed. It may still be booting or may have failed silently; check logs_read(source='editor', include_details=true) and retry." + "break": + var break_info: Dictionary = status.get("break", {}) + var break_reason := str(break_info.get("reason", "")) + var reason_suffix := (": %s" % break_reason) if not break_reason.is_empty() else "" + if bool(break_info.get("pre_live", true)): + message = "The game hit a script error during startup and is frozen at a debugger break%s. It cannot become live; call project_manage(op='stop') to end the run, fix the error, and relaunch. Check logs_read(source='editor', include_details=true)." % reason_suffix + else: + message = "The game is paused at a debugger break%s. Resume it from the editor's Debugger panel or call project_manage(op='stop')." % reason_suffix + "no_helper": + message = "The running game has no _mcp_game_helper autoload, so game-side tools cannot connect. If this is a headless or custom-main-loop project, use editor_screenshot(source='viewport') where applicable. Otherwise, re-enable the plugin and relaunch the game." + "launching": + message = "The game is still starting (%.1fs elapsed); the Godot AI game helper has not registered yet. Retry shortly." % (float(status.get("elapsed_msec", 0)) / 1000.0) + "stopped": + message = "The game is not running. Start the project and retry the game-side tool." + _: + message = "The game-side tool could not confirm the game is live (status=%s). Check logs_read(source='editor', include_details=true) and retry." % state + var err := ErrorCodes.make(code, message) + var inner: Dictionary = err.get("error", {}) + inner["data"] = data + err["error"] = inner + return err + + +static func split_errors_by_scope(recent_errors: Array, scope: String) -> Dictionary: + var current_run_errors: Array = [] + var retained_errors: Array = [] + if scope == "run": + current_run_errors = recent_errors + elif scope == "retained_recent": + retained_errors = recent_errors + return { + "current_run_errors": current_run_errors, + "retained_errors": retained_errors, + } + + +## `force_debugger_scan` bypasses the tracker's scan gate for one read. Keep it +## false on per-frame polling paths (the run-liveness loop) — a forced scan +## walks the Debugger dock UI — and pass true only for one-shot reads that must +## see rows which landed after the last gated scan (#641). +func recent_editor_errors_since(cursor: int, force_debugger_scan: bool = false) -> Dictionary: + return _recent_editor_errors_since(cursor, force_debugger_scan) + + +func _recent_editor_errors_since(cursor: int, force_debugger_scan: bool = false) -> Dictionary: + var out: Array[Dictionary] = [] + var truncated := false + if _surfaced_error_tracker != null: + var captured_by_tracker: Dictionary = _surfaced_error_tracker.editor_entries_since( + maxi(0, cursor), + _game_run_started_debugger_cursor, + force_debugger_scan, + ) + truncated = bool(captured_by_tracker.get("truncated", false)) + for raw_entry in captured_by_tracker.get("entries", []): + var compact := _compact_editor_error(raw_entry) + if compact.is_empty(): + continue + out.append(compact) + if out.size() >= 5: + break + if not out.is_empty(): + return {"errors": out, "truncated": truncated, "scope": "run"} + for raw_entry in _surfaced_error_tracker.retained_recent_editor_entries(): + var compact := _compact_editor_error(raw_entry, true) + if compact.is_empty(): + continue + out.append(compact) + if out.size() >= 5: + break + if not out.is_empty(): + return {"errors": out, "truncated": false, "scope": "retained_recent"} + return {"errors": out, "truncated": false, "scope": "none"} + if _editor_log_buffer == null: + return {"errors": out, "truncated": false, "scope": "none"} + var captured: Dictionary = _editor_log_buffer.get_since(maxi(0, cursor), -1) + truncated = bool(captured.get("truncated", false)) + for raw_entry in captured.get("entries", []): + var compact := _compact_editor_error(raw_entry) + if compact.is_empty(): + continue + out.append(compact) + if out.size() >= 5: + break + if not out.is_empty(): + return {"errors": out, "truncated": truncated, "scope": "run"} + + for raw_entry in _reversed_entries(_editor_log_buffer.get_recent(McpEditorLogBuffer.MAX_LINES)): + var compact := _compact_editor_error(raw_entry, true) + if compact.is_empty(): + continue + out.append(compact) + if out.size() >= 5: + break + if not out.is_empty(): + return {"errors": out, "truncated": false, "scope": "retained_recent"} + return {"errors": out, "truncated": false, "scope": "none"} + + +func _compact_editor_error(raw_entry: Variant, fallback_recent: bool = false) -> Dictionary: + if not raw_entry is Dictionary: + return {} + var entry := raw_entry as Dictionary + if str(entry.get("level", "info")) != "error": + return {} + var path := str(entry.get("path", "")) + if fallback_recent and _is_diagnostic_noise_path(path): + return {} + var compact := { + "source": "editor", + "level": "error", + "text": str(entry.get("text", "")), + "path": path, + "line": int(entry.get("line", 0)), + "function": str(entry.get("function", "")), + } + if entry.has("details"): + compact["details"] = entry["details"].duplicate(true) + return compact + + +func _is_diagnostic_noise_path(path: String) -> bool: + return path.begins_with("res://addons/godot_ai/") or path.begins_with("res://tests/") + + +func _reversed_entries(entries: Array[Dictionary]) -> Array[Dictionary]: + var out: Array[Dictionary] = [] + for i in range(entries.size() - 1, -1, -1): + out.append(entries[i]) + return out + + +func _format_editor_error_summary(entry: Dictionary) -> String: + return McpSurfacedErrorTracker.format_editor_error_summary(entry) + + +func _capture(message: String, data: Array, session_id: int) -> bool: + ## Godot passes the full "prefix:tail" string as `message`. + match message: + "mcp:screenshot_response": + _on_screenshot_response(data) + return true + "mcp:screenshot_error": + _on_screenshot_error(data) + return true + "mcp:log_batch": + _on_log_batch(data) + return true + "mcp:hello": + ## Staleness is checked FIRST, before the buffering branch below: + ## `_begin_game_run_tracking` clears `_game_session_id`, so a beacon + ## validated only at replay time could never be rejected (#891 + ## review). A beacon from a session other than the attached one is + ## some other game's — never hold it, never apply it. + if _game_session_id != -1 and session_id != _game_session_id: + if _log_buffer: + _log_buffer.log("[debug] ignored stale mcp:hello from debugger session %d (current %d)" % [session_id, _game_session_id]) + return true + if not _game_run_active: + ## #891: the run is not adopted YET — a manually started play + ## whose debugger session attached before the editor flipped + ## `is_playing_scene()` lands here. The beacon is a one-shot, + ## so hold it for the imminent adoption instead of dropping it + ## (which left game_eval waiting forever for a hello that had + ## already been thrown away). + _pending_hello_session_id = session_id + ## The beacon is this game's first word, and its boot output + ## follows immediately (the helper flushes on its first + ## `_process`). Rotate the run id NOW so those lines are tagged + ## with the identity adoption will announce, instead of landing + ## under the previous run and vanishing from + ## `logs_read(source="game")` (#891 review). + if _game_log_buffer and not _pre_adoption_log_rotated: + _game_log_buffer.clear_for_new_run() + _pre_adoption_log_rotated = true + if _log_buffer: + _log_buffer.log("[debug] holding mcp:hello from debugger session %d until the run is adopted" % session_id) + return true + _accept_game_hello(session_id) + return true + "mcp:eval_liveness_response": + _on_eval_liveness_response(data) + return true + "mcp:eval_response": + _on_eval_response(data) + return true + "mcp:eval_error": + _on_eval_error(data) + return true + "mcp:eval_ack": + _on_eval_ack(data) + return true + "mcp:eval_compiled": + _on_eval_compiled(data) + return true + "mcp:eval_runtime_error": + _on_eval_runtime_error(data) + return true + "mcp:game_command_response": + _on_game_command_response(data) + return true + "mcp:game_command_error": + _on_game_command_error(data) + return true + return false + + +func _on_log_batch(data: Array) -> void: + if _game_log_buffer == null: + return + ## data layout: [[[level, text, details?], ...]] + if data.is_empty() or not (data[0] is Array): + return + var entries: Array = data[0] + for entry in entries: + if entry is Dictionary: + var dict_details: Dictionary = {} + var raw_dict_details = entry.get("details", {}) + if raw_dict_details is Dictionary: + dict_details = raw_dict_details + _game_log_buffer.append(str(entry.get("level", "info")), str(entry.get("text", "")), dict_details) + continue + if not (entry is Array) or entry.size() < 2: + continue + var details: Dictionary = {} + if entry.size() > 2 and entry[2] is Dictionary: + details = entry[2] + _game_log_buffer.append(str(entry[0]), str(entry[1]), details) + + +## Request a game-process framebuffer capture over the debugger channel. +## Reply is pushed back through `connection` out-of-band because the MCP +## dispatcher has already returned a deferred-response marker for this +## request_id. Synchronous from the caller's perspective — if the +## game-side autoload hasn't beaconed yet, the wait + send run as a +## fire-and-forget coroutine kicked off from here. Structured this way +## so the call site in EditorHandler stays a plain non-await invocation. +func request_game_screenshot( + request_id: String, + max_resolution: int, + connection: McpConnection, + timeout_sec: float = DEFAULT_TIMEOUT_SEC, +) -> void: + if request_id.is_empty(): + push_warning("MCP debugger: screenshot request missing request_id") + return + + var tree := Engine.get_main_loop() as SceneTree + if tree == null: + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, + "Editor main loop is not a SceneTree — cannot schedule capture") + return + + if is_game_capture_ready(): + _send_take_screenshot(tree, request_id, max_resolution, connection, timeout_sec) + return + + ## Not ready yet — run the wait-then-send flow as a detached + ## coroutine. It keeps itself alive via the signal subscription on + ## tree.process_frame; the caller doesn't need to (and shouldn't) + ## await this entrypoint. + if _log_buffer: + _log_buffer.log("[debug] waiting for game_helper hello (%s)" % request_id) + _wait_then_send(tree, request_id, max_resolution, connection, timeout_sec) + + +## Coroutine: poll each editor frame until the mcp:hello beacon arrives +## (flipping _game_ready true) or the deadline elapses. Once resolved, +## either dispatch the capture or return an actionable timeout error. +func _wait_then_send( + tree: SceneTree, + request_id: String, + max_resolution: int, + connection: McpConnection, + timeout_sec: float, +) -> void: + var deadline := Time.get_ticks_msec() + int(GAME_READY_WAIT_SEC * 1000.0) + ## #645: always yield at least one frame — the dispatcher registers the + ## deferred request only after the handler returns DEFERRED_RESPONSE, so a + ## same-frame error reply would be dropped as an expired request. The break + ## check then bails out with the actionable break error instead of waiting + ## out the full window (a game parked in a debugger break never beacons). + await tree.process_frame + while not is_game_capture_ready() and not _break_active and Time.get_ticks_msec() < deadline: + await tree.process_frame + if not is_game_capture_ready(): + _send_error_response(connection, request_id, + _explain_not_live(get_game_status(-1, GAME_READY_WAIT_SEC), ErrorCodes.INTERNAL_ERROR)) + return + _send_take_screenshot(tree, request_id, max_resolution, connection, timeout_sec) + + +## Send the mcp:take_screenshot message and arm the reply timeout. +## Assumes _game_ready is true. +func _send_take_screenshot( + tree: SceneTree, + request_id: String, + max_resolution: int, + connection: McpConnection, + timeout_sec: float, +) -> void: + var session: EditorDebuggerSession = _first_active_session() + if session == null: + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, + "No active debugger session — is the game actually running and started from this editor?") + return + + var timer: SceneTreeTimer = tree.create_timer(timeout_sec) + var timeout_callable := func() -> void: _on_timeout(request_id) + timer.timeout.connect(timeout_callable) + _pending[request_id] = { + "connection": connection, + "timer": timer, + "timeout_callable": timeout_callable, + } + + session.send_message("mcp:take_screenshot", [request_id, max_resolution]) + if _log_buffer: + _log_buffer.log("[debug] -> mcp:take_screenshot (%s)" % request_id) + + +func _first_active_session() -> EditorDebuggerSession: + for s in get_sessions(): + if s is EditorDebuggerSession and s.is_active(): + return s + return null + + +func _on_screenshot_response(data: Array) -> void: + if data.size() < 6: + push_warning("MCP debugger: malformed screenshot response (expected 6 fields, got %d)" % data.size()) + return + var request_id: String = data[0] + var pending = _pending.get(request_id) + if pending == null: + ## Timed out or unknown — silently drop. + return + _clear_pending(request_id) + + var connection: McpConnection = pending.connection + if connection == null or not is_instance_valid(connection): + return + + var payload := { + "source": "game", + "width": int(data[2]), + "height": int(data[3]), + "original_width": int(data[4]), + "original_height": int(data[5]), + "format": "png", + "image_base64": data[1], + } + ## #777: game helpers append frames_drawn + a stale flag so a capture + ## taken while the game's main loop is frozen (backgrounded window) is + ## honestly labeled instead of timing out. Older helpers send six fields + ## — leave the keys absent rather than guessing. + if data.size() >= 8: + payload["frames_drawn"] = int(data[6]) + payload["stale_frame"] = bool(data[7]) + if bool(data[7]): + payload["note"] = ("The game window appears backgrounded or its main loop is " + + "stalled; returning the last rendered frame. Focus the game window and " + + "retry for a current frame.") + ## Vision Routing: when enabled, describe the frame through the configured + ## vision provider on a + ## worker thread and reply with the text description instead of the raw + ## image (see vision_routing.gd). The router replies for us in that case. + if vision_routing != null and vision_routing.is_routing_enabled(): + if vision_routing.route_game_payload(connection, request_id, {"data": payload}): + return + connection.send_deferred_response(request_id, {"data": payload}) + if _log_buffer: + _log_buffer.log("[debug] <- mcp:screenshot_response (%s)" % request_id) + + +func _on_screenshot_error(data: Array) -> void: + if data.size() < 2: + return + var request_id: String = data[0] + var message: String = data[1] + var pending = _pending.get(request_id) + if pending == null: + return + _clear_pending(request_id) + var connection: McpConnection = pending.connection + if connection == null or not is_instance_valid(connection): + return + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, message) + + +## #777: the 8s reply timer fired — the screenshot request reached (or should +## have reached) the game helper and no reply came back. Mirror the eval +## timeout split (#518): a not-live game gets the attributed +## _explain_not_live payload; a live game gets GAME_HELPER_TIMEOUT instead of +## the former opaque INTERNAL_ERROR. With the game side's stalled-loop +## stale-frame fallback, a live game only lands here when it has nothing +## rendered to fall back on, its debugger servicing is itself wedged, or the +## helper died mid-run. +func _on_timeout(request_id: String) -> void: + var pending = _pending.get(request_id) + if pending == null: + return + _pending.erase(request_id) + var connection: McpConnection = pending.connection + if connection == null or not is_instance_valid(connection): + return + var status := get_game_status(-1, GAME_READY_WAIT_SEC) + var err: Dictionary + if status.get("status", "") != "live": + err = _explain_not_live(status, ErrorCodes.INTERNAL_ERROR) + else: + err = ErrorCodes.make(ErrorCodes.GAME_HELPER_TIMEOUT, + "The game process did not return a frame. The game window may be backgrounded or its main loop blocked — focus the game window and retry, or use game_command to confirm liveness.") + _send_error_response(connection, request_id, err) + if _log_buffer: + _log_buffer.log("[debug] !! screenshot timeout (%s)" % request_id) + + +func _send_error(connection: McpConnection, request_id: String, code: String, message: String) -> void: + _send_error_response(connection, request_id, ErrorCodes.make(code, message)) + + +func _send_error_response(connection: McpConnection, request_id: String, err: Dictionary) -> void: + if connection == null or not is_instance_valid(connection): + return + connection.send_deferred_response(request_id, err) + + +func _clear_pending(request_id: String) -> void: + var pending: Dictionary = _pending.get(request_id, {}) + var timer: SceneTreeTimer = pending.get("timer") + var cb: Callable = pending.get("timeout_callable", Callable()) + if timer != null and timer.timeout.is_connected(cb): + timer.timeout.disconnect(cb) + ## #490: eval requests also carry a compile-grace timer and a runtime probe. + var grace: SceneTreeTimer = pending.get("grace_timer") + var gcb: Callable = pending.get("grace_callable", Callable()) + if grace != null and grace.timeout.is_connected(gcb): + grace.timeout.disconnect(gcb) + var probe: SceneTreeTimer = pending.get("probe_timer") + var pcb: Callable = pending.get("probe_callable", Callable()) + if probe != null and probe.timeout.is_connected(pcb): + probe.timeout.disconnect(pcb) + _pending.erase(request_id) + + +## --- game_eval: execute arbitrary GDScript in the running game --- + +## Editor-side fallback timer for game_eval. MUST stay above the game-side +## EVAL_TIMEOUT_SEC (8.0) in runtime/game_helper.gd and below the dispatcher's +## game_eval budget (15000 ms) in dispatcher.gd — i.e. game 8s < editor 10s < +## dispatcher 15s. This timer only fires when the game never replies at all; +## _on_eval_timeout then attributes the failure (game not live vs never-acked +## vs started-and-hung, #518). Drop timeout_sec at/below 8s and it pre-empts +## the game's more specific "Eval exceeded 8s" message — see the TIMEOUT +## ORDERING note on EVAL_TIMEOUT_SEC. +## +## #500/#859: the *not-ready* path adds EVAL_READY_WAIT_SEC (3s) and the +## EVAL_LIVENESS_WAIT_SEC probe (0.25s) on top of this 10s backstop. That sum +## (13.25s) must also stay below the dispatcher/server 15s budget, or a +## not-yet-ready game makes the server time out opaquely before the editor's +## actionable error returns — exactly the residual ~15s TimeoutError bucket +## #500 tracked down. The cross-file contract is enforced by +## tests/unit/test_game_eval_timeout_ordering.py. +func request_game_eval( + code: String, + request_id: String, + connection: McpConnection, + timeout_sec: float = 10.0, +) -> void: + if request_id.is_empty(): + push_warning("MCP debugger: eval request missing request_id") + return + + var tree := Engine.get_main_loop() as SceneTree + if tree == null: + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, + "Editor main loop is not a SceneTree — cannot schedule eval") + return + + var run_token := _game_run_token + if is_game_capture_ready(): + _probe_then_eval(tree, code, request_id, connection, timeout_sec, run_token) + return + + if _log_buffer: + _log_buffer.log("[debug] waiting for game_helper hello before eval (%s)" % request_id) + _wait_then_eval(tree, code, request_id, connection, timeout_sec, run_token) + + +func _wait_then_eval( + tree: SceneTree, + code: String, + request_id: String, + connection: McpConnection, + timeout_sec: float, + run_token: int, +) -> void: + ## #500: eval uses EVAL_READY_WAIT_SEC (not the 20s GAME_READY_WAIT_SEC) so + ## the not-ready path returns its actionable error before the 15s server-side + ## command timeout fires an opaque TimeoutError. See EVAL_READY_WAIT_SEC. + _pending[request_id] = { + "kind": "eval_ready_wait", + "connection": connection, + "run_token": run_token, + } + var deadline := Time.get_ticks_msec() + int(EVAL_READY_WAIT_SEC * 1000.0) + ## #645: the leading yield guarantees the dispatcher has registered the + ## deferred request before any reply (a same-frame reply is dropped as + ## expired); the break check bails out early because a parked game never + ## registers its capture. + if _eval_ready_frame_waiter.is_valid(): + await _eval_ready_frame_waiter.call() + else: + await tree.process_frame + while ( + _pending.has(request_id) + and _is_current_game_run(run_token) + and not is_game_capture_ready() + and not _break_active + and Time.get_ticks_msec() < deadline + ): + if _eval_ready_frame_waiter.is_valid(): + await _eval_ready_frame_waiter.call() + else: + await tree.process_frame + ## end_game_run() owns the reply once it has cleared this tracked wait. + if not _pending.has(request_id): + return + if not _is_current_game_run(run_token): + _fail_eval_not_ready(request_id, + "The game run changed before game_eval could start — the game stopped or restarted. Retry against the current run.") + return + if not is_game_capture_ready(): + ## #518: EVAL_GAME_NOT_READY (not INTERNAL_ERROR) — the play session is up + ## but the game-side capture didn't register within the short wait. Fast + ## and caller-actionable; classifying it apart from the opaque 10s hang + ## keeps the INTERNAL_ERROR telemetry bucket meaning "the eval truly hung". + _clear_pending(request_id) + _send_error_response(connection, request_id, + _explain_not_live(get_game_status(-1, EVAL_READY_WAIT_SEC), ErrorCodes.EVAL_GAME_NOT_READY)) + return + _clear_pending(request_id) + _probe_then_eval(tree, code, request_id, connection, timeout_sec, run_token) + + +## #859: registration is run-scoped but not a liveness guarantee. Ping the +## helper's debugger capture and let it report whether its _process beacon is +## still advancing before arming the much longer eval backstop. +func _probe_then_eval( + tree: SceneTree, + code: String, + request_id: String, + connection: McpConnection, + timeout_sec: float, + run_token: int, +) -> void: + if not _is_current_game_run(run_token) or not is_game_capture_ready(): + _send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY, + "The game run changed before game_eval could be checked — the game stopped or restarted. Retry against the current run.") + return + var session: EditorDebuggerSession = _first_active_session() + if session == null: + _send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY, + "Game-side capture registered but its debugger session is no longer active — the game likely just stopped or is restarting. Confirm it is running and retry.") + return + + var timer := tree.create_timer(EVAL_LIVENESS_WAIT_SEC) + var timeout_callable := func() -> void: _on_eval_liveness_timeout(request_id) + timer.timeout.connect(timeout_callable) + _pending[request_id] = { + "kind": "eval_liveness", + "connection": connection, + "timer": timer, + "timeout_callable": timeout_callable, + "code": code, + "eval_timeout_sec": timeout_sec, + "run_token": run_token, + } + session.send_message("mcp:eval_liveness", [request_id]) + if _log_buffer: + _log_buffer.log("[debug] -> mcp:eval_liveness (%s)" % request_id) + + +func _on_eval_liveness_timeout(request_id: String) -> void: + var pending_entry = _pending.get(request_id) + if pending_entry == null or str(pending_entry.get("kind", "")) != "eval_liveness": + return + var connection: McpConnection = pending_entry.get("connection") + _clear_pending(request_id) + if connection == null or not is_instance_valid(connection): + return + _send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY, + ("The game helper did not answer the liveness probe within %.0fms — the game may be backgrounded, frozen, stopped, or restarting. Focus the game window (or relaunch it) and retry." + % (EVAL_LIVENESS_WAIT_SEC * 1000.0))) + + +func _on_eval_liveness_response(data: Array) -> void: + if data.size() < 2: + push_warning("MCP debugger: malformed eval liveness response") + return + var request_id := str(data[0]) + var pending_entry = _pending.get(request_id) + if pending_entry == null or str(pending_entry.get("kind", "")) != "eval_liveness": + return + var connection: McpConnection = pending_entry.get("connection") + var code := str(pending_entry.get("code", "")) + var timeout_sec := float(pending_entry.get("eval_timeout_sec", 10.0)) + var run_token := int(pending_entry.get("run_token", -1)) + var loop_live := bool(data[1]) + _clear_pending(request_id) + if connection == null or not is_instance_valid(connection): + return + if not _is_current_game_run(run_token) or not is_game_capture_ready(): + _send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY, + "The game run changed while game_eval liveness was being checked — the game stopped or restarted. Retry against the current run.") + return + if not loop_live: + _send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY, + "The game helper is registered but its main loop is not advancing — the game window may be backgrounded or the game may be frozen. Focus the game window (or relaunch it) and retry.") + return + var current_tree := Engine.get_main_loop() as SceneTree + if current_tree == null: + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, + "Editor main loop is not a SceneTree — cannot schedule eval") + return + _send_eval(current_tree, code, request_id, connection, timeout_sec) + + +func _send_eval( + tree: SceneTree, + code: String, + request_id: String, + connection: McpConnection, + timeout_sec: float, +) -> void: + var session: EditorDebuggerSession = _first_active_session() + if session == null: + ## #518: capture reported ready but the debugger session is no longer live + ## (the game just stopped / is restarting) — a not-ready race, so the same + ## caller-actionable EVAL_GAME_NOT_READY rather than the opaque hang bucket. + _send_error(connection, request_id, ErrorCodes.EVAL_GAME_NOT_READY, + "Game-side capture registered but its debugger session is no longer active — the game likely just stopped or is restarting. Confirm it's running and retry.") + return + + var timer: SceneTreeTimer = tree.create_timer(timeout_sec) + var timeout_callable := func() -> void: _on_eval_timeout(request_id, timeout_sec) + timer.timeout.connect(timeout_callable) + + ## #490: arm the compile-grace timer. _on_eval_grace concludes a parse error + ## only when the game acked the eval (it received the message and started + ## reload()) but never sent mcp:eval_compiled — see there for why a missing + ## ack must NOT be read as a compile error. + var grace: SceneTreeTimer = tree.create_timer(EVAL_COMPILE_GRACE_SEC) + var grace_callable := func() -> void: _on_eval_grace(request_id) + grace.timeout.connect(grace_callable) + + _pending[request_id] = { + "kind": "eval", + "connection": connection, + "run_token": _game_run_token, + "timer": timer, + "timeout_callable": timeout_callable, + "grace_timer": grace, + "grace_callable": grace_callable, + "acked": false, + "compiled": false, + } + + session.send_message("mcp:eval", [request_id, code]) + if _log_buffer: + _log_buffer.log("[debug] -> mcp:eval (%s)" % request_id) + + +## #518: the 10s editor-side backstop fired — the game never replied at all. +## Attribute the failure instead of emitting a one-size-fits-all INTERNAL_ERROR: +## +## - game not live anymore (parked in a debugger break, stopped, crashed): +## the eval couldn't run/finish for a *game-state* reason. Reply with the +## same caller-actionable EVAL_GAME_NOT_READY + `_explain_not_live` payload +## the pre-hello break path already uses — a break freezes the game's idle +## loop, so any awaiting eval parks here even though sync evals still work. +## - game live but never acked the eval: its main thread never serviced the +## debugger message (long frame/load, CPU-bound prior eval, or a +## backgrounded window whose idle loop is frozen). +## - game live, acked, compiled: the eval genuinely started and never +## finished, and the game couldn't even self-report via its own 8s guard +## (which needs a ticking idle loop) — hung await, CPU-bound loop, or a +## reply the debugger channel dropped. +## +## The live branches reply EVAL_HUNG: the eval code never finished. That code +## plus the game-side 8s guard (also EVAL_HUNG, via mcp:eval_error's code +## element) empties the former INTERNAL_ERROR bucket on this path. +func _on_eval_timeout(request_id: String, timeout_sec: float) -> void: + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + var run_token := int(pending_entry.get("run_token", _game_run_token)) + _clear_pending(request_id) + var conn: McpConnection = pending_entry.connection + if conn == null or not is_instance_valid(conn): + return + if run_token != _game_run_token: + _send_error(conn, request_id, ErrorCodes.EVAL_GAME_NOT_READY, + "The game run changed before game_eval completed — the original game stopped or restarted. Retry against the current run.") + if _log_buffer: + _log_buffer.log("[debug] !! eval timeout from prior run (%s, run=%d, current=%d)" + % [request_id, run_token, _game_run_token]) + return + var status := get_game_status(-1, EVAL_READY_WAIT_SEC) + if str(status.get("status", "")) != "live": + _send_error_response(conn, request_id, + _explain_not_live(status, ErrorCodes.EVAL_GAME_NOT_READY)) + if _log_buffer: + _log_buffer.log("[debug] !! eval timeout, game not live (%s, status=%s)" + % [request_id, str(status.get("status", ""))]) + return + var message: String + if not bool(pending_entry.get("acked", false)): + message = ("Game eval was sent but the game never picked it up within %.0fs — " + + "its main thread is busy or frozen (a long frame/load, a CPU-bound " + + "prior eval, or a backgrounded game window whose loop is throttled). " + + "Check logs_read(source='game') and retry.") % timeout_sec + else: + message = ("Game eval compiled and started running but never returned within " + + "%.0fs — the code is likely stuck in an infinite loop or awaiting a " + + "signal/timer that never fires (a backgrounded game window also freezes " + + "awaits). Check logs_read(source='game').") % timeout_sec + _send_error(conn, request_id, ErrorCodes.EVAL_HUNG, message) + if _log_buffer: + _log_buffer.log("[debug] !! eval timeout (%s)" % request_id) + + +func _on_eval_response(data: Array) -> void: + if data.size() < 2: + push_warning("MCP debugger: malformed eval response (expected 2 fields, got %d)" % data.size()) + return + var request_id: String = data[0] + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + _clear_pending(request_id) + + var connection: McpConnection = pending_entry.connection + if connection == null or not is_instance_valid(connection): + return + + var result_json: String = data[1] if data.size() > 1 else "null" + var json := JSON.new() + var parse_err := json.parse(result_json) + connection.send_deferred_response(request_id, { + "data": { + "result": json.data if parse_err == OK else result_json, + "source": "game", + } + }) + if _log_buffer: + _log_buffer.log("[debug] <- mcp:eval_response (%s)" % request_id) + + +## #518: codes the game side may attach as mcp:eval_error's optional third +## payload element. Allowlisted so a game process can't mint arbitrary +## top-level error codes over the debugger channel; anything else (including +## the legacy two-element payload from an older game helper mid-update) +## falls back to INTERNAL_ERROR exactly as before. +const _GAME_EVAL_ERROR_CODES: Array[String] = [ + ErrorCodes.EVAL_HUNG, + ErrorCodes.EVAL_RESULT_TOO_LARGE, +] + + +func _on_eval_error(data: Array) -> void: + if data.size() < 2: + return + var request_id: String = data[0] + var message: String = data[1] + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + _clear_pending(request_id) + var connection: McpConnection = pending_entry.connection + if connection == null or not is_instance_valid(connection): + return + var code := ErrorCodes.INTERNAL_ERROR + if data.size() > 2 and str(data[2]) in _GAME_EVAL_ERROR_CODES: + code = str(data[2]) + _send_error(connection, request_id, code, message) + if _log_buffer: + _log_buffer.log("[debug] <- mcp:eval_error (%s): %s" % [request_id, message]) + + +## #490: the game sends this at the top of _handle_eval, BEFORE reload() (so it +## survives a parse-error abort). It positively signals "the game received this +## eval and started compiling it" — letting _on_eval_grace tell a real parse +## error (acked, never compiled) apart from a message the game hasn't serviced +## yet (never acked — main thread blocked by a long frame/load or a CPU-bound +## prior eval). +func _on_eval_ack(data: Array) -> void: + if data.is_empty(): + return + var request_id: String = data[0] + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + pending_entry["acked"] = true + if _log_buffer: + _log_buffer.log("[debug] <- mcp:eval_ack (%s)" % request_id) + + +## #490: compile-grace timer fired. Conclude a parse error ONLY when the game +## acked the eval (started reload()) but never sent mcp:eval_compiled. If it +## never acked, the game simply hasn't serviced the message yet — NOT a parse +## error — so leave _pending intact and let the normal eval timeout handle it +## rather than false-failing a valid eval and dropping its eventual real reply. +func _on_eval_grace(request_id: String) -> void: + var pending_entry = _pending.get(request_id) + if pending_entry == null or pending_entry.get("compiled", false): + return + if not pending_entry.get("acked", false): + if _log_buffer: + _log_buffer.log("[debug] eval grace: no ack yet, deferring to timeout (%s)" % request_id) + return + _clear_pending(request_id) + var conn: McpConnection = pending_entry.connection + if conn == null or not is_instance_valid(conn): + return + _send_error(conn, request_id, ErrorCodes.EVAL_COMPILE_ERROR, + "Game eval failed to compile — likely a GDScript syntax/parse error. The parse error text is in the editor's Output/Debugger panel; it is not capturable from the running game. Check your eval code's syntax.") + if _log_buffer: + _log_buffer.log("[debug] !! eval compile error (%s)" % request_id) + + +## #490: the game sends this the instant reload() of the eval source +## succeeds. Flips the pending entry's `compiled` flag so the compile-grace +## timer won't fire a false EVAL_COMPILE_ERROR. +func _on_eval_compiled(data: Array) -> void: + if data.is_empty(): + return + var request_id: String = data[0] + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + pending_entry["compiled"] = true + if _log_buffer: + _log_buffer.log("[debug] <- mcp:eval_compiled (%s)" % request_id) + ## #490: compiled OK — start polling for a runtime error that may have + ## aborted execute(). A backgrounded game can't self-report it, so the + ## editor probes via mcp:eval_check until the eval resolves. + _arm_eval_probe(request_id) + + +## #490: the game reported a runtime error that aborted the eval — either +## from its _process fast path (focused game) or in answer to an editor +## eval_check probe (backgrounded game). Reply fast with the real error text +## instead of waiting for the hang timeout. +func _on_eval_runtime_error(data: Array) -> void: + if data.size() < 2: + return + var request_id: String = data[0] + var message: String = data[1] + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + _clear_pending(request_id) + var connection: McpConnection = pending_entry.connection + if connection == null or not is_instance_valid(connection): + return + var msg := "Game eval raised a runtime error: %s" % message if not message.is_empty() else "Game eval raised a runtime error (no message captured). Check logs_read(source='game')." + _send_error(connection, request_id, ErrorCodes.EVAL_RUNTIME_ERROR, msg) + if _log_buffer: + _log_buffer.log("[debug] <- mcp:eval_runtime_error (%s): %s" % [request_id, message]) + + +## #490: arm one probe tick for an in-flight eval. Re-arms itself each tick +## until the request resolves — eval_response / eval_runtime_error / +## eval_compile_error / hang-timeout all call _clear_pending, which erases the +## entry and stops the chain. Uses the editor's own SceneTreeTimer because the +## editor loop keeps ticking even while a backgrounded game's loop is frozen. +func _arm_eval_probe(request_id: String) -> void: + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + var tree := Engine.get_main_loop() as SceneTree + if tree == null: + return + var probe_timer: SceneTreeTimer = tree.create_timer(EVAL_PROBE_INTERVAL_SEC) + var probe_callable := func() -> void: _on_eval_probe_tick(request_id) + pending_entry["probe_timer"] = probe_timer + pending_entry["probe_callable"] = probe_callable + probe_timer.timeout.connect(probe_callable) + + +## #490: poke the game for a runtime-error verdict, then re-arm. The game's +## _handle_eval_check answers with mcp:eval_runtime_error if a script error +## aborted this eval, else stays silent and we poll again next interval. +func _on_eval_probe_tick(request_id: String) -> void: + if not _pending.has(request_id): + return ## resolved — stop probing + var session: EditorDebuggerSession = _first_active_session() + if session != null and session.is_active(): + session.send_message("mcp:eval_check", [request_id]) + _arm_eval_probe(request_id) + + +## --- game_command: curated runtime game operations --- + +func request_game_command( + op: String, + params: Dictionary, + request_id: String, + connection: McpConnection, + timeout_sec: float = 10.0, +) -> void: + if request_id.is_empty(): + push_warning("MCP debugger: game command request missing request_id") + return + + var tree := Engine.get_main_loop() as SceneTree + if tree == null: + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, + "Editor main loop is not a SceneTree — cannot schedule game command") + return + + if is_game_capture_ready(): + _send_game_command(tree, op, params, request_id, connection, timeout_sec) + return + + if _log_buffer: + _log_buffer.log("[debug] waiting for game_helper hello before game_command (%s)" % request_id) + _wait_then_game_command(tree, op, params, request_id, connection, timeout_sec) + + +func _wait_then_game_command( + tree: SceneTree, + op: String, + params: Dictionary, + request_id: String, + connection: McpConnection, + timeout_sec: float, +) -> void: + var deadline := Time.get_ticks_msec() + int(GAME_READY_WAIT_SEC * 1000.0) + ## #645: the leading yield guarantees the dispatcher has registered the + ## deferred request before any reply (a same-frame reply is dropped as + ## expired); the break check bails out early because a parked game never + ## registers its capture. + await tree.process_frame + while not is_game_capture_ready() and not _break_active and Time.get_ticks_msec() < deadline: + await tree.process_frame + if not is_game_capture_ready(): + _send_error_response(connection, request_id, + _explain_not_live(get_game_status(-1, GAME_READY_WAIT_SEC), ErrorCodes.INTERNAL_ERROR)) + return + _send_game_command(tree, op, params, request_id, connection, timeout_sec) + + +func _send_game_command( + tree: SceneTree, + op: String, + params: Dictionary, + request_id: String, + connection: McpConnection, + timeout_sec: float, +) -> void: + var session: EditorDebuggerSession = _first_active_session() + if session == null: + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, + "No active debugger session — is the game actually running?") + return + + var timer: SceneTreeTimer = tree.create_timer(timeout_sec) + var timeout_callable := func() -> void: + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + _pending.erase(request_id) + var conn: McpConnection = pending_entry.connection + if conn == null or not is_instance_valid(conn): + return + _send_error(conn, request_id, ErrorCodes.INTERNAL_ERROR, + "Game command '%s' timed out after %.0fs" % [op, timeout_sec]) + if _log_buffer: + _log_buffer.log("[debug] !! game_command timeout (%s)" % request_id) + timer.timeout.connect(timeout_callable) + _pending[request_id] = { + "connection": connection, + "timer": timer, + "timeout_callable": timeout_callable, + } + + session.send_message("mcp:game_command", [request_id, op, JSON.stringify(params)]) + if _log_buffer: + _log_buffer.log("[debug] -> mcp:game_command %s (%s)" % [op, request_id]) + + +func _on_game_command_response(data: Array) -> void: + if data.size() < 2: + push_warning("MCP debugger: malformed game_command response (expected 2 fields, got %d)" % data.size()) + return + var request_id: String = data[0] + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + _clear_pending(request_id) + + var connection: McpConnection = pending_entry.connection + if connection == null or not is_instance_valid(connection): + return + + var result_json: String = data[1] if data.size() > 1 else "{}" + var json := JSON.new() + var parse_err := json.parse(result_json) + connection.send_deferred_response(request_id, { + "data": json.data if parse_err == OK else {"source": "game", "result": result_json} + }) + if _log_buffer: + _log_buffer.log("[debug] <- mcp:game_command_response (%s)" % request_id) + + +func _on_game_command_error(data: Array) -> void: + if data.size() < 2: + return + var request_id: String = data[0] + var message: String = data[1] + var pending_entry = _pending.get(request_id) + if pending_entry == null: + return + _clear_pending(request_id) + var connection: McpConnection = pending_entry.connection + if connection == null or not is_instance_valid(connection): + return + _send_error(connection, request_id, ErrorCodes.INTERNAL_ERROR, message) + if _log_buffer: + _log_buffer.log("[debug] <- mcp:game_command_error (%s): %s" % [request_id, message]) diff --git a/addons/godot_ai/debugger/mcp_debugger_plugin.gd.uid b/addons/godot_ai/debugger/mcp_debugger_plugin.gd.uid new file mode 100644 index 0000000..1d5c148 --- /dev/null +++ b/addons/godot_ai/debugger/mcp_debugger_plugin.gd.uid @@ -0,0 +1 @@ +uid://bd1k63iye1bsl diff --git a/addons/godot_ai/dispatcher.gd b/addons/godot_ai/dispatcher.gd new file mode 100644 index 0000000..c834e8e --- /dev/null +++ b/addons/godot_ai/dispatcher.gd @@ -0,0 +1,476 @@ +@tool +class_name McpDispatcher +extends RefCounted + +## Routes incoming commands to handlers and manages the command queue +## with a per-frame time budget. + +var _command_queue: Array[Dictionary] = [] +var _handlers: Dictionary = {} # command_name -> Callable +## Lazy handler registration (#736): plugin.gd registers command names +## against a handler key plus a per-handler script path and constructor +## args, and the handler script is load()ed and instantiated at the FIRST +## dispatch of one of its commands. This keeps the ~30 handler scripts +## (and everything they preload) out of plugin.gd's eager compile +## closure, which stalled "Initializing plugins" on every editor boot. +## Materialized commands are promoted into `_handlers`, so the lazy dicts +## are only consulted on the first call per command. +var _lazy_handler_specs: Dictionary = {} # handler_key -> {path: String, args: Array} +var _lazy_handler_cache: Dictionary = {} # handler_key -> handler instance +var _lazy_commands: Dictionary = {} # command_name -> {handler: String, method: StringName} +var _pending_deferred: Dictionary = {} # request_id -> {command, started_ms, timeout_ms} +var _log_buffer +var _surfaced_error_tracker +## The McpConnection whose pause_processing handlers flip around unsafe +## editor operations (#288 guard). Set by plugin.gd; untyped to honor the +## self-update field-storage policy. When set, _call_handler restores the +## pause depth a crashed handler left unbalanced (#712) — without this a +## single handler crash inside a pause window freezes the transport +## forever (pause has no watchdog or disconnect reset by design). +var pause_target +var mcp_logging := true +var deferred_timeout_overrides_ms: Dictionary = {} + +const DEFAULT_DEFERRED_TIMEOUT_MS := 4500 +const DEFERRED_TIMEOUT_MS_BY_COMMAND := { + "create_script": 4500, + ## Fresh-`.gd` writes defer through the same import-settle window as + ## create_script (#714) — same headroom over IMPORT_SETTLE_MAX_MSEC. + "write_file": 4500, + "stop_project": 4500, + "run_project": 6000, + "take_screenshot": 30000, + "check_client_status": 30000, + "game_eval": 15000, + "game_command": 15000, + "scan_filesystem": 30000, +} +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const FuzzySuggestions := preload("res://addons/godot_ai/utils/fuzzy_suggestions.gd") + + +func _init(log_buffer: McpLogBuffer, surfaced_error_tracker = null) -> void: + _log_buffer = log_buffer + _surfaced_error_tracker = surfaced_error_tracker + + +## Register a command handler. The callable receives (params: Dictionary) -> Dictionary. +func register(command_name: String, handler: Callable) -> void: + _handlers[command_name] = handler + + +## Declare a lazily-constructed handler (#736). `script_path` is load()ed +## and instantiated with `ctor_args` at the first dispatch of any command +## registered against `handler_key` via register_lazy. `ctor_args` may hold +## plugin-lifetime objects (connection, buffers, the dispatcher itself for +## batch); clear() drops them so teardown ordering matches the old eager +## registration (#46). +func register_lazy_handler(handler_key: String, script_path: String, ctor_args: Array) -> void: + _lazy_handler_specs[handler_key] = {"path": script_path, "args": ctor_args} + + +## Register a command that resolves to `method` on the lazily-constructed +## handler declared under `handler_key`. Same dispatch semantics as +## register(); only construction timing differs. +func register_lazy(command_name: String, handler_key: String, method: StringName) -> void: + _lazy_commands[command_name] = {"handler": handler_key, "method": method} + +func unregister(command_name: String, handler_key: String) -> void: + _handlers.erase(command_name) + _lazy_commands.erase(command_name) + ## Drop the lazy spec/cache only when no remaining command routes to + ## this handler key. Custom tools use 1:1 keys ("custom:") so this + ## always erases for them, but built-in keys serve many commands — + ## erasing the shared spec would strand the siblings on + ## "No lazy handler declared" at dispatch time. + for entry in _lazy_commands.values(): + if entry.get("handler", "") == handler_key: + return + _lazy_handler_cache.erase(handler_key) + _lazy_handler_specs.erase(handler_key) + +## Drop registered handlers, queued commands, and the log buffer ref so +## plugin.gd can release RefCounted handlers before Godot reloads their +## class_name scripts (issue #46). After clear(), the dispatcher is inert. +func clear() -> void: + ## Stop lazy handlers before releasing the cache. Handler-owned polling + ## coroutines retain any in-flight worker and deferred-response connection + ## across frames, then join only after the worker is no longer alive. + for instance in _lazy_handler_cache.values(): + if is_instance_valid(instance) and instance.has_method("prepare_for_teardown"): + instance.call("prepare_for_teardown") + _handlers.clear() + ## Release lazily-constructed handler instances (and the ctor args that + ## reference plugin-lifetime objects) at the same teardown point where + ## eager handler Callables used to be dropped — their destructors must + ## run while their scripts are still loaded (#46). This also breaks the + ## dispatcher -> batch handler -> dispatcher ref cycle. + _lazy_handler_specs.clear() + _lazy_handler_cache.clear() + _lazy_commands.clear() + _command_queue.clear() + _pending_deferred.clear() + _log_buffer = null + _surfaced_error_tracker = null + pause_target = null +## Drop queued-but-unexecuted commands. Called by the connection on +## disconnect (#712): commands queued by the previous connection must not +## execute under the next one — the requester is gone, its in-flight +## futures were already failed server-side, and a mutation landing after +## reconnect is a surprise write nobody can correlate. Deferred bookkeeping +## has its own reset (clear_deferred_responses). +func clear_command_queue() -> void: + _command_queue.clear() + + +## Invoke a registered handler directly by name. Returns the handler's raw +## response dict (no request_id or status wrapping). Returns an UNKNOWN_COMMAND +## error dict if the command is not registered. Used by batch_execute. +func dispatch_direct(command: String, params: Dictionary) -> Dictionary: + if not has_command(command): + return ErrorCodes.make(ErrorCodes.UNKNOWN_COMMAND, "Unknown command: %s" % command) + ## Strip the reserved deferred-reply key: only _dispatch may thread it. + ## A caller-supplied _request_id (e.g. inside a batch_execute + ## sub-command's params) would flip a deferred-capable handler into + ## deferred mode against a request id the dispatcher never registered — + ## the direct caller would get the DEFERRED sentinel instead of a result + ## and the out-of-band reply would be dropped as expired. + if params.has("_request_id"): + params = params.duplicate() + params.erase("_request_id") + return _call_handler(command, params) + + +## Whether a command is registered (eagerly or lazily). +func has_command(command: String) -> bool: + return _handlers.has(command) or _lazy_commands.has(command) + + +## Rank registered commands by similarity to `cmd_name` and return the top `limit` +## matches. Uses Godot's built-in String.similarity() (0.0–1.0). Returns an empty +## array if no candidates clear the threshold. Used by batch_execute to surface +## "did you mean" suggestions when an unknown command is passed. +func suggest_similar(cmd_name: String, limit: int = 3, threshold: float = 0.5) -> Array[String]: + return FuzzySuggestions.rank(cmd_name, _registered_command_names(), limit, threshold, 0.0, 0.0) + + +## Union of eagerly-registered and lazily-registered command names. +## Materialized lazy commands live in both dicts, so dedupe via keys. +func _registered_command_names() -> Array: + var names: Dictionary = {} + for command in _handlers: + names[command] = true + for command in _lazy_commands: + names[command] = true + return names.keys() + + +## Enqueue a raw command dict received from the WebSocket. +func enqueue(cmd: Dictionary) -> void: + _command_queue.append(cmd) + + +func pending_deferred_count() -> int: + return _pending_deferred.size() + + +func clear_deferred_responses() -> void: + _pending_deferred.clear() + + +func has_pending_deferred_response(request_id: String) -> bool: + return request_id.is_empty() or _pending_deferred.has(request_id) + + +func complete_deferred_response(request_id: String) -> bool: + if request_id.is_empty(): + return true + if not _pending_deferred.has(request_id): + return false + _pending_deferred.erase(request_id) + return true + + +## Handlers whose response flows out-of-band (e.g. debugger-channel capture) +## return this marker so tick() skips auto-sending a response. The handler is +## responsible for pushing the final response via McpConnection._send_json when +## the async operation completes. The dispatcher tracks the request_id and emits +## DEFERRED_TIMEOUT if the out-of-band response never arrives. The request_id is +## threaded through params under the "_request_id" key so the handler can +## correlate the response. +const DEFERRED_RESPONSE := {"_deferred": true} + + +## Process queued commands within a frame budget (milliseconds). +## Returns an array of response dictionaries to send back. +func tick(budget_ms: float = 4.0) -> Array[Dictionary]: + var responses: Array[Dictionary] = _collect_deferred_timeouts() + var start := Time.get_ticks_msec() + var idx := 0 + + while idx < _command_queue.size() and (Time.get_ticks_msec() - start) < budget_ms: + var cmd: Dictionary = _command_queue[idx] + var response := _dispatch(cmd) + if not response.get("_deferred", false): + responses.append(response) + idx += 1 + + if idx > 0: + _command_queue = _command_queue.slice(idx) + + return responses + + +func _dispatch(cmd: Dictionary) -> Dictionary: + var request_id: String = cmd.get("request_id", "") + var command: String = cmd.get("command", "") + var raw_params: Dictionary = cmd.get("params", {}) + ## Duplicate so the internal _request_id key we thread through doesn't + ## mutate the queued command's params (which is the same dict we're + ## about to JSON-log below, and which later readers like batch_execute + ## shouldn't see dispatcher-internal metadata from). + var params: Dictionary = raw_params.duplicate() + params["_request_id"] = request_id + + if mcp_logging: + _log_buffer.log("[recv] %s(%s)" % [command, JSON.stringify(raw_params)]) + + var result: Dictionary + + if has_command(command): + result = _call_handler(command, params) + else: + result = ErrorCodes.make(ErrorCodes.UNKNOWN_COMMAND, "Unknown command: %s" % command) + + if result.get("_deferred", false): + ## A handler may attach `_deferred_timeout_ms` to its deferred sentinel + ## to claim a per-request budget larger than its command's shared entry + ## (e.g. game_command's `input_sequence`, which steps frames well past + ## the 15s that suits one-shot game ops). 0/absent falls back to the + ## per-command table. + _register_deferred(request_id, command, int(result.get("_deferred_timeout_ms", 0))) + if mcp_logging: + _log_buffer.log("[defer] %s (request %s)" % [command, request_id]) + return result + + result["request_id"] = request_id + if not result.has("status"): + result["status"] = "ok" + ## Stamp live editor readiness onto every command-response envelope so + ## the server's `Session.readiness` cache self-heals on the very next + ## tool call. Without this, a single dropped `readiness_changed` event + ## (or a one-frame race around `pause_processing`) leaves the cache + ## stuck at "playing" / "importing" long after the editor has settled, + ## and write tools fail with EDITOR_NOT_READY against a writable editor. + ## See connection.gd::send_deferred_response for the deferred-response + ## counterpart, which stamps the same field. + result["readiness"] = McpConnection.get_readiness() + _stamp_error_watermark(result) + + if mcp_logging: + var status: String = result.get("status", "ok") + if status == "ok": + _log_buffer.log("[send] %s -> ok" % command) + else: + var err_msg: String = result.get("error", {}).get("message", "unknown") + _log_buffer.log("[send] %s -> error: %s" % [command, err_msg]) + + return result + + +## Truncate JSON-stringified args at this many chars when stuffing them into +## a malformed-result error message — large dicts shouldn't bloat the +## response, but a few hundred chars usually pinpoints which param was the +## wrong shape. +const _MALFORMED_ARGS_MAX := 400 + + +func _call_handler(command: String, params: Dictionary) -> Dictionary: + if not _handlers.has(command): + var materialize_error := _materialize_lazy_command(command) + if not materialize_error.is_empty(): + return materialize_error + ## #712: a handler that crashes between pause_processing = true and its + ## matching false leaves the pause depth unbalanced — GDScript swallows + ## the error, the dispatcher reports "malformed result", and the + ## transport stays paused FOREVER (no watchdog, no disconnect reset). + ## Restore balance at this boundary: the depth a handler leaves behind + ## must equal the depth it started with. + var pause_depth_before: int = pause_target.pause_depth() if pause_target != null else 0 + var result: Dictionary = _handlers[command].call(params) + if pause_target != null and pause_target.pause_depth() > pause_depth_before: + var leaked: int = pause_target.pause_depth() - pause_depth_before + while pause_target.pause_depth() > pause_depth_before: + pause_target.resume() + if mcp_logging and _log_buffer != null: + _log_buffer.log( + "[error] %s leaked %d pause_processing level(s) — restored (handler crash?)" + % [command, leaked] + ) + ## Handlers must return {"data": ...} on success or {"error": ...} on failure. + ## Anything else (null, empty, missing keys) means the handler crashed + ## mid-call — GDScript swallows the error and returns an empty dict. + if result == null or not (result.has("data") or result.has("error") or result.has("_deferred")): + var safe_params := params.duplicate() + safe_params.erase("_request_id") + var args_json := JSON.stringify(safe_params) + if args_json.length() > _MALFORMED_ARGS_MAX: + args_json = args_json.substr(0, _MALFORMED_ARGS_MAX) + "..." + var backtrace := _capture_compact_backtrace() + var msg := ( + "Handler '%s' returned malformed result — likely a runtime error in the handler " + + "(e.g. param type mismatch). Args received: %s" + ) % [command, args_json] + if not backtrace.is_empty(): + msg += "\nBacktrace:\n%s" % backtrace + if mcp_logging and _log_buffer != null: + var compact_backtrace := backtrace.replace("\n", " | ") + _log_buffer.log( + "[error] %s -> malformed result; args=%s; backtrace=%s" + % [command, args_json, compact_backtrace] + ) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, msg) + return result + + +## Resolve a lazily-registered command into a live Callable in `_handlers`. +## Loads + constructs the owning handler on first use (cached per handler +## key, so one load() covers every command the handler serves). Returns an +## empty dict on success or a protocol error dict on failure — a missing +## script or method is a plugin packaging bug and must surface loudly, not +## as a silent no-op. +func _materialize_lazy_command(command: String) -> Dictionary: + var command_spec: Dictionary = _lazy_commands.get(command, {}) + if command_spec.is_empty(): + return ErrorCodes.make(ErrorCodes.UNKNOWN_COMMAND, "Unknown command: %s" % command) + var handler_key: String = command_spec["handler"] + var instance = _lazy_handler_cache.get(handler_key) + if instance == null: + var handler_spec: Dictionary = _lazy_handler_specs.get(handler_key, {}) + if handler_spec.is_empty(): + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "No lazy handler '%s' declared for command '%s'" % [handler_key, command] + ) + ## Existence-check first so a missing script surfaces as one clean + ## protocol error instead of also spraying engine load errors. + if not ResourceLoader.exists(handler_spec["path"]): + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Missing handler script '%s' for command '%s'" % [handler_spec["path"], command] + ) + var script := load(handler_spec["path"]) as GDScript + if script == null: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to load handler script '%s' for command '%s'" % [handler_spec["path"], command] + ) + instance = script.callv("new", handler_spec["args"]) + if instance == null: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to construct handler '%s' for command '%s'" % [handler_key, command] + ) + _lazy_handler_cache[handler_key] = instance + var method: StringName = command_spec["method"] + if not instance.has_method(method): + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Handler '%s' has no method '%s' for command '%s'" % [handler_key, method, command] + ) + _handlers[command] = Callable(instance, method) + return {} + + +func _register_deferred(request_id: String, command: String, timeout_override_ms: int = 0) -> void: + if request_id.is_empty(): + return + ## A positive per-request override wins over the per-command table so a + ## single deferred call can claim more headroom without globally widening + ## the command's budget (see _dispatch: input_sequence needs ~30s, but the + ## other game_command ops must keep their tight 15s). + var timeout_ms: int = ( + timeout_override_ms if timeout_override_ms > 0 + else _deferred_timeout_ms_for_command(command) + ) + _pending_deferred[request_id] = { + "command": command, + "started_ms": Time.get_ticks_msec(), + "timeout_ms": timeout_ms, + } + + +func _deferred_timeout_ms_for_command(command: String) -> int: + if deferred_timeout_overrides_ms.has(command): + return int(deferred_timeout_overrides_ms[command]) + return int(DEFERRED_TIMEOUT_MS_BY_COMMAND.get(command, DEFAULT_DEFERRED_TIMEOUT_MS)) + + +func _collect_deferred_timeouts() -> Array[Dictionary]: + var responses: Array[Dictionary] = [] + if _pending_deferred.is_empty(): + return responses + var now := Time.get_ticks_msec() + for request_id in _pending_deferred.keys(): + var entry: Dictionary = _pending_deferred[request_id] + var timeout_ms: int = entry.get("timeout_ms", DEFAULT_DEFERRED_TIMEOUT_MS) + var elapsed_ms := now - int(entry.get("started_ms", now)) + if elapsed_ms < timeout_ms: + continue + _pending_deferred.erase(request_id) + var command: String = entry.get("command", "") + var response := ErrorCodes.make( + ErrorCodes.DEFERRED_TIMEOUT, + "Deferred response for '%s' timed out after %dms" % [command, timeout_ms] + ) + response["request_id"] = request_id + response["error"]["data"] = { + "command": command, + "elapsed_ms": elapsed_ms, + "timeout_ms": timeout_ms, + } + ## Same envelope-level readiness stamp as `_dispatch` — keep the + ## self-heal channel symmetric across every reply shape the + ## dispatcher emits so the server cache can't drift just because + ## the editor happened to time out a deferred command. + response["readiness"] = McpConnection.get_readiness() + _stamp_error_watermark(response) + responses.append(response) + if mcp_logging and _log_buffer != null: + _log_buffer.log("[defer] %s (request %s) -> timeout" % [command, request_id]) + return responses + + +func _stamp_error_watermark(response: Dictionary) -> void: + McpSurfacedErrorTracker.stamp_watermark(response, _surfaced_error_tracker) + + +static func _capture_compact_backtrace(max_frames: int = 8) -> String: + var traces: Array = Engine.capture_script_backtraces(false) + for bt in traces: + if bt != null and not bt.is_empty(): + return _trim_backtrace_string(bt.format(0, 2), max_frames) + return _format_stack_frames(get_stack(), max_frames) + + +static func _trim_backtrace_string(text: String, max_frames: int) -> String: + var lines := text.strip_edges().split("\n") + var kept: Array[String] = [] + for i in range(min(lines.size(), max_frames)): + kept.append(lines[i].strip_edges()) + return "\n".join(kept) + + +static func _format_stack_frames(frames: Array, max_frames: int) -> String: + var lines: Array[String] = [] + for i in range(min(frames.size(), max_frames)): + var frame: Dictionary = frames[i] + lines.append( + "%s:%s in %s" + % [ + frame.get("source", "?"), + frame.get("line", 0), + frame.get("function", "?"), + ] + ) + return "\n".join(lines) diff --git a/addons/godot_ai/dispatcher.gd.uid b/addons/godot_ai/dispatcher.gd.uid new file mode 100644 index 0000000..25a05bd --- /dev/null +++ b/addons/godot_ai/dispatcher.gd.uid @@ -0,0 +1 @@ +uid://ctldk7ivsoo3i diff --git a/addons/godot_ai/dock_panels/log_viewer.gd b/addons/godot_ai/dock_panels/log_viewer.gd new file mode 100644 index 0000000..1d7b986 --- /dev/null +++ b/addons/godot_ai/dock_panels/log_viewer.gd @@ -0,0 +1,100 @@ +@tool +extends VBoxContainer + +## Dock subpanel — renders the MCP request/response log buffer. Owns its own +## UI subtree, the line-count cursor, and the display-visibility toggle. Emits +## `logging_enabled_changed` so the dock can route the flag onto the +## connection dispatcher without the panel knowing the routing exists. +## +## Extracted from mcp_dock.gd as part of audit-v2 #360 — see the comment at +## the top of mcp_dock.gd for the broader extraction story. + +signal logging_enabled_changed(enabled: bool) + +const Dock := preload("res://addons/godot_ai/mcp_dock.gd") +## Preload (not the McpSettings class_name) for consistency with the parse +## hazard note on `_log_buffer` below. +const Settings := preload("res://addons/godot_ai/utils/settings.gd") + +## Untyped: a `: McpLogBuffer` annotation hits the class_name registry at +## script-load and trips the self-update parse hazard (#398). The type fence +## stays on the `setup(log_buffer: McpLogBuffer)` parameter. +var _log_buffer +var _log_display: RichTextLabel +var _log_toggle: CheckButton +## Last `McpLogBuffer.total_logged()` value painted into the display. Tracking +## the buffer's monotonic sequence (rather than its bounded `total_count()`) +## keeps the viewer painting once the ring fills — a size-based cursor would +## freeze at MAX_LINES on every subsequent append. See PR #392 for the bug. +var _last_log_seq := 0 + + +## Build the UI synchronously here so callers (and detached-tree tests that +## instantiate the dock with `McpDockScript.new()` and never enter the tree) +## can interact with the panel's controls right after `setup()`. Mirrors the +## pre-extraction inline-build behavior that test_dock.gd relies on. +## +## Idempotent: `_log_display == null` covers an unlikely double-`setup()` call +## without rebuilding (which would orphan the prior controls). +func setup(log_buffer: McpLogBuffer) -> void: + _log_buffer = log_buffer + if _log_display == null: + _build_ui() + + +func _build_ui() -> void: + add_child(HSeparator.new()) + + var log_header_row := HBoxContainer.new() + var log_header := Dock._make_header("MCP Log") + log_header.size_flags_horizontal = Control.SIZE_EXPAND_FILL + log_header_row.add_child(log_header) + + _log_toggle = CheckButton.new() + _log_toggle.text = "Log" + ## Restore the persisted choice — a hardcoded `true` here meant the + ## toggle reset to noisy on every editor restart (#626). + _log_toggle.button_pressed = Settings.mcp_logging_enabled() + _log_toggle.toggled.connect(_on_log_toggled) + log_header_row.add_child(_log_toggle) + + add_child(log_header_row) + + _log_display = RichTextLabel.new() + _log_display.custom_minimum_size = Vector2(0, 80) + _log_display.scroll_following = true + _log_display.bbcode_enabled = false + _log_display.selection_enabled = true + _log_display.visible = _log_toggle.button_pressed + add_child(_log_display) + + +## Called from McpDock._process when the panel is visible. Appends any new +## log lines since the last tick. +func tick() -> void: + if _log_buffer == null or _log_display == null: + return + var seq: int = _log_buffer.total_logged() + if seq == _last_log_seq: + return + if seq < _last_log_seq: + ## Buffer cleared via `McpLogBuffer.clear()` (the `clear_logs` MCP + ## tool / `logs_clear` handler). The buffer resets `_total_logged` + ## to 0, flipping the sequence backward. Without this branch the + ## display would keep showing pre-clear lines forever — the viewer + ## drifts permanently out of sync with the buffer. Reset display + + ## cursor so the next append paints over a clean slate. + _log_display.clear() + _last_log_seq = 0 + if seq == 0: + return + var new_lines: Array[String] = _log_buffer.get_recent(seq - _last_log_seq) + for line in new_lines: + _log_display.add_text(line + "\n") + _last_log_seq = seq + + +func _on_log_toggled(enabled: bool) -> void: + Settings.set_mcp_logging_enabled(enabled) + _log_display.visible = enabled + logging_enabled_changed.emit(enabled) diff --git a/addons/godot_ai/dock_panels/log_viewer.gd.uid b/addons/godot_ai/dock_panels/log_viewer.gd.uid new file mode 100644 index 0000000..c261627 --- /dev/null +++ b/addons/godot_ai/dock_panels/log_viewer.gd.uid @@ -0,0 +1 @@ +uid://cr5nbnd6vj3b8 diff --git a/addons/godot_ai/dock_panels/port_picker_panel.gd b/addons/godot_ai/dock_panels/port_picker_panel.gd new file mode 100644 index 0000000..30c3ed3 --- /dev/null +++ b/addons/godot_ai/dock_panels/port_picker_panel.gd @@ -0,0 +1,78 @@ +@tool +extends VBoxContainer + +## Dock subpanel — port-change escape hatch surfaced inside the spawn-failure +## crash panel when the HTTP port is contested (PORT_EXCLUDED, FOREIGN_PORT). +## Emits `port_apply_requested(new_port)` after range-validation; the dock +## handles writing the EditorSetting and reloading the plugin. +## +## Extracted from mcp_dock.gd as part of audit-v2 #360 — see the comment at +## the top of mcp_dock.gd for the broader extraction story. + +const ClientConfigurator := preload("res://addons/godot_ai/client_configurator.gd") + +signal port_apply_requested(new_port: int) + +var _spinbox: SpinBox + + +## Build the UI synchronously here so callers (and detached-tree tests that +## instantiate the dock with `McpDockScript.new()` and never enter the tree) +## can interact with the panel's controls right after `setup()`. Mirrors the +## pre-extraction inline-build behavior that test_dock.gd relies on. +## +## Idempotent: `_spinbox == null` covers an unlikely double-`setup()` call +## without rebuilding (which would orphan the prior controls). +func setup() -> void: + if _spinbox == null: + _build_ui() + + +func _build_ui() -> void: + add_theme_constant_override("separation", 4) + visible = false + + var picker_row := HBoxContainer.new() + picker_row.add_theme_constant_override("separation", 6) + + _spinbox = SpinBox.new() + _spinbox.min_value = ClientConfigurator.MIN_PORT + _spinbox.max_value = ClientConfigurator.MAX_PORT + _spinbox.step = 1 + _spinbox.value = ClientConfigurator.http_port() + _spinbox.size_flags_horizontal = Control.SIZE_EXPAND_FILL + picker_row.add_child(_spinbox) + + var apply_btn := Button.new() + apply_btn.text = "Apply + Reload" + apply_btn.tooltip_text = ( + "Saves godot_ai/http_port to Editor Settings and reloads the plugin so" + + " the server spawns on the new port." + ) + apply_btn.pressed.connect(_on_apply_pressed) + picker_row.add_child(apply_btn) + + add_child(picker_row) + + +## Re-seed the spinbox with a fresh suggestion every time the panel surfaces, +## so a stale value from a previous spawn-failure round can't carry over. Note +## that this OVERWRITES any unsaved user input — fine in practice because the +## dock's `_update_crash_panel` only calls this on `server_status` transitions +## (`if server_status == _last_server_status: return` short-circuit), so a +## user typing into the spinbox between transitions keeps their value. If the +## state flips while the picker is visible (e.g. `PORT_EXCLUDED` → `FOREIGN_PORT`), +## the in-flight edit is clobbered — accept that, the suggestion is more current. +func seed_suggested_port() -> void: + if _spinbox == null: + return + _spinbox.value = ClientConfigurator.suggest_free_port( + ClientConfigurator.http_port() + 1 + ) + + +func _on_apply_pressed() -> void: + var new_port: int = int(_spinbox.value) + if new_port < ClientConfigurator.MIN_PORT or new_port > ClientConfigurator.MAX_PORT: + return + port_apply_requested.emit(new_port) diff --git a/addons/godot_ai/dock_panels/port_picker_panel.gd.uid b/addons/godot_ai/dock_panels/port_picker_panel.gd.uid new file mode 100644 index 0000000..38b6320 --- /dev/null +++ b/addons/godot_ai/dock_panels/port_picker_panel.gd.uid @@ -0,0 +1 @@ +uid://hlggbo1q65eq diff --git a/addons/godot_ai/export/mcp_export_plugin.gd b/addons/godot_ai/export/mcp_export_plugin.gd new file mode 100644 index 0000000..5a8b885 --- /dev/null +++ b/addons/godot_ai/export/mcp_export_plugin.gd @@ -0,0 +1,69 @@ +@tool +extends EditorExportPlugin + +## Strips the MCP game-helper autoload from exported builds (#740). +## +## plugin.gd writes `autoload/_mcp_game_helper` into project.godot so the +## editor-spawned game process loads the helper. Exports bake project +## settings into the pack's project.binary, so without this plugin every +## export ships the autoload — and users who exclude addons/godot_ai/** +## in their export preset get three "Failed to instantiate an autoload" +## errors at game start. Even when the files ARE shipped, the helper is +## editor-tooling: no exported build should carry it. +## +## Strip mechanics: clear the in-memory ProjectSettings entry in +## _export_begin, restore it in _export_end. The export pipeline reads +## the live ProjectSettings when it bakes project.binary, which happens +## after _export_begin — verified end-to-end by +## script/ci-export-strip-smoke, which exports a real pack and asserts +## the autoload is absent inside it. We never call ProjectSettings.save() +## while stripped, so project.godot on disk keeps the autoload +## throughout; only the export snapshot loses it. +## +## Failure containment: if an export aborts so hard that _export_end +## never fires, the damage is bounded to the editor's in-memory settings +## — the running game reads project.godot from disk, and plugin.gd's +## _ensure_game_helper_autoload() re-asserts the entry on the next +## plugin enable / editor launch. + +## Must equal "autoload/" + plugin.gd's GAME_HELPER_AUTOLOAD_NAME. +## Duplicated (not preloaded from plugin.gd) to avoid a cyclic preload — +## plugin.gd preloads this script. The pairing is locked by +## test_export_strip.gd's constants-contract test. +const AUTOLOAD_KEY := "autoload/_mcp_game_helper" + +var _saved_value: Variant = null +var _stripped := false + + +func _get_name() -> String: + return "GodotAIStripAutoload" + + +func _export_begin(_features: PackedStringArray, _is_debug: bool, _path: String, _flags: int) -> void: + ## `_stripped` guard: if a previous export died before _export_end, + ## don't overwrite the genuinely-saved value with the already-cleared + ## state — restore semantics stay anchored to the original value. + if _stripped: + return + if not ProjectSettings.has_setting(AUTOLOAD_KEY): + return + _saved_value = ProjectSettings.get_setting(AUTOLOAD_KEY) + ## Setting a project setting to null erases it. + ProjectSettings.set_setting(AUTOLOAD_KEY, null) + _stripped = true + print("MCP | export: stripping %s from the exported pack (restored in the editor after export)" % AUTOLOAD_KEY) + + +func _export_end() -> void: + if not _stripped: + return + ProjectSettings.set_setting(AUTOLOAD_KEY, _saved_value) + ## Mirror _ensure_game_helper_autoload()'s registration shape so the + ## restored entry is indistinguishable from the original: initial + ## value "" keeps project.godot diff-clean, basic keeps it visible in + ## the non-advanced settings view. + ProjectSettings.set_initial_value(AUTOLOAD_KEY, "") + ProjectSettings.set_as_basic(AUTOLOAD_KEY, true) + _saved_value = null + _stripped = false diff --git a/addons/godot_ai/export/mcp_export_plugin.gd.uid b/addons/godot_ai/export/mcp_export_plugin.gd.uid new file mode 100644 index 0000000..f2a3634 --- /dev/null +++ b/addons/godot_ai/export/mcp_export_plugin.gd.uid @@ -0,0 +1 @@ +uid://np0cp6fwpim7 diff --git a/addons/godot_ai/handlers/_node_validator.gd b/addons/godot_ai/handlers/_node_validator.gd new file mode 100644 index 0000000..61bbe10 --- /dev/null +++ b/addons/godot_ai/handlers/_node_validator.gd @@ -0,0 +1,71 @@ +@tool +class_name McpNodeValidator +extends RefCounted + +## Shared resolve-or-error helper that subsumes the 38+ sites where +## handlers each rolled their own "is the editor ready, does the path +## resolve, otherwise return EDITOR_NOT_READY / NODE_NOT_FOUND" guard. +## +## audit-v2 #20 (issue #364). Uses the audit-v2 #21 (issue #365) error +## vocabulary. + +## Local const names alias the preloaded scripts. The naming choice is +## stylistic, not an upgrade-safety boundary: bare `McpErrorCodes.MEMBER` +## and `ErrorCodes.MEMBER` both depend on the Script object Godot has for +## `error_codes.gd`. The transient #398 parse errors were caused by the +## old runner scanning a mixed old/new plugin snapshot and seeing stale +## Script-object content; the runner now writes one v(N+1) snapshot before +## its scan. +const ScenePath := preload("res://addons/godot_ai/utils/scene_path.gd") +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + + +## Resolve a scene-relative path to the live Node, or return a structured +## error dict. +## +## Success shape: `{"node": Node, "scene_root": Node, "path": String}`. +## Error shape: matches `ErrorCodes.make(...)` so callers can +## `return resolved` to propagate. +## +## Errors (in order checked): +## - `MISSING_REQUIRED_PARAM`: `node_path` is empty +## - `EDITOR_NOT_READY`: no scene open +## - `EDITED_SCENE_MISMATCH`: caller pinned `scene_file` and the open +## scene's path doesn't match +## - `NODE_NOT_FOUND`: `node_path` doesn't resolve under the scene root +## +## `param_name` is the agent-facing name reported in the +## `MISSING_REQUIRED_PARAM` message — handlers pass "node_path", +## "player_path", "target_path", etc. so the error reads like the +## hand-written messages it replaces. +static func resolve_or_error( + node_path: String, + param_name: String = "path", + scene_file: String = "", +) -> Dictionary: + if node_path.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "Missing required param: %s" % param_name, + ) + var scene_check := ScenePath.require_edited_scene(scene_file) + if scene_check.has("error"): + return scene_check + var scene_root: Node = scene_check.node + var node := ScenePath.resolve(node_path, scene_root) + if node == null: + return ErrorCodes.make( + ErrorCodes.NODE_NOT_FOUND, + ScenePath.format_node_error(node_path, scene_root), + ) + return {"node": node, "scene_root": scene_root, "path": node_path} + + +## When the caller needs the scene root but no specific node yet — e.g. +## handlers that walk children or filter by group. Returns either +## `{"scene_root": Node}` or an `ErrorCodes.make(...)` error dict. +static func require_scene_or_error(scene_file: String = "") -> Dictionary: + var scene_check := ScenePath.require_edited_scene(scene_file) + if scene_check.has("error"): + return scene_check + return {"scene_root": scene_check.node} diff --git a/addons/godot_ai/handlers/_node_validator.gd.uid b/addons/godot_ai/handlers/_node_validator.gd.uid new file mode 100644 index 0000000..b3153a6 --- /dev/null +++ b/addons/godot_ai/handlers/_node_validator.gd.uid @@ -0,0 +1 @@ +uid://dn75jifad0ghx diff --git a/addons/godot_ai/handlers/_param_validators.gd b/addons/godot_ai/handlers/_param_validators.gd new file mode 100644 index 0000000..a316b32 --- /dev/null +++ b/addons/godot_ai/handlers/_param_validators.gd @@ -0,0 +1,30 @@ +@tool +class_name McpParamValidators +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Type-check a JSON-decoded param Variant before assigning it into a typed +## GDScript local. The dispatcher only catches handler crashes as an opaque +## "malformed result" (issue #210), so a typed assignment like +## var group: String = params.get("group", "") +## will runtime-error and bubble up without telling the caller which param +## was the wrong shape. Only string params are guarded — int/bool params +## can't be: Godot's JSON parser decodes every number as float (a wire `5` +## arrives as `5.0`), so a strict int check would reject every legitimate +## integer a client sends, and GDScript's typed assignment already converts +## numeric Variants safely. Bool params arrive as real bools and a wrong +## type surfaces through the dispatcher's malformed-result path. + + +## Returns null iff `value` is a String or StringName. On any other type +## returns an INVALID_PARAMS error dict whose message names both `name` and +## the actual Variant type (via Godot's built-in `type_string`). +static func require_string(name: String, value: Variant) -> Variant: + var t := typeof(value) + if t == TYPE_STRING or t == TYPE_STRING_NAME: + return null + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Param '%s' must be a String, got %s" % [name, type_string(t)], + ) diff --git a/addons/godot_ai/handlers/_param_validators.gd.uid b/addons/godot_ai/handlers/_param_validators.gd.uid new file mode 100644 index 0000000..cd2061e --- /dev/null +++ b/addons/godot_ai/handlers/_param_validators.gd.uid @@ -0,0 +1 @@ +uid://difa877m8dsla diff --git a/addons/godot_ai/handlers/_property_errors.gd b/addons/godot_ai/handlers/_property_errors.gd new file mode 100644 index 0000000..316b941 --- /dev/null +++ b/addons/godot_ai/handlers/_property_errors.gd @@ -0,0 +1,82 @@ +@tool +class_name McpPropertyErrors +extends RefCounted + +## Shared helper for building "Property not found" error messages that include +## "did you mean" suggestions and a tail of available property names. All +## handlers that validate user-supplied property names against a target Object +## (Node, Resource, …) should route through build_message() so agents get +## consistent, actionable errors on typos. +## +## Ranking combines Godot's built-in String.similarity() with a substring +## bonus so both "radus" → "radius" (edit distance) and "top" → "top_radius" +## (substring) surface naturally. + +const _SIMILARITY_THRESHOLD: float = 0.4 +const _SUBSTRING_BONUS: float = 0.5 +const _MAX_SUGGESTIONS: int = 5 +const _MAX_TAIL: int = 10 + + +static func build_message(target: Object, bad_name: String) -> String: + if target == null: + return "Property '%s' not found" % bad_name + var class_label := _class_label(target) + var available := _available_property_names(target) + if available.is_empty(): + return "Property '%s' not found on %s" % [bad_name, class_label] + + var msg := "Property '%s' not found on %s" % [bad_name, class_label] + var suggestions := _rank_suggestions(bad_name, available) + if not suggestions.is_empty(): + msg += ". Did you mean: %s?" % ", ".join(suggestions) + + var tail_names := available.slice(0, min(_MAX_TAIL, available.size())) + msg += " (available: %s" % ", ".join(tail_names) + if available.size() > tail_names.size(): + msg += ", ..." + msg += ")" + return msg + + +## Prefer a scripted class_name if the target has one, else the engine class. +static func _class_label(target: Object) -> String: + var scr := target.get_script() + if scr != null and scr.has_method("get_global_name"): + var gcn: String = scr.get_global_name() + if not gcn.is_empty(): + return gcn + return target.get_class() + + +## Editor-visible properties, alphabetised, with internal/category entries dropped. +static func _available_property_names(target: Object) -> Array: + var names: Array = [] + for p in target.get_property_list(): + var usage: int = int(p.get("usage", 0)) + if (usage & PROPERTY_USAGE_EDITOR) == 0: + continue + var name: String = p.get("name", "") + if name.is_empty() or name.begins_with("_"): + continue + names.append(name) + names.sort() + return names + + +static func _rank_suggestions(bad: String, available: Array) -> Array: + if bad.is_empty(): + return [] + var bad_lower := bad.to_lower() + var scored: Array = [] + for n in available: + var score: float = bad.similarity(n) + if n.to_lower().find(bad_lower) != -1 or bad_lower.find(n.to_lower()) != -1: + score += _SUBSTRING_BONUS + if score >= _SIMILARITY_THRESHOLD: + scored.append([score, n]) + scored.sort_custom(func(a, b): return a[0] > b[0]) + var result: Array = [] + for i in range(min(_MAX_SUGGESTIONS, scored.size())): + result.append(scored[i][1]) + return result diff --git a/addons/godot_ai/handlers/_property_errors.gd.uid b/addons/godot_ai/handlers/_property_errors.gd.uid new file mode 100644 index 0000000..c29d21c --- /dev/null +++ b/addons/godot_ai/handlers/_property_errors.gd.uid @@ -0,0 +1 @@ +uid://c74d560g4l86b diff --git a/addons/godot_ai/handlers/animation_handler.gd b/addons/godot_ai/handlers/animation_handler.gd new file mode 100644 index 0000000..8000b78 --- /dev/null +++ b/addons/godot_ai/handlers/animation_handler.gd @@ -0,0 +1,825 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles AnimationPlayer authoring: creating players, animations, tracks, +## keyframes, autoplay, and dev-ergonomics playback. +## +## Animations live inside an AnimationLibrary attached to an AnimationPlayer +## node in the scene. They save with the .tscn — no separate resource file +## needed. Undo callables hold direct Animation references (not paths). +## +## Split (issue #342, audit finding #13): +## - animation_presets.gd → preset_fade / slide / shake / pulse + helpers +## - animation_values.gd → animation_list / get / validate + shared +## value coercion / serialization +## Both submodules hold a WeakRef back to this handler. The handler's +## preset_* / list / get / validate methods are thin proxies so existing +## dispatcher registrations and test fixtures don't change. + +const AnimationPresets := preload("res://addons/godot_ai/handlers/animation_presets.gd") +const AnimationValues := preload("res://addons/godot_ai/handlers/animation_values.gd") + +var _undo_redo: EditorUndoRedoManager +var _presets +var _values + +const _LOOP_MODES := { + "none": Animation.LOOP_NONE, + "linear": Animation.LOOP_LINEAR, + "pingpong": Animation.LOOP_PINGPONG, +} + +const _INTERP_MODES := { + "nearest": Animation.INTERPOLATION_NEAREST, + "linear": Animation.INTERPOLATION_LINEAR, + "cubic": Animation.INTERPOLATION_CUBIC, +} + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + _presets = AnimationPresets.new(self) + _values = AnimationValues.new(self) + + +# ============================================================================ +# animation_player_create +# ============================================================================ + +func create_player(params: Dictionary) -> Dictionary: + var parent_path: String = params.get("parent_path", "") + var node_name: String = params.get("name", "AnimationPlayer") + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + var player := AnimationPlayer.new() + if not node_name.is_empty(): + player.name = node_name + + # Attach the default library before adding to tree — it persists on redo. + var library := AnimationLibrary.new() + player.add_animation_library("", library) + + _undo_redo.create_action("MCP: Create AnimationPlayer %s" % player.name) + _undo_redo.add_do_method(parent, "add_child", player, true) + _undo_redo.add_do_method(player, "set_owner", scene_root) + _undo_redo.add_do_reference(player) + _undo_redo.add_do_reference(library) + _undo_redo.add_undo_method(parent, "remove_child", player) + _undo_redo.commit_action() + + return { + "data": { + "path": McpScenePath.from_node(player, scene_root), + "parent_path": McpScenePath.from_node(parent, scene_root), + "name": String(player.name), + "undoable": true, + } + } + + +# ============================================================================ +# animation_create +# ============================================================================ + +func create_animation(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("name", "") + var length: float = float(params.get("length", 1.0)) + var loop_mode_str: String = params.get("loop_mode", "none") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if anim_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: name") + if length <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "length must be > 0 (got %s)" % length) + + if not _LOOP_MODES.has(loop_mode_str): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid loop_mode '%s'. Valid: %s" % [loop_mode_str, ", ".join(_LOOP_MODES.keys())]) + + var resolved := _resolve_player(player_path, true) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + var library: AnimationLibrary = resolved.library + var created_player: bool = resolved.get("player_created", false) + var player_parent: Node = resolved.get("player_parent", null) + var created_library := false + if library == null: + library = AnimationLibrary.new() + created_library = true + + var overwrite: bool = params.get("overwrite", false) + var old_anim: Animation = null + if library.has_animation(anim_name): + if not overwrite: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Animation '%s' already exists. Pass overwrite=true or delete it first." % anim_name) + old_anim = library.get_animation(anim_name) + + var anim := Animation.new() + anim.length = length + anim.loop_mode = _LOOP_MODES[loop_mode_str] + + _commit_animation_add("MCP: Create animation %s" % anim_name, + player, library, created_library, anim_name, anim, old_anim, + created_player, player_parent) + + return { + "data": { + "player_path": player_path, + "name": anim_name, + "length": length, + "loop_mode": loop_mode_str, + "library_created": created_library or created_player, + "animation_player_created": created_player, + "overwritten": old_anim != null, + "undoable": true, + } + } + + +# ============================================================================ +# animation_delete +# ============================================================================ + +func delete_animation(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("animation_name", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if anim_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: animation_name") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + # Use _resolve_animation so we can delete from ANY library, not just the + # default. Mirrors the read-side symmetry with animation_get / animation_play + # which already search all libraries via _resolve_animation. + var anim_resolved := _resolve_animation(player, anim_name) + if anim_resolved.has("error"): + return anim_resolved + var old_anim: Animation = anim_resolved.animation + var library: AnimationLibrary = anim_resolved.library + # Clip key within the owning library — strips the "libname/" prefix if the + # caller passed a qualified name. + var clip_key: String = anim_name + var slash := anim_name.find("/") + if slash >= 0: + clip_key = anim_name.substr(slash + 1) + + _undo_redo.create_action("MCP: Delete animation %s" % anim_name) + _undo_redo.add_do_method(library, "remove_animation", clip_key) + _undo_redo.add_undo_method(library, "add_animation", clip_key, old_anim) + _undo_redo.add_do_reference(old_anim) # prevent GC so undo→redo works + _undo_redo.commit_action() + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "library_key": anim_resolved.get("library_key", ""), + "undoable": true, + } + } + + +# ============================================================================ +# animation_add_property_track +# ============================================================================ + +func add_property_track(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("animation_name", "") + var track_path: String = params.get("track_path", "") + var keyframes = params.get("keyframes", []) + var interp_str: String = params.get("interpolation", "linear") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if anim_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: animation_name") + if track_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, + "Missing required param: track_path (format: 'NodeName:property', e.g. 'Panel:modulate')") + if not track_path.contains(":"): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "track_path must include ':property' suffix (e.g. 'Panel:modulate', '.:position')") + if not _INTERP_MODES.has(interp_str): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid interpolation '%s'. Valid: %s" % [interp_str, ", ".join(_INTERP_MODES.keys())]) + if typeof(keyframes) != TYPE_ARRAY or keyframes.is_empty(): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "keyframes must be a non-empty array") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + var anim_resolved := _resolve_animation(player, anim_name) + if anim_resolved.has("error"): + return anim_resolved + var anim: Animation = anim_resolved.animation + + # Validate + pre-coerce keyframes before mutating. Coercion errors + # surface as INVALID_PARAMS rather than silently inserting garbage keys. + # Resolve the target property's type ONCE — dense clips used to re-walk + # get_property_list() per keyframe. + var ctx := AnimationValues.resolve_track_prop_context(track_path, player) + if ctx.has("error"): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, ctx.error) + var coerced_keyframes: Array = [] + for kf in keyframes: + if typeof(kf) != TYPE_DICTIONARY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Each keyframe must be a dictionary") + if not "time" in kf: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Each keyframe must have a 'time' field") + if not "value" in kf: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Each keyframe must have a 'value' field") + var coerce_result := AnimationValues.coerce_with_context(kf.get("value"), ctx) + if coerce_result.has("error"): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, coerce_result.error) + coerced_keyframes.append({ + "time": kf.get("time"), + "value": coerce_result.ok, + "transition": kf.get("transition", "linear"), + }) + + _create_scene_pinned_action("MCP: Add property track %s to %s" % [track_path, anim_name]) + _undo_redo.add_do_method(self, "_do_add_property_track", anim, track_path, interp_str, coerced_keyframes) + # Undo locates the track by (path, type) at undo time rather than caching + # an index captured at do time. Cached indices go stale if any other track + # mutation lands between do and undo (Godot editor, another MCP call, etc.) + _undo_redo.add_undo_method(self, "_undo_remove_track_by_path", anim, track_path, Animation.TYPE_VALUE) + _undo_redo.commit_action() + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "track_path": track_path, + "interpolation": interp_str, + "keyframe_count": keyframes.size(), + "undoable": true, + } + } + + +## Insert a pre-coerced track into the animation. Callers must coerce +## values against the target property before calling this (see +## AnimationValues.coerce_value_for_track) — this method runs inside the +## undo do-method path where error propagation isn't possible. +func _do_add_property_track( + anim: Animation, + track_path: String, + interp_str: String, + keyframes: Array, +) -> void: + var idx := anim.add_track(Animation.TYPE_VALUE) + anim.track_set_path(idx, NodePath(track_path)) + anim.track_set_interpolation_type(idx, _INTERP_MODES.get(interp_str, Animation.INTERPOLATION_LINEAR)) + for kf in keyframes: + var t: float = float(kf.get("time", 0.0)) + var trans: float = AnimationValues.parse_transition(kf.get("transition", "linear")) + anim.track_insert_key(idx, t, kf.get("value"), trans) + + +# ============================================================================ +# animation_add_method_track +# ============================================================================ + +func add_method_track(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("animation_name", "") + var target_path: String = params.get("target_node_path", "") + var keyframes = params.get("keyframes", []) + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if anim_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: animation_name") + if target_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: target_node_path") + if target_path.contains(":"): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "target_node_path is a bare NodePath without ':property' (got '%s'). " % target_path + + "Method name goes in each keyframe's 'method' field, not the path.") + if typeof(keyframes) != TYPE_ARRAY or keyframes.is_empty(): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "keyframes must be a non-empty array") + + for kf in keyframes: + if typeof(kf) != TYPE_DICTIONARY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Each keyframe must be a dictionary") + if not "time" in kf: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Each keyframe must have a 'time' field") + if not "method" in kf: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Each keyframe must have a 'method' field") + var method_field = kf.get("method") + if typeof(method_field) != TYPE_STRING or (method_field as String).is_empty(): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "'method' must be a non-empty string") + if kf.has("args") and typeof(kf.get("args")) != TYPE_ARRAY: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "'args' must be an array if provided (got %s)" % type_string(typeof(kf.get("args")))) + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + var anim_resolved := _resolve_animation(player, anim_name) + if anim_resolved.has("error"): + return anim_resolved + var anim: Animation = anim_resolved.animation + + _create_scene_pinned_action("MCP: Add method track %s to %s" % [target_path, anim_name]) + _undo_redo.add_do_method(self, "_do_add_method_track", anim, target_path, keyframes) + # Undo locates the track by (path, type) at undo time — see add_property_track. + _undo_redo.add_undo_method(self, "_undo_remove_track_by_path", anim, target_path, Animation.TYPE_METHOD) + _undo_redo.commit_action() + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "target_node_path": target_path, + "keyframe_count": keyframes.size(), + "undoable": true, + } + } + + +## Remove a track identified by (path, type) at undo time. Robust to +## history interleaving: if another track was added since the do, the +## find_track call still resolves to the correct index. Returns silently +## if the track is no longer present (e.g. a prior undo already removed it). +func _undo_remove_track_by_path(anim: Animation, track_path: String, track_type: int) -> void: + var idx := anim.find_track(NodePath(track_path), track_type) + if idx >= 0: + anim.remove_track(idx) + + +func _do_add_method_track(anim: Animation, target_path: String, keyframes: Array) -> void: + var idx := anim.add_track(Animation.TYPE_METHOD) + anim.track_set_path(idx, NodePath(target_path)) + for kf in keyframes: + var t: float = float(kf.get("time", 0.0)) + var method_name: String = str(kf.get("method", "")) + var args: Array = kf.get("args", []) + anim.track_insert_key(idx, t, {"method": method_name, "args": args}) + + +# ============================================================================ +# animation_set_autoplay +# ============================================================================ + +func set_autoplay(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("animation_name", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + # Allow empty string to clear autoplay; otherwise validate the name exists. + if not anim_name.is_empty() and not player.has_animation(anim_name): + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Animation '%s' not found on player at %s" % [anim_name, player_path]) + + var old_autoplay: String = player.autoplay + + _undo_redo.create_action("MCP: Set autoplay %s on %s" % [anim_name, player_path]) + _undo_redo.add_do_property(player, "autoplay", anim_name) + _undo_redo.add_undo_property(player, "autoplay", old_autoplay) + _undo_redo.commit_action() + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "previous_autoplay": old_autoplay, + "cleared": anim_name.is_empty(), + "undoable": true, + } + } + + +# ============================================================================ +# animation_play (dev ergonomics — not saved with scene) +# ============================================================================ + +func play(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("animation_name", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + if not anim_name.is_empty() and not player.has_animation(anim_name): + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Animation '%s' not found on player at %s" % [anim_name, player_path]) + + player.play(anim_name) + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "undoable": false, + "reason": "Runtime playback state — not saved with scene", + } + } + + +# ============================================================================ +# animation_stop (dev ergonomics — not saved with scene) +# ============================================================================ + +func stop(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + player.stop() + + return { + "data": { + "player_path": player_path, + "undoable": false, + "reason": "Runtime playback state — not saved with scene", + } + } + + +# ============================================================================ +# animation_create_simple (composer) +# ============================================================================ + +func create_simple(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("name", "") + var tweens = params.get("tweens", []) + var loop_mode_str: String = params.get("loop_mode", "none") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if anim_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: name") + if typeof(tweens) != TYPE_ARRAY or tweens.is_empty(): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "tweens must be a non-empty array") + if not _LOOP_MODES.has(loop_mode_str): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid loop_mode '%s'. Valid: %s" % [loop_mode_str, ", ".join(_LOOP_MODES.keys())]) + + # Validate all tween specs before touching the scene. + var seen_paths := {} + for spec in tweens: + if typeof(spec) != TYPE_DICTIONARY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Each tween spec must be a dictionary") + for field in ["target", "property", "from", "to", "duration"]: + if not field in spec: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, + "Each tween spec must have '%s'" % field) + if float(spec.get("duration", 0.0)) <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "tween 'duration' must be > 0") + var dup_key: String = str(spec.target) + ":" + str(spec.property) + if seen_paths.has(dup_key): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Duplicate tween target '%s' — merge keyframes into a single track " % dup_key + + "via animation_add_property_track instead of two separate tweens.") + seen_paths[dup_key] = true + + # Compute/validate length before resolving the player — a fresh auto-created + # AnimationPlayer is a detached Node that leaks if we return after creation. + var has_length: bool = params.has("length") and params.get("length") != null + var computed_length: float = 0.0 + if has_length: + computed_length = float(params.get("length")) + if computed_length <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "'length' must be > 0 when provided (got %s)" % str(params.get("length"))) + else: + for spec in tweens: + var end_time: float = float(spec.get("delay", 0.0)) + float(spec.get("duration", 0.0)) + if end_time > computed_length: + computed_length = end_time + if computed_length <= 0.0: + computed_length = 1.0 + + var resolved := _resolve_player(player_path, true) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + var library: AnimationLibrary = resolved.library + var created_player: bool = resolved.get("player_created", false) + var player_parent: Node = resolved.get("player_parent", null) + var created_library := false + if library == null: + library = AnimationLibrary.new() + created_library = true + + var overwrite: bool = params.get("overwrite", false) + var old_anim: Animation = null + if library.has_animation(anim_name): + if not overwrite: + if created_player: + player.queue_free() + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Animation '%s' already exists. Pass overwrite=true or delete it first." % anim_name) + old_anim = library.get_animation(anim_name) + + # Pre-coerce all tween values before touching the anim — coercion errors + # surface as INVALID_PARAMS, not silent garbage keyframes. + # When the player was auto-created, it isn't in the tree yet — pass its + # future parent so the coercer can still resolve target property types. + var coerce_root: Node = player_parent if created_player else null + var per_track_keyframes: Array = [] + for spec in tweens: + var target: String = str(spec.get("target", "")) + var property: String = str(spec.get("property", "")) + var track_path: String = target + ":" + property + var duration: float = float(spec.get("duration", 1.0)) + var delay: float = float(spec.get("delay", 0.0)) + var trans_str = spec.get("transition", "linear") + var from_result := AnimationValues.coerce_value_for_track(spec.get("from"), track_path, player, coerce_root) + if from_result.has("error"): + if created_player: + player.queue_free() + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "tween '%s': %s" % [track_path, from_result.error]) + var to_result := AnimationValues.coerce_value_for_track(spec.get("to"), track_path, player, coerce_root) + if to_result.has("error"): + if created_player: + player.queue_free() + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "tween '%s': %s" % [track_path, to_result.error]) + per_track_keyframes.append({ + "track_path": track_path, + "keyframes": [ + {"time": delay, "value": from_result.ok, "transition": trans_str}, + {"time": delay + duration, "value": to_result.ok, "transition": trans_str}, + ], + }) + + # Build the animation fully in memory before touching the undo stack. + var anim := Animation.new() + anim.length = computed_length + anim.loop_mode = _LOOP_MODES[loop_mode_str] + + for entry in per_track_keyframes: + _do_add_property_track(anim, entry.track_path, "linear", entry.keyframes) + + # One atomic undo action — bundles player creation (if any), library + # creation (if any), and the animation add. A single Ctrl-Z rolls back all. + _commit_animation_add("MCP: Create animation %s (%d tracks)" % [anim_name, anim.get_track_count()], + player, library, created_library, anim_name, anim, old_anim, + created_player, player_parent) + + return { + "data": { + "player_path": player_path, + "name": anim_name, + "length": computed_length, + "loop_mode": loop_mode_str, + "track_count": anim.get_track_count(), + "library_created": created_library or created_player, + "animation_player_created": created_player, + "overwritten": old_anim != null, + "undoable": true, + } + } + + +# ============================================================================ +# Proxies — preset_* and read methods live in the submodules. Kept here so +# the dispatcher registrations and `_handler.method(...)` test fixtures stay +# unchanged across the split. +# ============================================================================ + +func preset_fade(params: Dictionary) -> Dictionary: + return _presets.preset_fade(params) + + +func preset_slide(params: Dictionary) -> Dictionary: + return _presets.preset_slide(params) + + +func preset_shake(params: Dictionary) -> Dictionary: + return _presets.preset_shake(params) + + +func preset_pulse(params: Dictionary) -> Dictionary: + return _presets.preset_pulse(params) + + +func list_animations(params: Dictionary) -> Dictionary: + return _values.list_animations(params) + + +func get_animation(params: Dictionary) -> Dictionary: + return _values.get_animation(params) + + +func validate_animation(params: Dictionary) -> Dictionary: + return _values.validate_animation(params) + + +# ============================================================================ +# Helpers — undo +# ============================================================================ + +## Shared undo setup for create_animation and create_simple. Handles fresh- +## create, overwrite, library auto-create, and player auto-create in a single +## atomic action. When `created_player` is true, the player already has the +## library attached (eagerly, from `_instantiate_player`) and the library +## doesn't need its own undo bookkeeping — it rides along with the add_child. +func _commit_animation_add( + action_label: String, + player: AnimationPlayer, + library: AnimationLibrary, + created_library: bool, + anim_name: String, + anim: Animation, + old_anim: Animation, ## null when not overwriting + created_player: bool = false, + player_parent: Node = null, +) -> void: + _undo_redo.create_action(action_label) + if created_player: + var scene_root := EditorInterface.get_edited_scene_root() + _undo_redo.add_do_method(player_parent, "add_child", player, true) + _undo_redo.add_do_method(player, "set_owner", scene_root) + _undo_redo.add_do_reference(player) + _undo_redo.add_do_reference(library) + _undo_redo.add_undo_method(player_parent, "remove_child", player) + elif created_library: + _undo_redo.add_do_method(player, "add_animation_library", "", library) + _undo_redo.add_undo_method(player, "remove_animation_library", "") + _undo_redo.add_do_reference(library) + if old_anim != null: + _undo_redo.add_do_method(library, "remove_animation", anim_name) + _undo_redo.add_do_method(library, "add_animation", anim_name, anim) + if old_anim != null: + _undo_redo.add_undo_method(library, "remove_animation", anim_name) + _undo_redo.add_undo_method(library, "add_animation", anim_name, old_anim) + _undo_redo.add_do_reference(old_anim) + else: + _undo_redo.add_undo_method(library, "remove_animation", anim_name) + _undo_redo.add_do_reference(anim) + _undo_redo.commit_action() + + +## Open a `create_action` pinned to the edited scene's history. +## +## Without an explicit context, `add_do_method(self, ...)` against a +## RefCounted handler lands in GLOBAL_HISTORY while sibling actions whose +## first do-target is a Resource (e.g. AnimationLibrary) land in the scene's +## history. Mismatched histories make the test-side `editor_undo` helper +## (walks scene first) undo the wrong action, and break batch_handler's +## rollback. Mirrors `camera_handler.gd`'s identical pinning rationale. +func _create_scene_pinned_action(action_label: String) -> void: + _undo_redo.create_action( + action_label, UndoRedo.MERGE_DISABLE, EditorInterface.get_edited_scene_root(), + ) + + +# ============================================================================ +# Helpers — resolution +# ============================================================================ + +## Resolve an AnimationPlayer and its default library for write operations. +## Returns {player, library, player_created, player_parent} on success, or an +## error dict. library is null if the player exists but has no default library +## yet — callers bundle an `add_animation_library` step into their undo action. +## +## When `create_if_missing` is true and `player_path` resolves to nothing, a +## fresh AnimationPlayer is instantiated (with an empty default library attached +## eagerly) but is NOT added to the scene tree — callers must bundle the +## add_child step into their undo action via `_commit_animation_add`. +## If the resolved node exists but isn't an AnimationPlayer, that's still an +## error — we don't clobber an existing node of a different type. +func _resolve_player(player_path: String, create_if_missing: bool = false) -> Dictionary: + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + var node := McpScenePath.resolve(player_path, scene_root) + if node == null: + if not create_if_missing: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_node_error(player_path, scene_root)) + return _instantiate_player(player_path, scene_root) + if not node is AnimationPlayer: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "Node at %s is not an AnimationPlayer (got %s)" % [player_path, node.get_class()]) + var player := node as AnimationPlayer + var lib: AnimationLibrary = null + if player.has_animation_library(""): + lib = player.get_animation_library("") + return {"player": player, "library": lib, "player_created": false, "player_parent": null} + + +## Build a new AnimationPlayer (with empty default library) for insertion under +## the parent implied by `player_path`. Returns an error dict if the parent +## can't be resolved or the path has no usable leaf name. +func _instantiate_player(player_path: String, scene_root: Node) -> Dictionary: + var slash := player_path.rfind("/") + var parent_path: String + var player_name: String + if slash < 0: + parent_path = "" + player_name = player_path + else: + parent_path = player_path.substr(0, slash) + player_name = player_path.substr(slash + 1) + if player_name.is_empty(): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Cannot auto-create AnimationPlayer: player_path '%s' has no leaf name" % player_path) + var parent: Node + if parent_path.is_empty(): + parent = scene_root + else: + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, + "Cannot auto-create AnimationPlayer at %s: %s" % [ + player_path, McpScenePath.format_parent_error(parent_path, scene_root)]) + var new_player := AnimationPlayer.new() + new_player.name = player_name + var lib := AnimationLibrary.new() + new_player.add_animation_library("", lib) + return { + "player": new_player, + "library": lib, + "player_created": true, + "player_parent": parent, + } + + +## Resolve for read operations (no library requirement). +func _resolve_player_read(player_path: String) -> Dictionary: + var resolved := McpNodeValidator.resolve_or_error(player_path, "player_path") + if resolved.has("error"): + return resolved + var node: Node = resolved.node + if not node is AnimationPlayer: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "Node at %s is not an AnimationPlayer (got %s)" % [player_path, node.get_class()]) + return {"player": node as AnimationPlayer} + + +## Resolve an animation by name, searching all libraries. +## Accepts bare clip names ("idle") and library-qualified names ("moves/idle") +## as returned by `list_animations` for non-default libraries. +func _resolve_animation(player: AnimationPlayer, anim_name: String) -> Dictionary: + if not player.has_animation(anim_name): + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Animation '%s' not found on player. Available: %s" % [ + anim_name, + ", ".join(Array(player.get_animation_list())) + ]) + # If the caller passed "library/clip", look up in that specific library. + var slash := anim_name.find("/") + if slash >= 0: + var lib_key := anim_name.substr(0, slash) + var clip_key := anim_name.substr(slash + 1) + if player.has_animation_library(lib_key): + var lib: AnimationLibrary = player.get_animation_library(lib_key) + if lib.has_animation(clip_key): + return {"animation": lib.get_animation(clip_key), "library": lib, "library_key": lib_key} + # Otherwise scan libraries for a bare clip name. + for lib_name in player.get_animation_library_list(): + var lib2: AnimationLibrary = player.get_animation_library(lib_name) + if lib2.has_animation(anim_name): + return {"animation": lib2.get_animation(anim_name), "library": lib2, "library_key": lib_name} + # Fallback — shouldn't happen if has_animation returned true. + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Animation found by player but not in any library") diff --git a/addons/godot_ai/handlers/animation_handler.gd.uid b/addons/godot_ai/handlers/animation_handler.gd.uid new file mode 100644 index 0000000..934f665 --- /dev/null +++ b/addons/godot_ai/handlers/animation_handler.gd.uid @@ -0,0 +1 @@ +uid://c0jrius46xsd4 diff --git a/addons/godot_ai/handlers/animation_presets.gd b/addons/godot_ai/handlers/animation_presets.gd new file mode 100644 index 0000000..40f1ddc --- /dev/null +++ b/addons/godot_ai/handlers/animation_presets.gd @@ -0,0 +1,536 @@ +@tool +extends RefCounted + +## Curated motion presets for the AnimationPlayer surface. +## +## Each preset_* method: +## 1. Validates params + resolves the player (auto-creating its default lib). +## 2. Resolves the target node + classifies it as control / 2d / 3d. +## 3. Builds a single-track Animation with shape-appropriate keyframes. +## 4. Commits the add through the handler's shared `_commit_animation_add` +## so a single Ctrl-Z rolls back any auto-created library + the animation. +## +## Holds a WeakRef back to the AnimationHandler instance so the handler can +## continue to own this module strongly via `_presets` without forming a +## RefCounted cycle. Resolution / undo helpers live on the handler — keeping +## the `_undo_redo` member single-source there avoids drift. + + +const AnimationValues := preload("res://addons/godot_ai/handlers/animation_values.gd") +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const ScenePath := preload("res://addons/godot_ai/utils/scene_path.gd") + + +var _handler_weak: WeakRef + + +func _init(handler) -> void: + _handler_weak = weakref(handler) + + +func _h(): + return _handler_weak.get_ref() + + +# ============================================================================ +# animation_preset_fade +# ============================================================================ + +func preset_fade(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var target_path: String = params.get("target_path", "") + var mode: String = params.get("mode", "in") + var duration: float = float(params.get("duration", 0.5)) + var anim_name: String = params.get("animation_name", "") + var overwrite: bool = params.get("overwrite", false) + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if target_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: target_path") + if mode != "in" and mode != "out": + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid mode '%s'. Valid: 'in', 'out'" % mode) + if duration <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'duration' must be > 0") + + var handler = _h() + if handler == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "AnimationHandler not available", false) + var resolved: Dictionary = handler._resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + var library: AnimationLibrary = resolved.library + var created_library := false + if library == null: + library = AnimationLibrary.new() + created_library = true + + var target_resolved := _resolve_preset_target(player, target_path) + if target_resolved.has("error"): + return target_resolved + var target: Node = target_resolved.node + var track_target: String = target_resolved.track_path_root + + # Fade requires a `modulate` property (CanvasItem/Control/Node2D/Sprite3D/etc). + var has_modulate := false + for p in target.get_property_list(): + if p.name == "modulate": + has_modulate = true + break + if not has_modulate: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "Target '%s' (class %s) has no 'modulate' property — fade requires a CanvasItem, Control, Node2D, or Sprite3D" + % [target_path, target.get_class()]) + + if anim_name.is_empty(): + anim_name = "fade_%s" % mode + + var old_anim: Animation = null + if library.has_animation(anim_name): + if not overwrite: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Animation '%s' already exists. Pass overwrite=true or delete it first." % anim_name) + old_anim = library.get_animation(anim_name) + + var start_a: float = 0.0 if mode == "in" else 1.0 + var end_a: float = 1.0 if mode == "in" else 0.0 + + var anim := Animation.new() + anim.length = duration + anim.loop_mode = Animation.LOOP_NONE + + var track_path := "%s:modulate:a" % track_target + handler._do_add_property_track(anim, track_path, "linear", [ + {"time": 0.0, "value": start_a, "transition": "linear"}, + {"time": duration, "value": end_a, "transition": "linear"}, + ]) + + handler._commit_animation_add( + "MCP: Create animation %s" % anim_name, + player, library, created_library, anim_name, anim, old_anim, + ) + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "mode": mode, + "length": duration, + "track_count": anim.get_track_count(), + "library_created": created_library, + "overwritten": old_anim != null, + "undoable": true, + } + } + + +# ============================================================================ +# animation_preset_slide +# ============================================================================ + +func preset_slide(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var target_path: String = params.get("target_path", "") + var direction: String = params.get("direction", "left") + var mode: String = params.get("mode", "in") + var duration: float = float(params.get("duration", 0.4)) + var anim_name: String = params.get("animation_name", "") + var overwrite: bool = params.get("overwrite", false) + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if target_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: target_path") + if not ["left", "right", "up", "down"].has(direction): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid direction '%s'. Valid: 'left', 'right', 'up', 'down'" % direction) + if mode != "in" and mode != "out": + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid mode '%s'. Valid: 'in', 'out'" % mode) + if duration <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'duration' must be > 0") + + var handler = _h() + if handler == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "AnimationHandler not available", false) + var resolved: Dictionary = handler._resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + var library: AnimationLibrary = resolved.library + var created_library := false + if library == null: + library = AnimationLibrary.new() + created_library = true + + var target_resolved := _resolve_preset_target(player, target_path) + if target_resolved.has("error"): + return target_resolved + var target = target_resolved.node + var kind: String = target_resolved.kind + var track_target: String = target_resolved.track_path_root + + # Default distance picks 3D units vs screen pixels based on target kind. + var default_distance: float = 1.0 if kind == "3d" else 100.0 + var distance: float = float(params.get("distance", default_distance)) + if distance == 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'distance' must be non-zero") + + var offset: Variant = _direction_offset(kind, direction, distance) + var current_pos: Variant = target.position + var start_pos: Variant + var end_pos: Variant + if mode == "in": + start_pos = current_pos + offset + end_pos = current_pos + else: + start_pos = current_pos + end_pos = current_pos + offset + + if anim_name.is_empty(): + anim_name = "slide_%s_%s" % [mode, direction] + + var old_anim: Animation = null + if library.has_animation(anim_name): + if not overwrite: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Animation '%s' already exists. Pass overwrite=true or delete it first." % anim_name) + old_anim = library.get_animation(anim_name) + + var anim := Animation.new() + anim.length = duration + anim.loop_mode = Animation.LOOP_NONE + + var track_path := "%s:position" % track_target + handler._do_add_property_track(anim, track_path, "linear", [ + {"time": 0.0, "value": start_pos, "transition": "linear"}, + {"time": duration, "value": end_pos, "transition": "linear"}, + ]) + + handler._commit_animation_add( + "MCP: Create animation %s" % anim_name, + player, library, created_library, anim_name, anim, old_anim, + ) + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "direction": direction, + "mode": mode, + "distance": distance, + "length": duration, + "track_count": anim.get_track_count(), + "library_created": created_library, + "overwritten": old_anim != null, + "undoable": true, + } + } + + +# ============================================================================ +# animation_preset_shake +# ============================================================================ + +func preset_shake(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var target_path: String = params.get("target_path", "") + var duration: float = float(params.get("duration", 0.3)) + var frequency: float = float(params.get("frequency", 30.0)) + var rng_seed: int = int(params.get("seed", 0)) + var anim_name: String = params.get("animation_name", "") + var overwrite: bool = params.get("overwrite", false) + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if target_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: target_path") + if duration <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'duration' must be > 0") + if frequency <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'frequency' must be > 0") + + var handler = _h() + if handler == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "AnimationHandler not available", false) + var resolved: Dictionary = handler._resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + var library: AnimationLibrary = resolved.library + var created_library := false + if library == null: + library = AnimationLibrary.new() + created_library = true + + var target_resolved := _resolve_preset_target(player, target_path) + if target_resolved.has("error"): + return target_resolved + var target = target_resolved.node + var kind: String = target_resolved.kind + var track_target: String = target_resolved.track_path_root + + var default_intensity: float = 0.1 if kind == "3d" else 10.0 + var intensity: float = float(params.get("intensity", default_intensity)) + if intensity <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'intensity' must be > 0") + + if anim_name.is_empty(): + anim_name = "shake" + + var old_anim: Animation = null + if library.has_animation(anim_name): + if not overwrite: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Animation '%s' already exists. Pass overwrite=true or delete it first." % anim_name) + old_anim = library.get_animation(anim_name) + + var rng := RandomNumberGenerator.new() + if rng_seed != 0: + rng.seed = rng_seed + else: + rng.randomize() + + # Samples between t=0 and t=duration (exclusive); bookended by at-rest keys. + var sample_count: int = int(ceil(frequency * duration)) + if sample_count < 2: + sample_count = 2 + + var current_pos: Variant = target.position + var kfs: Array = [] + kfs.append({"time": 0.0, "value": current_pos, "transition": "linear"}) + for i in range(1, sample_count): + var t: float = (float(i) / float(sample_count)) * duration + var jx: float = rng.randf_range(-intensity, intensity) + var jy: float = rng.randf_range(-intensity, intensity) + var jittered: Variant + if kind == "3d": + var jz: float = rng.randf_range(-intensity, intensity) + jittered = current_pos + Vector3(jx, jy, jz) + else: + jittered = current_pos + Vector2(jx, jy) + kfs.append({"time": t, "value": jittered, "transition": "linear"}) + kfs.append({"time": duration, "value": current_pos, "transition": "linear"}) + + var anim := Animation.new() + anim.length = duration + anim.loop_mode = Animation.LOOP_NONE + + var track_path := "%s:position" % track_target + handler._do_add_property_track(anim, track_path, "linear", kfs) + + handler._commit_animation_add( + "MCP: Create animation %s" % anim_name, + player, library, created_library, anim_name, anim, old_anim, + ) + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "length": duration, + "frequency": frequency, + "intensity": intensity, + "keyframe_count": kfs.size(), + "track_count": anim.get_track_count(), + "library_created": created_library, + "overwritten": old_anim != null, + "undoable": true, + } + } + + +# ============================================================================ +# animation_preset_pulse +# ============================================================================ + +func preset_pulse(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var target_path: String = params.get("target_path", "") + var from_scale: float = float(params.get("from_scale", 1.0)) + var to_scale: float = float(params.get("to_scale", 1.1)) + var duration: float = float(params.get("duration", 0.4)) + var anim_name: String = params.get("animation_name", "") + var overwrite: bool = params.get("overwrite", false) + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if target_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: target_path") + if duration <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'duration' must be > 0") + if from_scale <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'from_scale' must be > 0") + if to_scale <= 0.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "'to_scale' must be > 0") + + var handler = _h() + if handler == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "AnimationHandler not available", false) + var resolved: Dictionary = handler._resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + var library: AnimationLibrary = resolved.library + var created_library := false + if library == null: + library = AnimationLibrary.new() + created_library = true + + var target_resolved := _resolve_preset_target(player, target_path) + if target_resolved.has("error"): + return target_resolved + var kind: String = target_resolved.kind + var track_target: String = target_resolved.track_path_root + + if anim_name.is_empty(): + anim_name = "pulse" + + var old_anim: Animation = null + if library.has_animation(anim_name): + if not overwrite: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Animation '%s' already exists. Pass overwrite=true or delete it first." % anim_name) + old_anim = library.get_animation(anim_name) + + var from_vec: Variant + var to_vec: Variant + if kind == "3d": + from_vec = Vector3(from_scale, from_scale, from_scale) + to_vec = Vector3(to_scale, to_scale, to_scale) + else: + from_vec = Vector2(from_scale, from_scale) + to_vec = Vector2(to_scale, to_scale) + + var anim := Animation.new() + anim.length = duration + anim.loop_mode = Animation.LOOP_NONE + + var track_path := "%s:scale" % track_target + handler._do_add_property_track(anim, track_path, "linear", [ + {"time": 0.0, "value": from_vec, "transition": "linear"}, + {"time": duration * 0.5, "value": to_vec, "transition": "linear"}, + {"time": duration, "value": from_vec, "transition": "linear"}, + ]) + + handler._commit_animation_add( + "MCP: Create animation %s" % anim_name, + player, library, created_library, anim_name, anim, old_anim, + ) + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "from_scale": from_scale, + "to_scale": to_scale, + "length": duration, + "track_count": anim.get_track_count(), + "library_created": created_library, + "overwritten": old_anim != null, + "undoable": true, + } + } + + +# ============================================================================ +# Helpers — preset resolution +# ============================================================================ + +## Resolve a preset target node and classify its transform kind. +## +## Accepts two `target_path` shapes: +## * Scene-absolute (starts with "/") — resolved through `ScenePath.resolve`, +## matching the convention used by every other scene-mutating tool. Targets +## outside the player's `root_node` subtree are converted to `..`-prefixed +## paths via `root_node.get_path_to(target)`, mirroring what the relative +## form accepts and how Godot stores track paths. +## * Relative — used as-is against the player's `root_node`, matching how +## animation tracks themselves are stored. +## +## Returns `{node, kind, track_path_root}` where `track_path_root` is the path +## (relative to `root_node`) that callers should embed in the track path. For +## scene-absolute inputs this is the converted relative path; for relative +## inputs it equals the input. `kind` ∈ {"control", "2d", "3d"}. +## +## Mirrors the same root-node fallback that +## `AnimationValues.resolve_track_prop_context` uses so tool inputs match how +## the track path will resolve at playback. +func _resolve_preset_target(player: AnimationPlayer, target_path: String) -> Dictionary: + var root_node := AnimationValues.player_root_node(player) + if root_node == null: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "AnimationPlayer at %s has no resolvable root_node (is the scene open?)" % str(player.get_path())) + + var target: Node = null + var track_path_root: String = target_path + if target_path.begins_with("/"): + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root == null: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Cannot resolve scene-absolute target_path '%s': no scene open" % target_path) + target = ScenePath.resolve(target_path, scene_root) + if target == null: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + ScenePath.format_node_error(target_path, scene_root)) + # Convert to a root_node-relative path. For targets outside the + # subtree this yields a `..`-prefixed path, matching what the + # relative form already accepts (root_node.get_node_or_null + # resolves `..` segments) and what Godot's animation engine + # stores natively. + track_path_root = str(root_node.get_path_to(target)) + else: + target = root_node.get_node_or_null(target_path) + if target == null: + # root_node.get_path() leaks the editor's SubViewport-wrapped + # path; use the clean scene-relative form so the hint is + # actionable. + var scene_root := EditorInterface.get_edited_scene_root() + var root_hint := ScenePath.from_node(root_node, scene_root) if scene_root != null else str(root_node.name) + var abs_example := "/%s/path/to/target" % scene_root.name if scene_root != null else "/SceneRoot/path/to/target" + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + ("Target node not found at '%s' (resolved relative to AnimationPlayer's root_node '%s'). " + + "Pass a path relative to root_node (e.g. \"path/to/target\") or a scene-absolute path (e.g. \"%s\").") + % [target_path, root_hint, abs_example]) + + var kind: String + if target is Control: + kind = "control" + elif target is Node2D: + kind = "2d" + elif target is Node3D: + kind = "3d" + else: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "Target '%s' must be a Control, Node2D, or Node3D (got %s)" % [target_path, target.get_class()]) + return {"node": target, "kind": kind, "track_path_root": track_path_root} + + +## Build a directional offset for slide presets. +## Axis conventions: +## Control + Node2D (screen-space, y-down): left/right = ∓x, up = -y, down = +y +## Node3D (world-up): left/right = ∓x, up = +y, down = -y +static func _direction_offset(kind: String, direction: String, distance: float) -> Variant: + if kind == "3d": + match direction: + "left": return Vector3(-distance, 0.0, 0.0) + "right": return Vector3(distance, 0.0, 0.0) + "up": return Vector3(0.0, distance, 0.0) + "down": return Vector3(0.0, -distance, 0.0) + else: + match direction: + "left": return Vector2(-distance, 0.0) + "right": return Vector2(distance, 0.0) + "up": return Vector2(0.0, -distance) + "down": return Vector2(0.0, distance) + return null diff --git a/addons/godot_ai/handlers/animation_presets.gd.uid b/addons/godot_ai/handlers/animation_presets.gd.uid new file mode 100644 index 0000000..f463501 --- /dev/null +++ b/addons/godot_ai/handlers/animation_presets.gd.uid @@ -0,0 +1 @@ +uid://c4s3h78bwvr6w diff --git a/addons/godot_ai/handlers/animation_values.gd b/addons/godot_ai/handlers/animation_values.gd new file mode 100644 index 0000000..b1553df --- /dev/null +++ b/addons/godot_ai/handlers/animation_values.gd @@ -0,0 +1,442 @@ +@tool +extends RefCounted + +const VariantSerializer := preload("res://addons/godot_ai/utils/variant_serializer.gd") + +## Read-only animation introspection + shared value-coercion / serialization. +## +## Holds: +## - Static helpers used by both the write handler (track building, simple +## composer) and the preset module (target/property resolution). +## - Instance methods that back the read MCP ops: animation_list, +## animation_get, animation_validate. +## +## The instance methods need the handler to resolve players / animations. +## To keep that without introducing a RefCounted cycle (the handler holds a +## strong ref to this module via `_values`), the back-pointer is a WeakRef. +## When the handler is freed during plugin teardown, _h() returns null and +## the (no-longer-routable) calls short-circuit to a generic editor-not-ready +## error — matches the dispatcher already being torn down at that point. + + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const PropertyErrors := preload("res://addons/godot_ai/handlers/_property_errors.gd") + + +const _NAMED_TRANSITIONS := { + "linear": 1.0, + "ease_in": 2.0, + "ease_out": 0.5, + "ease_in_out": -2.0, +} + +## Component letters accepted on each aggregate base type, paired with the +## scalar Variant type the component resolves to. A subpath like `position:y` +## on a Vector3 maps to TYPE_FLOAT; on a Vector3i it maps to TYPE_INT. +const _SUBPATH_COMPONENTS := { + TYPE_VECTOR2: ["xy", TYPE_FLOAT], + TYPE_VECTOR3: ["xyz", TYPE_FLOAT], + TYPE_VECTOR4: ["xyzw", TYPE_FLOAT], + TYPE_QUATERNION: ["xyzw", TYPE_FLOAT], + TYPE_COLOR: ["rgba", TYPE_FLOAT], + TYPE_VECTOR2I: ["xy", TYPE_INT], + TYPE_VECTOR3I: ["xyz", TYPE_INT], + TYPE_VECTOR4I: ["xyzw", TYPE_INT], +} + + +var _handler_weak: WeakRef + + +func _init(handler) -> void: + _handler_weak = weakref(handler) + + +func _h(): + return _handler_weak.get_ref() + + +# ============================================================================ +# animation_list (read) +# ============================================================================ + +func list_animations(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + + var handler = _h() + if handler == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "AnimationHandler not available", false) + var resolved: Dictionary = handler._resolve_player_read(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + var animations: Array[Dictionary] = [] + for lib_name in player.get_animation_library_list(): + var lib: AnimationLibrary = player.get_animation_library(lib_name) + for anim_name in lib.get_animation_list(): + var anim: Animation = lib.get_animation(anim_name) + var display_name: String = anim_name if lib_name == "" else "%s/%s" % [lib_name, anim_name] + animations.append({ + "name": display_name, + "length": anim.length, + "loop_mode": loop_mode_to_string(anim.loop_mode), + "track_count": anim.get_track_count(), + }) + + return { + "data": { + "player_path": player_path, + "animations": animations, + "count": animations.size(), + } + } + + +# ============================================================================ +# animation_get (read) +# ============================================================================ + +func get_animation(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("animation_name", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if anim_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: animation_name") + + var handler = _h() + if handler == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "AnimationHandler not available", false) + var resolved: Dictionary = handler._resolve_player_read(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + var anim_resolved: Dictionary = handler._resolve_animation(player, anim_name) + if anim_resolved.has("error"): + return anim_resolved + var anim: Animation = anim_resolved.animation + + var tracks: Array[Dictionary] = [] + for i in anim.get_track_count(): + var track_type := anim.track_get_type(i) + var type_name := track_type_to_string(track_type) + var keys: Array[Dictionary] = [] + for k in anim.track_get_key_count(i): + var key_val = anim.track_get_key_value(i, k) + keys.append({ + "time": anim.track_get_key_time(i, k), + "value": serialize_value(key_val), + "transition": anim.track_get_key_transition(i, k), + }) + tracks.append({ + "index": i, + "type": type_name, + "path": str(anim.track_get_path(i)), + "interpolation": interp_to_string(anim.track_get_interpolation_type(i)), + "key_count": keys.size(), + "keys": keys, + }) + + return { + "data": { + "player_path": player_path, + "name": anim_name, + "length": anim.length, + "loop_mode": loop_mode_to_string(anim.loop_mode), + "track_count": anim.get_track_count(), + "tracks": tracks, + } + } + + +# ============================================================================ +# animation_validate (read-only) +# ============================================================================ + +func validate_animation(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var anim_name: String = params.get("animation_name", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if anim_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: animation_name") + + var handler = _h() + if handler == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "AnimationHandler not available", false) + var resolved: Dictionary = handler._resolve_player_read(player_path) + if resolved.has("error"): + return resolved + var player: AnimationPlayer = resolved.player + + if not player.has_animation(anim_name): + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Animation '%s' not found on player at %s" % [anim_name, player_path]) + + var anim: Animation = player.get_animation(anim_name) + + var root_node := player_root_node(player) + + var broken_tracks: Array[Dictionary] = [] + var valid_count := 0 + + for i in anim.get_track_count(): + var track_path_str := str(anim.track_get_path(i)) + # Split on the FIRST colon (node↔property boundary), not the last. + # Godot's get_node_or_null strips the ":property" tail natively, so + # the valid/broken classification is the same either way — but for + # BROKEN tracks the broken_tracks[].node_path field is what callers + # read to diagnose the missing node, and rfind would surface + # "MissingTarget:modulate" instead of "MissingTarget" for subpath + # tracks like the "Target:modulate:a" shape preset_fade emits. + var colon := track_path_str.find(":") + var node_part: String + if colon >= 0: + node_part = track_path_str.substr(0, colon) + else: + node_part = track_path_str + + var target_node: Node = null + if root_node != null: + target_node = root_node.get_node_or_null(node_part) + + if target_node == null: + broken_tracks.append({ + "index": i, + "path": track_path_str, + "type": track_type_to_string(anim.track_get_type(i)), + "issue": "node_not_found", + "node_path": node_part, + }) + else: + valid_count += 1 + + return { + "data": { + "player_path": player_path, + "animation_name": anim_name, + "track_count": anim.get_track_count(), + "valid_count": valid_count, + "broken_count": broken_tracks.size(), + "broken_tracks": broken_tracks, + "valid": broken_tracks.is_empty(), + } + } + + +# ============================================================================ +# Static helpers — shared with handler + presets +# ============================================================================ + +## Resolve the effective root node an AnimationPlayer animates against. +## Falls back to the player's parent when the explicit root_node NodePath is +## empty or unresolvable. Returns null when the player isn't in the tree. +## +## Mirrors the resolution Godot does at playback time so the validator, +## preset target resolver, and track-property coercer all see the same root. +static func player_root_node(player: AnimationPlayer) -> Node: + if not player.is_inside_tree(): + return null + var rn := player.root_node + if rn != NodePath(): + var n := player.get_node_or_null(rn) + if n != null: + return n + return player.get_parent() + + +## Coerce a JSON value to match the expected Godot type for the given +## track_path. Returns {"ok": value} or {"error": msg}. +## Passes the raw value through when the target node isn't in the scene +## yet (authoring-time path). Errors when the target exists but the +## property doesn't, or when parsing a typed value (Color/Vector2/Vector3) +## clearly fails — better to reject than silently store garbage. +## `override_root_node` lets callers supply the root to resolve target paths +## against when the player isn't in the tree yet (auto-create flow) — the +## player's future parent stands in for the root the AnimationPlayer will +## eventually use. +static func coerce_value_for_track(value: Variant, track_path: String, player: AnimationPlayer, override_root_node: Node = null) -> Dictionary: + var ctx := resolve_track_prop_context(track_path, player, override_root_node) + if ctx.has("error"): + return {"error": ctx.error} + return coerce_with_context(value, ctx) + + +## Resolve a track_path's target property type once, so callers coercing many +## keyframes avoid walking `get_property_list()` on every one. Returns: +## {pass_through: true} — no resolution / authoring-time +## {pass_through: false, prop_type, prop_name} — coerce against this type +## {error: msg} — property not found on target +## +## Supports Godot's native NodePath subpath form `property:sub` (e.g. +## `position:y`, `modulate:a`) — splits on the FIRST colon (node↔property +## boundary), resolves the base property on the target, and for known +## scalar subpaths (x/y/z/w on vectors, r/g/b/a on Color) narrows the +## coerce target to TYPE_FLOAT so JSON numbers land as floats, not dicts. +static func resolve_track_prop_context(track_path: String, player: AnimationPlayer, override_root_node: Node = null) -> Dictionary: + var colon := track_path.find(":") + if colon < 0: + return {"pass_through": true} + + var node_part := track_path.substr(0, colon) + var prop_full := track_path.substr(colon + 1) + + # Property may include a subpath: "position:y", "modulate:a", etc. + var sub_colon := prop_full.find(":") + var prop_base := prop_full if sub_colon < 0 else prop_full.substr(0, sub_colon) + var prop_sub := "" if sub_colon < 0 else prop_full.substr(sub_colon + 1) + + var root_node: Node = override_root_node + if root_node == null: + root_node = player_root_node(player) + if root_node == null: + return {"pass_through": true} + + var target: Node = root_node.get_node_or_null(node_part) + if target == null: + # Target node isn't in the scene yet — authoring-time path. Pass through. + return {"pass_through": true} + + for p in target.get_property_list(): + if p.name == prop_base: + var base_type: int = p.get("type", TYPE_NIL) + var coerce_type := base_type + if not prop_sub.is_empty(): + var sub_type := subpath_component_type(base_type, prop_sub) + if sub_type == TYPE_NIL: + # Unknown subpath component — pass through so Godot's own + # NodePath resolution raises at playback if it's truly bogus, + # rather than fabricating a coerce error for a valid-but- + # uncommon form (e.g. Transform3D subpaths). + return {"pass_through": true} + coerce_type = sub_type + return { + "pass_through": false, + "prop_type": coerce_type, + "prop_name": prop_full, + } + + # Target exists but the property doesn't. Reject loudly — silently storing + # the raw value here produces garbage keyframes at playback time. + return {"error": + "%s (target path: '%s')" % + [PropertyErrors.build_message(target, prop_base), node_part]} + + +## Map a `property:sub` subpath to its scalar component type. Returns +## TYPE_NIL when the base type / subkey pair isn't one we recognise — +## callers pass-through in that case rather than mis-coerce. +static func subpath_component_type(base_type: int, sub: String) -> int: + var entry = _SUBPATH_COMPONENTS.get(base_type) + if entry == null or sub.length() != 1: + return TYPE_NIL + return entry[1] if (entry[0] as String).contains(sub) else TYPE_NIL + + +static func coerce_with_context(value: Variant, ctx: Dictionary) -> Dictionary: + if ctx.get("pass_through", false): + return {"ok": value} + return coerce_for_type(value, ctx.prop_type, ctx.prop_name) + + +## Coerce a single value to the given Godot variant type. Returns +## {"ok": coerced} or {"error": msg}. Unknown types pass through. +static func coerce_for_type(value: Variant, prop_type: int, prop_name: String) -> Dictionary: + match prop_type: + TYPE_COLOR: + ## Canonical strict parser (#714): same shapes as every other + ## color-accepting handler, including [r,g,b(,a)] arrays. + var col = McpJsonValues.parse_color(value) + if col != null: + return {"ok": col} + return {"error": "Cannot coerce value to Color for property '%s' (expected \"#rrggbb(aa)\"/named string, {r,g,b[,a]}, [r,g,b(,a)], or Color)" % prop_name} + TYPE_VECTOR2: + var v2 = McpJsonValues.parse_vector2(value) + if v2 != null: + return {"ok": v2} + return {"error": "Cannot coerce value to Vector2 for property '%s' (expected {x,y}, [x,y], or Vector2)" % prop_name} + TYPE_VECTOR3: + var v3 = McpJsonValues.parse_vector3(value) + if v3 != null: + return {"ok": v3} + return {"error": "Cannot coerce value to Vector3 for property '%s' (expected {x,y,z}, [x,y,z], or Vector3)" % prop_name} + TYPE_FLOAT: + if value is int or value is float: + return {"ok": float(value)} + TYPE_INT: + if value is float or value is int: + return {"ok": int(value)} + TYPE_BOOL: + if value is int or value is float or value is bool: + return {"ok": bool(value)} + return {"ok": value} + + +# ============================================================================ +# Static helpers — parsing + serializing +# ============================================================================ + +## Parse a transition value: named string or raw float. +## Named values live in `_NAMED_TRANSITIONS` so the mapping has a single source. +static func parse_transition(v: Variant) -> float: + if v is float or v is int: + return float(v) + if v is String: + var key: String = (v as String).to_lower() + if _NAMED_TRANSITIONS.has(key): + return float(_NAMED_TRANSITIONS[key]) + return 1.0 + + +## Map an Animation.TrackType enum to a stable string. Unknown types report +## as "unknown" rather than being silently coerced to "method" — callers that +## only produce value/method tracks can ignore the others; clients that want +## to round-trip bezier/audio/etc. get an honest label to key off. +static func track_type_to_string(track_type: int) -> String: + match track_type: + Animation.TYPE_VALUE: return "value" + Animation.TYPE_METHOD: return "method" + Animation.TYPE_POSITION_3D: return "position_3d" + Animation.TYPE_ROTATION_3D: return "rotation_3d" + Animation.TYPE_SCALE_3D: return "scale_3d" + Animation.TYPE_BLEND_SHAPE: return "blend_shape" + Animation.TYPE_BEZIER: return "bezier" + Animation.TYPE_AUDIO: return "audio" + Animation.TYPE_ANIMATION: return "animation" + _: return "unknown" + + +static func loop_mode_to_string(mode: int) -> String: + match mode: + Animation.LOOP_LINEAR: return "linear" + Animation.LOOP_PINGPONG: return "pingpong" + _: return "none" + + +static func interp_to_string(mode: int) -> String: + match mode: + Animation.INTERPOLATION_NEAREST: return "nearest" + Animation.INTERPOLATION_CUBIC: return "cubic" + _: return "linear" + + +## Convert a Godot Variant to a JSON-safe value. +static func serialize_value(value: Variant) -> Variant: + ## Delegates to the shared serializer (#714) — the drifted private copy + ## stringified rotation_3d keyframe Quaternions into opaque text where + ## McpVariantSerializer emits the {x,y,z,w} dict callers can round-trip + ## (it also NaN/Inf-guards floats, matching the wire contract). + return VariantSerializer.serialize(value) diff --git a/addons/godot_ai/handlers/animation_values.gd.uid b/addons/godot_ai/handlers/animation_values.gd.uid new file mode 100644 index 0000000..5d2a8b7 --- /dev/null +++ b/addons/godot_ai/handlers/animation_values.gd.uid @@ -0,0 +1 @@ +uid://bguta2eb8blgf diff --git a/addons/godot_ai/handlers/api_handler.gd b/addons/godot_ai/handlers/api_handler.gd new file mode 100644 index 0000000..acfeda5 --- /dev/null +++ b/addons/godot_ai/handlers/api_handler.gd @@ -0,0 +1,89 @@ +@tool +extends RefCounted + +## Read-only access to version-correct Godot class metadata. + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const ClassIntrospection := preload("res://addons/godot_ai/utils/class_introspection.gd") +const FuzzySuggestions := preload("res://addons/godot_ai/utils/fuzzy_suggestions.gd") + +func get_class_info(params: Dictionary) -> Dictionary: + var requested_class: String = params.get("class_name", "") + if requested_class.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "Missing required param: class_name" + ) + if not ClassDB.class_exists(requested_class): + var script_class := _global_script_class(requested_class) + if not script_class.is_empty(): + return _script_class_error(requested_class, script_class) + return _unknown_class_error(requested_class) + if params.has("limit") and int(params.get("limit")) < 0: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "limit must be >= 0; use limit=0 only when an unlimited section is needed" + ) + var section_check := ClassIntrospection.validate_sections( + params.get("sections", ClassIntrospection.DEFAULT_SECTIONS) + ) + if not section_check.invalid.is_empty(): + return _invalid_sections_error(section_check.invalid) + return {"data": ClassIntrospection.build(requested_class, params)} + + +static func _unknown_class_error(requested_class: String) -> Dictionary: + var suggestions := _suggest_classes(requested_class) + var message := "Unknown Godot class: %s" % requested_class + if not suggestions.is_empty(): + message += ". Did you mean: %s?" % ", ".join(suggestions) + var result := ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, message) + result["error"]["data"] = {"suggestions": suggestions} + return result + + +static func _suggest_classes(requested_class: String) -> Array[String]: + return FuzzySuggestions.rank(requested_class, ClassDB.get_class_list()) + + +static func _global_script_class(requested_class: String) -> Dictionary: + for raw_info in ProjectSettings.get_global_class_list(): + var info: Dictionary = raw_info + if info.get("class", "") == requested_class: + return info + return {} + + +static func _script_class_error(requested_class: String, script_class: Dictionary) -> Dictionary: + var path := str(script_class.get("path", "")) + var base := str(script_class.get("base", "")) + var message := ( + "%s is a project script class, not a ClassDB class. " + + "Use script_manage(op=\"find_symbols\", params={\"path\": \"%s\"}) for script symbols." + ) % [requested_class, path] + var result := ErrorCodes.make(ErrorCodes.WRONG_TYPE, message) + result["error"]["data"] = { + "script_class": true, + "class_name": requested_class, + "base_class": base, + "path": path, + } + return result + + +static func _invalid_sections_error(invalid_sections: Array[String]) -> Dictionary: + var suggestions := {} + for section in invalid_sections: + suggestions[section] = FuzzySuggestions.rank( + section, + ClassIntrospection.SUGGESTABLE_SECTION_TOKENS, + 3, + 0.3 + ) + var message := "Unknown class-info section(s): %s. Valid sections: %s (or \"all\" for all documentation sections; \"inheritors\" must be requested by name)" % [ + ", ".join(invalid_sections), + ", ".join(ClassIntrospection.KNOWN_SECTIONS), + ] + var result := ErrorCodes.make(ErrorCodes.INVALID_PARAMS, message) + result["error"]["data"] = {"suggestions": suggestions} + return result diff --git a/addons/godot_ai/handlers/api_handler.gd.uid b/addons/godot_ai/handlers/api_handler.gd.uid new file mode 100644 index 0000000..f519c48 --- /dev/null +++ b/addons/godot_ai/handlers/api_handler.gd.uid @@ -0,0 +1 @@ +uid://v3rkd7ueunii diff --git a/addons/godot_ai/handlers/audio_handler.gd b/addons/godot_ai/handlers/audio_handler.gd new file mode 100644 index 0000000..79dea56 --- /dev/null +++ b/addons/godot_ai/handlers/audio_handler.gd @@ -0,0 +1,361 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles AudioStreamPlayer / 2D / 3D authoring — node creation, stream +## assignment, playback-property edits, and real editor preview playback. +## +## Stream assignment loads a Godot-imported AudioStream resource from +## res:// (the editor's import step converts .ogg / .wav / .mp3 into a +## streamable AudioStream subclass before we ever see it). +## +## play() / stop() call the live node method directly — no undo, no +## persistence; they match what the inspector's play button does. + + +const _VALID_TYPES := { + "1d": "AudioStreamPlayer", + "2d": "AudioStreamPlayer2D", + "3d": "AudioStreamPlayer3D", +} + +## Whitelist of playback properties settable via audio_player_set_playback. +## Each value is the expected Variant type of the param dict value. +const _PLAYBACK_KEYS := { + "volume_db": TYPE_FLOAT, + "pitch_scale": TYPE_FLOAT, + "autoplay": TYPE_BOOL, + "bus": TYPE_STRING, +} + + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +# ============================================================================ +# audio_player_create +# ============================================================================ + +func create_player(params: Dictionary) -> Dictionary: + var parent_path: String = params.get("parent_path", "") + var node_name: String = params.get("name", "AudioStreamPlayer") + var type_str: String = params.get("type", "1d") + + if not _VALID_TYPES.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid audio player type '%s'. Valid: %s" % [type_str, ", ".join(_VALID_TYPES.keys())] + ) + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + var node := _instantiate_player(type_str) + if node == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate audio player") + if not node_name.is_empty(): + node.name = node_name + + _undo_redo.create_action("MCP: Create %s '%s'" % [_VALID_TYPES[type_str], node.name]) + _undo_redo.add_do_method(parent, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + _undo_redo.add_do_reference(node) + _undo_redo.add_undo_method(parent, "remove_child", node) + _undo_redo.commit_action() + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "parent_path": McpScenePath.from_node(parent, scene_root), + "name": String(node.name), + "type": type_str, + "class": _VALID_TYPES[type_str], + "undoable": true, + } + } + + +# ============================================================================ +# audio_player_set_stream +# ============================================================================ + +func set_stream(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var stream_path: String = params.get("stream_path", "") + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + if stream_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: stream_path") + + var stream_path_err = McpPathValidator.loadable_error(stream_path, "stream_path") + if stream_path_err != null: + return stream_path_err + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: Node = resolved.player + + if not ResourceLoader.exists(stream_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "AudioStream not found: %s" % stream_path) + var loaded := ResourceLoader.load(stream_path) + if loaded == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to load AudioStream: %s" % stream_path) + if not (loaded is AudioStream): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Resource at %s is not an AudioStream (got %s)" % [stream_path, loaded.get_class()] + ) + + var old_stream: AudioStream = player.stream + + _undo_redo.create_action("MCP: Set audio stream on %s" % player.name) + _undo_redo.add_do_property(player, "stream", loaded) + _undo_redo.add_undo_property(player, "stream", old_stream) + _undo_redo.commit_action() + + return { + "data": { + "player_path": player_path, + "stream_path": stream_path, + "stream_class": loaded.get_class(), + "duration_seconds": float(loaded.get_length()), + "undoable": true, + } + } + + +# ============================================================================ +# audio_player_set_playback +# ============================================================================ + +func set_playback(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: Node = resolved.player + + var updates: Dictionary = {} + for key in _PLAYBACK_KEYS: + if params.has(key): + var expected_type: int = _PLAYBACK_KEYS[key] + var value = params.get(key) + var coerced = _coerce_playback_value(value, expected_type) + if coerced == null: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Invalid value for %s: expected %s, got %s" % [ + key, type_string(expected_type), type_string(typeof(value)) + ] + ) + updates[key] = coerced + + if updates.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "At least one of %s is required" % ", ".join(_PLAYBACK_KEYS.keys()) + ) + + var old_values: Dictionary = {} + for key in updates: + old_values[key] = player.get(key) + + _undo_redo.create_action("MCP: Update playback on %s" % player.name) + for key in updates: + _undo_redo.add_do_property(player, key, updates[key]) + _undo_redo.add_undo_property(player, key, old_values[key]) + _undo_redo.commit_action() + + return { + "data": { + "player_path": player_path, + "applied": updates.keys(), + "values": updates, + "undoable": true, + } + } + + +# ============================================================================ +# audio_play (runtime preview — not saved with scene) +# ============================================================================ + +func play(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + var from_position: float = float(params.get("from_position", 0.0)) + + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: Node = resolved.player + + if player.stream == null: + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "Player has no stream assigned — call audio_player_set_stream first" + ) + + player.play(from_position) + + return { + "data": { + "player_path": player_path, + "from_position": from_position, + "playing": bool(player.playing), + "undoable": false, + "reason": "Runtime playback state — not saved with scene", + } + } + + +# ============================================================================ +# audio_stop (runtime preview — not saved with scene) +# ============================================================================ + +func stop(params: Dictionary) -> Dictionary: + var player_path: String = params.get("player_path", "") + if player_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: player_path") + + var resolved := _resolve_player(player_path) + if resolved.has("error"): + return resolved + var player: Node = resolved.player + + player.stop() + + return { + "data": { + "player_path": player_path, + "playing": bool(player.playing), + "undoable": false, + "reason": "Runtime playback state — not saved with scene", + } + } + + +# ============================================================================ +# audio_list (read — scan project for AudioStream resources) +# ============================================================================ + +func list_streams(params: Dictionary) -> Dictionary: + var root: String = params.get("root", "res://") + var include_duration: bool = bool(params.get("include_duration", true)) + + var root_err = McpPathValidator.path_error(root, "root") + if root_err != null: + return root_err + + var efs := EditorInterface.get_resource_filesystem() + if efs == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "EditorFileSystem not available", false) + + var results: Array[Dictionary] = [] + var start_dir := efs.get_filesystem_path(root) + if start_dir == null: + start_dir = efs.get_filesystem() + _scan_audio(start_dir, root, include_duration, results) + return { + "data": { + "root": root, + "streams": results, + "count": results.size(), + } + } + + +func _scan_audio(dir: EditorFileSystemDirectory, root: String, include_duration: bool, out: Array[Dictionary]) -> void: + if dir == null: + return + for i in dir.get_file_count(): + var file_path := dir.get_file_path(i) + if not file_path.begins_with(root): + continue + var file_type := dir.get_file_type(i) + var is_audio := file_type == "AudioStream" or ClassDB.is_parent_class(file_type, "AudioStream") + if not is_audio: + continue + var entry: Dictionary = { + "path": file_path, + "class": file_type, + } + if include_duration: + var res := ResourceLoader.load(file_path) + if res is AudioStream: + entry["duration_seconds"] = float((res as AudioStream).get_length()) + else: + entry["duration_seconds"] = 0.0 + out.append(entry) + for i in dir.get_subdir_count(): + _scan_audio(dir.get_subdir(i), root, include_duration, out) + + +# ============================================================================ +# Helpers +# ============================================================================ + +static func _instantiate_player(type_str: String) -> Node: + match type_str: + "1d": + return AudioStreamPlayer.new() + "2d": + return AudioStreamPlayer2D.new() + "3d": + return AudioStreamPlayer3D.new() + return null + + +func _resolve_player(player_path: String) -> Dictionary: + var resolved := McpNodeValidator.resolve_or_error(player_path, "player_path") + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var is_player := node is AudioStreamPlayer \ + or node is AudioStreamPlayer2D \ + or node is AudioStreamPlayer3D + if not is_player: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node at %s is not an AudioStreamPlayer/2D/3D (got %s)" % [player_path, node.get_class()] + ) + return {"player": node} + + +## Coerce a playback param value to the expected type. int→float is allowed +## so JSON integers pass through; everything else requires the exact type. +## Returns the coerced value, or null on type mismatch. +static func _coerce_playback_value(value: Variant, expected_type: int) -> Variant: + match expected_type: + TYPE_FLOAT: + if value is float or value is int: + return float(value) + TYPE_BOOL: + if value is bool: + return value + TYPE_STRING: + if value is String: + return value + return null diff --git a/addons/godot_ai/handlers/audio_handler.gd.uid b/addons/godot_ai/handlers/audio_handler.gd.uid new file mode 100644 index 0000000..2510ee7 --- /dev/null +++ b/addons/godot_ai/handlers/audio_handler.gd.uid @@ -0,0 +1 @@ +uid://cjtvod52xxocs diff --git a/addons/godot_ai/handlers/autoload_handler.gd b/addons/godot_ai/handlers/autoload_handler.gd new file mode 100644 index 0000000..22e7764 --- /dev/null +++ b/addons/godot_ai/handlers/autoload_handler.gd @@ -0,0 +1,91 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles autoload listing, adding, and removing via ProjectSettings. + + +func list_autoloads(_params: Dictionary) -> Dictionary: + var autoloads: Array[Dictionary] = [] + for prop in ProjectSettings.get_property_list(): + var key: String = prop.get("name", "") + if not key.begins_with("autoload/"): + continue + var name := key.substr("autoload/".length()) + var raw_value: String = ProjectSettings.get_setting(key, "") + var is_singleton := raw_value.begins_with("*") + var path := raw_value.substr(1) if is_singleton else raw_value + autoloads.append({ + "name": name, + "path": path, + "singleton": is_singleton, + }) + return {"data": {"autoloads": autoloads, "count": autoloads.size()}} + + +func add_autoload(params: Dictionary) -> Dictionary: + var name: String = params.get("name", "") + var path: String = params.get("path", "") + var singleton: bool = params.get("singleton", true) + + if name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: name") + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + var path_err = McpPathValidator.path_error(path, "path") + if path_err != null: + return path_err + if not FileAccess.file_exists(path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "File not found: %s" % path) + + var key := "autoload/%s" % name + if ProjectSettings.has_setting(key): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Autoload '%s' already exists" % name) + + var value := ("*" if singleton else "") + path + ProjectSettings.set_setting(key, value) + ProjectSettings.set_initial_value(key, "") + ProjectSettings.set_as_basic(key, true) + var err := ProjectSettings.save() + if err != OK: + ProjectSettings.clear(key) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Failed to save project settings while adding autoload '%s': %s (error %d)" % [name, error_string(err), err]) + + return { + "data": { + "name": name, + "path": path, + "singleton": singleton, + "undoable": false, + "reason": "Autoload changes are saved to project.godot", + } + } + + +func remove_autoload(params: Dictionary) -> Dictionary: + var name: String = params.get("name", "") + if name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: name") + + var key := "autoload/%s" % name + if not ProjectSettings.has_setting(key): + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, "Autoload '%s' not found" % name) + + var old_value: String = ProjectSettings.get_setting(key, "") + ProjectSettings.clear(key) + var err := ProjectSettings.save() + if err != OK: + ProjectSettings.set_setting(key, old_value) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Failed to save project settings while removing autoload '%s': %s (error %d)" % [name, error_string(err), err]) + + return { + "data": { + "name": name, + "removed": true, + "undoable": false, + "reason": "Autoload changes are saved to project.godot", + } + } diff --git a/addons/godot_ai/handlers/autoload_handler.gd.uid b/addons/godot_ai/handlers/autoload_handler.gd.uid new file mode 100644 index 0000000..921ed4e --- /dev/null +++ b/addons/godot_ai/handlers/autoload_handler.gd.uid @@ -0,0 +1 @@ +uid://bb0inov044jn6 diff --git a/addons/godot_ai/handlers/batch_handler.gd b/addons/godot_ai/handlers/batch_handler.gd new file mode 100644 index 0000000..c6c1474 --- /dev/null +++ b/addons/godot_ai/handlers/batch_handler.gd @@ -0,0 +1,190 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Executes a list of sub-commands through the dispatcher with stop-on-first-error +## semantics. When undo=true (default), any successful sub-commands are rolled +## back via the scene's UndoRedo history if a later sub-command fails. + +## Commands that cannot run as batch sub-commands, each with the reason a batch +## can't host it. +## - batch_execute: would recurse. +## - run_tests: a batch executes synchronously inside one dispatcher tick with +## NO transport servicing, so a full suite starves the WebSocket heartbeat +## (the exact disconnect the serviced test_run path exists to prevent) and +## the Python batch handler only allows 30s anyway — call the test_run tool +## directly. +## - game_command: it is deferred — its reply flows out-of-band correlated by a +## _request_id that dispatch_direct deliberately strips (see +## McpDispatcher.dispatch_direct), so a game op nested in a batch would have +## no completion channel and hang or lose its reply. input_sequence made this +## concrete (#814); the whole game_command surface shares the deferred path. +const FORBIDDEN_SUBCOMMANDS := { + "batch_execute": "batch_execute cannot be nested inside another batch", + "run_tests": + "run_tests is not allowed as a sub-command — a batch runs synchronously " + + "with no transport servicing; call the test_run tool directly", + "game_command": + "game_command ops are deferred (their reply arrives out-of-band) and " + + "have no completion channel inside a batch — run them as their own tool call", +} + +## The whole batch executes synchronously inside one dispatcher tick, +## outside the 4ms frame budget — an unbounded array freezes the editor +## for the batch's full duration. 500 is far above any legitimate scene +## edit while keeping worst-case stalls in check. +const MAX_BATCH_COMMANDS := 500 + +var _dispatcher: McpDispatcher +var _undo_redo: EditorUndoRedoManager + + +func _init(dispatcher: McpDispatcher, undo_redo: EditorUndoRedoManager) -> void: + _dispatcher = dispatcher + _undo_redo = undo_redo + + +func batch_execute(params: Dictionary) -> Dictionary: + var commands = params.get("commands", null) + if typeof(commands) != TYPE_ARRAY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "commands must be a list") + if commands.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "commands must not be empty") + if commands.size() > MAX_BATCH_COMMANDS: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "commands exceeds the %d-command batch cap (got %d) — split into multiple batches" % [MAX_BATCH_COMMANDS, commands.size()] + ) + + var undo: bool = params.get("undo", true) + + for idx in range(commands.size()): + var item = commands[idx] + if typeof(item) != TYPE_DICTIONARY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "commands[%d] must be a dict" % idx) + var cmd_name: String = item.get("command", "") + if cmd_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "commands[%d] missing 'command' field" % idx) + if FORBIDDEN_SUBCOMMANDS.has(cmd_name): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "commands[%d]: %s" % [idx, FORBIDDEN_SUBCOMMANDS[cmd_name]]) + if not _dispatcher.has_command(cmd_name): + return _unknown_command_error(idx, cmd_name) + ## Pre-validate params type: the execution loop's typed Dictionary + ## local would hard-error on a non-dict mid-batch, aborting AFTER + ## earlier mutations committed. Catching it here keeps the + ## all-or-nothing contract for malformed input. + if typeof(item.get("params", {})) != TYPE_DICTIONARY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "commands[%d].params must be a dict" % idx) + if cmd_name.begins_with("custom_tool:"): + var _custom_tools := McpToolRegistry.get_instance() + if _custom_tools: + var spec := _custom_tools.get_spec(cmd_name.trim_prefix("custom_tool:")) + ## A deferred tool's real reply arrives via ctx.send_deferred + ## AFTER the batch has already returned its synchronous + ## results — the sub-command would report an opaque + ## "_deferred" placeholder and the actual payload would be + ## orphaned. Reject up-front, matching the FORBIDDEN_SUBCOMMANDS + ## contract for run_tests. + if spec != null and spec.deferred: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "commands[%d] custom_tool:%s is deferred — its reply outlives the batch response; call it directly instead" % [idx, cmd_name.trim_prefix("custom_tool:")] + ) + if undo and spec != null and not spec.undoable: + return ErrorCodes.make( + ErrorCodes.CUSTOM_TOOL_NOT_UNDOABLE, + "commands[%d] custom_tool:%s is not undoable" % [idx, cmd_name.trim_prefix("custom_tool:")] + ) + + var results: Array = [] + var succeeded := 0 + var stopped_at = null + var all_undoable := true + # Captured after the first successful commit — get_history_undo_redo() + # errors if called before any action exists in the history_map. + var histories: Array = [] + + for idx in range(commands.size()): + var item: Dictionary = commands[idx] + var cmd_name: String = item["command"] + var sub_params: Dictionary = item.get("params", {}) + + var raw_result: Dictionary = _dispatcher.dispatch_direct(cmd_name, sub_params) + var status: String = raw_result.get("status", "ok") + + var result_entry: Dictionary = {"command": cmd_name, "status": status} + if status == "error": + result_entry["error"] = raw_result.get("error", {}) + results.append(result_entry) + stopped_at = idx + break + else: + var data: Dictionary = raw_result.get("data", raw_result) + result_entry["data"] = data + if typeof(data) == TYPE_DICTIONARY and data.get("undoable", false) != true: + all_undoable = false + results.append(result_entry) + succeeded += 1 + _capture_histories(histories) + + var rolled_back := false + if stopped_at != null and undo and succeeded > 0: + rolled_back = _rollback(succeeded, histories) + + var response_data: Dictionary = { + "succeeded": succeeded, + "stopped_at": stopped_at, + "results": results, + "undo": undo, + "rolled_back": rolled_back, + "undoable": stopped_at == null and all_undoable and not rolled_back, + } + if stopped_at != null: + response_data["error"] = results[-1]["error"] + return {"data": response_data} + + +## Capture the scene's UndoRedo reference for batch rollback. Safe to call +## multiple times; appends only the new reference. MCP write handlers all pin +## their actions to the scene history, so the scene UndoRedo is the only one +## rollback needs. Must be called only after at least one action has been +## committed to the scene history. +func _capture_histories(histories: Array) -> void: + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root == null: + return + var scene_id := _undo_redo.get_object_history_id(scene_root) + var scene_ur := _undo_redo.get_history_undo_redo(scene_id) + if scene_ur != null and not scene_ur in histories: + histories.append(scene_ur) + + +## Build the unknown-command error for a sub-command. Clarifies that +## batch_execute expects plugin command names (not MCP tool names) and +## surfaces fuzzy suggestions in both the message and structured data. +func _unknown_command_error(idx: int, cmd_name: String) -> Dictionary: + var suggestions := _dispatcher.suggest_similar(cmd_name) + var msg := "commands[%d]: unknown plugin command '%s'. batch_execute expects plugin command names (e.g. 'create_node'), not MCP tool names (e.g. 'node_create')." % [idx, cmd_name] + if not suggestions.is_empty(): + msg += " Did you mean: %s?" % ", ".join(suggestions) + var err := ErrorCodes.make(ErrorCodes.UNKNOWN_COMMAND, msg) + err["error"]["data"] = {"suggestions": suggestions} + return err + + +## Undo `count` actions by calling undo() on captured histories in LIFO order. +## Returns true iff all undo calls succeeded. +func _rollback(count: int, histories: Array) -> bool: + if histories.is_empty(): + return false + for _i in range(count): + var undone := false + for ur in histories: + if ur.undo(): + undone = true + break + if not undone: + return false + return true diff --git a/addons/godot_ai/handlers/batch_handler.gd.uid b/addons/godot_ai/handlers/batch_handler.gd.uid new file mode 100644 index 0000000..630a596 --- /dev/null +++ b/addons/godot_ai/handlers/batch_handler.gd.uid @@ -0,0 +1 @@ +uid://dt7um75oofdrh diff --git a/addons/godot_ai/handlers/camera_handler.gd b/addons/godot_ai/handlers/camera_handler.gd new file mode 100644 index 0000000..fb986e5 --- /dev/null +++ b/addons/godot_ai/handlers/camera_handler.gd @@ -0,0 +1,1145 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles Camera2D / Camera3D authoring — create, configure, bounds, damping, +## node-parent-based follow, presets. +## +## All writes are bundled into a single EditorUndoRedoManager action. +## Setting current=true auto-unmarks previously-current cameras of the same +## class in the same action so one Ctrl-Z reverts the switch. + +const CameraValues := preload("res://addons/godot_ai/handlers/camera_values.gd") +const CameraPresets := preload("res://addons/godot_ai/handlers/camera_presets.gd") + +const _VALID_TYPES := { + "2d": "Camera2D", + "3d": "Camera3D", +} + +const _KEYS_2D := [ + "zoom", + "offset", + "anchor_mode", + "ignore_rotation", + "enabled", + "current", + "process_callback", + "position_smoothing_enabled", + "position_smoothing_speed", + "rotation_smoothing_enabled", + "rotation_smoothing_speed", + "drag_horizontal_enabled", + "drag_vertical_enabled", + "drag_horizontal_offset", + "drag_vertical_offset", + "drag_left_margin", + "drag_top_margin", + "drag_right_margin", + "drag_bottom_margin", + "limit_left", + "limit_right", + "limit_top", + "limit_bottom", + "limit_smoothed", +] + +const _KEYS_3D := [ + "fov", + "near", + "far", + "size", + "projection", + "keep_aspect", + "cull_mask", + "doppler_tracking", + "h_offset", + "v_offset", + "current", +] + +# Transform-shaped keys live on Node2D / Node3D, not in the camera-specific +# schema — rejecting them without a hint sends agents searching for the wrong +# tool. +const _NODE_TRANSFORM_KEYS := [ + "position", "rotation", "scale", "transform", + "global_position", "global_rotation", "global_scale", "global_transform", +] + +const _DAMPING_MARGIN_KEYS := ["left", "top", "right", "bottom"] +const _CURRENT_SETTLE_ATTEMPTS := 8 +const _CURRENT_SETTLE_DELAY_MSEC := 10 + + +var _undo_redo: EditorUndoRedoManager + +# Per-scene logical-current bookkeeping. Keys are scene-root InstanceIDs; +# values are { "2d": NodePath-as-String, "3d": NodePath-as-String } with +# missing keys meaning "no logical current for that class." +# +# Stored on the handler instance (NOT as Node metadata on the scene root) +# because set_meta() persists into the .tscn on save, contaminating user +# scene files with MCP-internal sidecar state that lingers across reloads +# and travels in commits. +var _logical_current: Dictionary = {} + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +# Camera2D doesn't expose `current` as a settable property in Godot 4 — +# only is_current() / make_current() / clear_current(). Camera3D exposes +# both, but using methods uniformly avoids per-class branching. +static func _is_current(cam: Node) -> bool: + if cam == null: + return false + return bool(cam.is_current()) + + +static func _viewport_current_camera(scene_root: Node) -> Node: + if scene_root == null: + return null + var viewport := scene_root.get_viewport() + if viewport == null: + return null + var current_2d := viewport.get_camera_2d() + if current_2d != null and scene_root.is_ancestor_of(current_2d): + return current_2d + var current_3d := viewport.get_camera_3d() + if current_3d != null and scene_root.is_ancestor_of(current_3d): + return current_3d + return null + + +static func _is_effective_current(cam: Node) -> bool: + if _is_current(cam): + return true + if cam is Camera2D: + var viewport_2d := cam.get_viewport() + return viewport_2d != null and viewport_2d.get_camera_2d() == cam + if cam is Camera3D: + var viewport_3d := cam.get_viewport() + return viewport_3d != null and viewport_3d.get_camera_3d() == cam + return false + + +# Logical-current bookkeeping. Updated from inside _apply_make_current / +# _apply_clear_current so DO and UNDO callables stamp the same logical +# slot they touch in the viewport. Reads consult the logical slot first +# and treat it as authoritative when set — the viewport read is the +# fallback for "MCP never touched this scene's cameras." + +func _set_logical_current(cam: Node) -> void: + if cam == null or not is_instance_valid(cam) or not cam.is_inside_tree(): + return + var type_str := _camera_type_str(cam) + if type_str.is_empty(): + return + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root == null or not scene_root.is_ancestor_of(cam): + return + var slot: Dictionary = _logical_current.get(scene_root.get_instance_id(), {}) + slot[type_str] = McpScenePath.from_node(cam, scene_root) + _logical_current[scene_root.get_instance_id()] = slot + + +func _clear_logical_current(cam: Node) -> void: + if cam == null: + return + var type_str := _camera_type_str(cam) + if type_str.is_empty(): + return + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root == null: + return + var key := scene_root.get_instance_id() + if not _logical_current.has(key): + return + var slot: Dictionary = _logical_current[key] + if not slot.has(type_str): + return + # Only clear if the logical slot still points at this camera; otherwise + # a later make_current already took the slot and we'd stomp it. + var current_path := "" + if is_instance_valid(cam) and cam.is_inside_tree() and scene_root.is_ancestor_of(cam): + current_path = McpScenePath.from_node(cam, scene_root) + if String(slot[type_str]) == current_path: + slot.erase(type_str) + if slot.is_empty(): + _logical_current.erase(key) + else: + _logical_current[key] = slot + + +func _logical_current_camera(scene_root: Node, type_str: String = "") -> Node: + if scene_root == null: + return null + var key := scene_root.get_instance_id() + if not _logical_current.has(key): + return null + var slot: Dictionary = _logical_current[key] + var types: Array[String] = [] + if type_str == "2d" or type_str == "3d": + types = [type_str] + else: + types = ["2d", "3d"] + for t in types: + if not slot.has(t): + continue + var path := String(slot[t]) + if path.is_empty(): + slot.erase(t) + continue + var node := McpScenePath.resolve(path, scene_root) + if node == null or not _is_camera(node) or _camera_type_str(node) != t: + slot.erase(t) + continue + return node + if slot.is_empty(): + _logical_current.erase(key) + else: + _logical_current[key] = slot + return null + + +# Public introspection for tests that need to distinguish "handler has a +# logical marker" from "handler is falling back to engine state". `get_camera` +# / `list_cameras` both use `_resolve_current` which falls through to +# `_is_effective_current` when no marker is set — that's correct for callers +# but masks the marker presence from anyone trying to gate on +# "did the handler actually record this state?". Returns the logical-current +# Camera2D / Camera3D for the given type ("2d" / "3d" / "" for either), or +# null when no marker is set. See #316 PR #372 review feedback. +func peek_logical_current(scene_root: Node, type_str: String = "") -> Node: + return _logical_current_camera(scene_root, type_str) + + +# Authoritative answer for "is `cam` the current camera of its class?" +# +# When a logical marker exists for the camera's class, it is the single +# source of truth — only the marker's referenced camera reports current, +# every other camera of that class reports false even if the viewport +# slot still points at one of them (the headless-CI lag in #140 / #278 / +# #301). Without a logical marker, fall through to the viewport read so +# scenes MCP never touched still answer correctly. +func _resolve_current(scene_root: Node, cam: Node) -> bool: + if scene_root == null or cam == null: + return false + var logical := _logical_current_camera(scene_root, _camera_type_str(cam)) + if logical != null: + return logical == cam + return _is_effective_current(cam) + + +# list_cameras pre-fetches the per-class logical pointers once; this +# variant takes those pointers to avoid an O(n²) walk over the meta +# bookkeeping for each camera in the scene. +func _resolve_current_with_logicals(cam: Node, logical_2d: Node, logical_3d: Node) -> bool: + if cam == null: + return false + if cam is Camera2D: + if logical_2d != null: + return logical_2d == cam + elif cam is Camera3D: + if logical_3d != null: + return logical_3d == cam + return _is_effective_current(cam) + + +# Register a current=true switch on `node` in the open undo action, +# unmarking previously-current siblings of the same class so a single +# Ctrl-Z reverts the whole switch. +# +# Both DO and UNDO route through `_apply_make_current` / `_apply_clear_current` +# on the handler itself rather than calling Camera.make_current() directly. +# The helpers do the make_current (or clear_current) call plus bounded sync +# settling when the viewport hasn't yet reflected the change — headless CI +# occasionally reports `is_current() == false` immediately after a committed +# make_current (observed CI run 24682342469) and symmetrically still reports +# the displaced camera as current immediately after an undo (observed CI runs +# 24682342469, 24692250322, 24696571517, 25079965242 — tracked in #140). +# Later #278 runs broadened the same current-camera timing flake across more +# platforms and assertions, so the settle budget is deliberately above one +# fast local frame. +# +# Because those callables bind to `self` (a RefCounted handler, not a scene +# node), every action that calls this helper must pin its history via +# `create_action(name, MERGE_DISABLE, scene_root)` — otherwise the +# handler-bound ops land in GLOBAL_HISTORY while the scene-node ops land in +# the scene's history, and a single editor_undo reverts only half the action. +# +# Both DO and UNDO use a single make_current() call — never a +# clear_current() + make_current() pair. make_current() takes over the +# viewport slot atomically (Godot enforces one current camera per class +# per viewport), so the displaced camera naturally returns +# is_current() == false without an explicit clear. The two-step approach +# leaves the viewport temporarily with no current camera between the +# clear and the make, which races with editor cleanup on macOS headless +# (observed flaking CI runs 24674252085, 24675424785). +func _add_make_current_to_action(node: Node, type_str: String, scene_root: Node) -> void: + var prev_current: Node = null + for cam in _list_cameras_in_scene(scene_root, type_str): + if cam == node: + continue + if _resolve_current(scene_root, cam): + prev_current = cam + break + _undo_redo.add_do_method(self, "_apply_make_current", node) + if prev_current != null: + _undo_redo.add_undo_method(self, "_apply_make_current", prev_current) + else: + _undo_redo.add_undo_method(self, "_apply_clear_current", node) + + +# Apply make_current on `cam` with bounded synchronous settling. Registered as the +# do/undo callable by `_add_make_current_to_action`. See that function's +# comment for why the undo path needs the retry inside the action itself. +# Safe against a freed camera node — short-circuits if the node is gone +# or not in the tree. +func _apply_make_current(cam: Node) -> void: + if cam == null or not is_instance_valid(cam) or not cam.is_inside_tree(): + return + _set_logical_current(cam) + var scene_root := EditorInterface.get_edited_scene_root() + var type_str := _camera_type_str(cam) + for attempt in range(_CURRENT_SETTLE_ATTEMPTS): + cam.make_current() + _force_camera_refresh(cam) + # Godot's make_current is supposed to atomically displace siblings, + # but on macOS headless the displaced camera occasionally still + # answers is_current() == true after this returns (#140 / #278 / #301). + # Sweep same-class siblings and clear any that lag. + _force_clear_other_currents(cam, type_str, scene_root) + if not _is_current_settled(cam): + _displace_stale_camera_2d(cam) + _force_clear_other_currents(cam, type_str, scene_root) + var waited_this_attempt := false + if _is_current_settled(cam): + if not (cam is Camera2D): + return + OS.delay_msec(_CURRENT_SETTLE_DELAY_MSEC) + waited_this_attempt = true + _force_camera_refresh(cam) + _force_clear_other_currents(cam, type_str, scene_root) + if _is_current_settled(cam): + return + if attempt < _CURRENT_SETTLE_ATTEMPTS - 1 and not waited_this_attempt: + OS.delay_msec(_CURRENT_SETTLE_DELAY_MSEC) + + +# Walk same-class siblings and force-clear any that still report is_current(). +# Best-effort: clear_current errors when called on a non-current camera, so +# guard. Camera2D's clear_current path also flushes the viewport slot, which +# is the one we actually care about settling for #301. +func _force_clear_other_currents(target: Node, type_str: String, scene_root: Node) -> void: + if scene_root == null or type_str.is_empty(): + return + for sibling in _list_cameras_in_scene(scene_root, type_str): + if sibling == target: + continue + if not is_instance_valid(sibling) or not sibling.is_inside_tree(): + continue + if not _is_current(sibling): + # Even if is_current() reports false, the viewport slot can + # still point at this sibling on macOS — re-make target to + # take it back. Cheap (idempotent) when the slot is fine. + if sibling is Camera2D: + var vp_other: Viewport = (sibling as Camera2D).get_viewport() + if vp_other != null and vp_other.get_camera_2d() == sibling: + target.make_current() + _force_camera_refresh(target) + continue + sibling.clear_current() + if sibling is Camera2D: + (sibling as Camera2D).force_update_scroll() + + +# Call after commit_action() whenever the action registered a make_current DO. +# The undo path cannot use a post-undo hook, so it relies on `_apply_make_current` +# directly; create/configure/apply_preset get this extra post-commit verifier. +func _verify_current_after_commit(node: Node) -> void: + _apply_make_current(node) + + +func _force_camera_refresh(cam: Node) -> void: + if cam is Camera2D: + (cam as Camera2D).force_update_scroll() + + +func _is_current_settled(cam: Node) -> bool: + if not _is_current(cam): + return false + if cam is Camera2D: + var viewport := cam.get_viewport() + if viewport != null and viewport.get_camera_2d() != cam: + return false + return true + + +func _displace_stale_camera_2d(target: Node) -> void: + if not (target is Camera2D): + return + var viewport := target.get_viewport() + if viewport == null: + return + var stale := viewport.get_camera_2d() + if stale == null or stale == target or not is_instance_valid(stale): + _nudge_camera_2d_current(target) + return + var was_enabled := stale.enabled + if was_enabled: + stale.enabled = false + target.make_current() + _force_camera_refresh(target) + if was_enabled: + stale.enabled = true + target.make_current() + _force_camera_refresh(target) + + +func _nudge_camera_2d_current(target: Node) -> void: + if not (target is Camera2D): + return + var cam := target as Camera2D + if not cam.enabled: + return + cam.enabled = false + _force_camera_refresh(cam) + cam.enabled = true + cam.make_current() + _force_camera_refresh(cam) + + +# Symmetric counterpart to `_apply_make_current` for the "no previous +# current camera" branch (create_camera with make_current=true and no +# sibling was current). clear_current errors in Godot if called on a +# non-current camera, so guard on is_current first. +func _apply_clear_current(cam: Node) -> void: + if cam == null or not is_instance_valid(cam) or not cam.is_inside_tree(): + return + _clear_logical_current(cam) + for attempt in range(_CURRENT_SETTLE_ATTEMPTS): + if _is_clear_settled(cam): + return + if _is_current(cam): + cam.clear_current() + _force_camera_refresh(cam) + # Camera2D-only: is_current() may answer false while the viewport + # slot still points at cam. Toggle enabled to force the viewport + # to release, then restore. + if cam is Camera2D: + var vp := cam.get_viewport() + if vp != null and vp.get_camera_2d() == cam: + var was_enabled := (cam as Camera2D).enabled + if was_enabled: + (cam as Camera2D).enabled = false + _force_camera_refresh(cam) + if was_enabled: + (cam as Camera2D).enabled = true + if _is_clear_settled(cam): + return + if attempt < _CURRENT_SETTLE_ATTEMPTS - 1: + OS.delay_msec(_CURRENT_SETTLE_DELAY_MSEC) + + +func _is_clear_settled(cam: Node) -> bool: + if cam == null: + return true + if _is_current(cam): + return false + if cam is Camera2D: + var vp := cam.get_viewport() + if vp != null and vp.get_camera_2d() == cam: + return false + return true + + +# ============================================================================ +# camera_create +# ============================================================================ + +func create_camera(params: Dictionary) -> Dictionary: + var parent_path: String = params.get("parent_path", "") + var node_name: String = params.get("name", "Camera") + var type_str: String = params.get("type", "2d") + var make_current: bool = bool(params.get("make_current", false)) + + if not _VALID_TYPES.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid camera type '%s'. Valid: %s" % [type_str, ", ".join(_VALID_TYPES.keys())] + ) + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + var node := _instantiate_camera(type_str) + if node == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate camera") + if not node_name.is_empty(): + node.name = node_name + + _undo_redo.create_action( + "MCP: Create %s '%s'" % [_VALID_TYPES[type_str], node.name], + UndoRedo.MERGE_DISABLE, scene_root + ) + _undo_redo.add_do_method(parent, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + _undo_redo.add_do_reference(node) + if make_current: + # Must land AFTER add_child: making current before the node is in the + # tree is a silent no-op on the viewport. + _add_make_current_to_action(node, type_str, scene_root) + _undo_redo.add_undo_method(parent, "remove_child", node) + _undo_redo.commit_action() + if make_current: + _verify_current_after_commit(node) + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "parent_path": McpScenePath.from_node(parent, scene_root), + "name": String(node.name), + "type": type_str, + "class": _VALID_TYPES[type_str], + "current": bool(make_current), + "undoable": true, + } + } + + +# ============================================================================ +# camera_configure +# ============================================================================ + +func configure(params: Dictionary) -> Dictionary: + var resolved := _resolve_camera(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var type_str: String = resolved.type + var scene_root: Node = resolved.scene_root + + var properties: Dictionary = params.get("properties", {}) + if properties.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "properties dict is empty") + + var valid_keys: Array = _KEYS_2D if type_str == "2d" else _KEYS_3D + var prop_types := _property_type_map(node) + var coerced: Dictionary = {} + var old_values: Dictionary = {} + # `current` is special-cased via methods (Camera2D doesn't expose it as a property). + var current_request: Variant = null + + for property in properties: + var prop_name: String = String(property) + if not (prop_name in valid_keys): + var msg := "Property '%s' not valid for %s. Valid: %s" % [ + prop_name, _VALID_TYPES[type_str], ", ".join(valid_keys) + ] + if prop_name in _NODE_TRANSFORM_KEYS: + msg += ( + ". Transforms live on the Node, not on the camera config — " + + "use node_set_property(path=%s, property=\"%s\", value=...)" % [node_path, prop_name] + ) + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, msg) + if prop_name == "current": + current_request = bool(properties[prop_name]) + continue + var prop_type: int = prop_types.get(prop_name, TYPE_NIL) + if prop_type == TYPE_NIL: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Property '%s' not present on %s" % [prop_name, node.get_class()] + ) + var coerce_result := CameraValues.coerce(prop_name, properties[prop_name], prop_type) + if not coerce_result.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerce_result.error)) + coerced[prop_name] = coerce_result.value + old_values[prop_name] = node.get(prop_name) + + _undo_redo.create_action( + "MCP: Configure camera %s" % node.name, + UndoRedo.MERGE_DISABLE, scene_root + ) + for prop_name in coerced: + _undo_redo.add_do_property(node, prop_name, coerced[prop_name]) + _undo_redo.add_undo_property(node, prop_name, old_values[prop_name]) + var verify_current_after := false + if current_request != null: + var want_on: bool = bool(current_request) + var was_on: bool = _resolve_current(scene_root, node) + if want_on and not was_on: + _add_make_current_to_action(node, type_str, scene_root) + verify_current_after = true + elif not want_on and was_on: + _undo_redo.add_do_method(self, "_apply_clear_current", node) + _undo_redo.add_undo_method(self, "_apply_make_current", node) + _undo_redo.commit_action() + if verify_current_after: + _verify_current_after_commit(node) + + var applied: Array[String] = [] + var serialized: Dictionary = {} + for prop_name in coerced: + applied.append(prop_name) + serialized[prop_name] = CameraValues.serialize(coerced[prop_name]) + if current_request != null: + applied.append("current") + serialized["current"] = bool(current_request) + + return { + "data": { + "path": node_path, + "type": type_str, + "class": node.get_class(), + "applied": applied, + "values": serialized, + "undoable": true, + } + } + + +# ============================================================================ +# camera_set_limits_2d +# ============================================================================ + +func set_limits_2d(params: Dictionary) -> Dictionary: + var resolved := _resolve_camera(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var type_str: String = resolved.type + + if type_str != "2d": + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "camera_set_limits_2d requires a Camera2D (got %s)" % node.get_class() + ) + + var applied: Dictionary = {} + var old_values: Dictionary = {} + var edges := { + "left": "limit_left", + "right": "limit_right", + "top": "limit_top", + "bottom": "limit_bottom", + } + for edge in edges: + var v = params.get(edge) + if v != null: + var prop_name: String = edges[edge] + applied[prop_name] = int(v) + old_values[prop_name] = node.get(prop_name) + + var smoothed = params.get("smoothed") + if smoothed != null: + applied["limit_smoothed"] = bool(smoothed) + old_values["limit_smoothed"] = node.get("limit_smoothed") + + if applied.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "No limits specified; provide at least one of left, right, top, bottom, smoothed" + ) + + _undo_redo.create_action("MCP: Set camera limits on %s" % node.name) + for prop_name in applied: + _undo_redo.add_do_property(node, prop_name, applied[prop_name]) + _undo_redo.add_undo_property(node, prop_name, old_values[prop_name]) + _undo_redo.commit_action() + + var values: Dictionary = {} + for prop_name in applied: + values[prop_name] = applied[prop_name] + + return { + "data": { + "path": node_path, + "applied": applied.keys(), + "values": values, + "undoable": true, + } + } + + +# ============================================================================ +# camera_set_damping_2d +# ============================================================================ + +func set_damping_2d(params: Dictionary) -> Dictionary: + var resolved := _resolve_camera(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var type_str: String = resolved.type + + if type_str != "2d": + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "camera_set_damping_2d requires a Camera2D (got %s)" % node.get_class() + ) + + var applied: Dictionary = {} + var old_values: Dictionary = {} + + # position_speed: set position_smoothing_speed AND toggle position_smoothing_enabled. + var pos_v = params.get("position_speed") + if pos_v != null: + var pos_speed := float(pos_v) + var pos_enable := pos_speed > 0.0 + applied["position_smoothing_enabled"] = pos_enable + old_values["position_smoothing_enabled"] = node.get("position_smoothing_enabled") + if pos_enable: + applied["position_smoothing_speed"] = pos_speed + old_values["position_smoothing_speed"] = node.get("position_smoothing_speed") + + # rotation_speed: same pattern for rotation_smoothing_*. + var rot_v = params.get("rotation_speed") + if rot_v != null: + var rot_speed := float(rot_v) + var rot_enable := rot_speed > 0.0 + applied["rotation_smoothing_enabled"] = rot_enable + old_values["rotation_smoothing_enabled"] = node.get("rotation_smoothing_enabled") + if rot_enable: + applied["rotation_smoothing_speed"] = rot_speed + old_values["rotation_smoothing_speed"] = node.get("rotation_smoothing_speed") + + for flag in ["drag_horizontal_enabled", "drag_vertical_enabled"]: + var flag_v = params.get(flag) + if flag_v != null: + applied[flag] = bool(flag_v) + old_values[flag] = node.get(flag) + + # drag_margins: dict {left, top, right, bottom} floats in [0,1]; null/missing keys untouched. + var margins_v = params.get("drag_margins") + if margins_v != null: + if not (margins_v is Dictionary): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "drag_margins must be a dict with optional keys left/top/right/bottom" + ) + var margins: Dictionary = margins_v + for edge in _DAMPING_MARGIN_KEYS: + var margin_v = margins.get(edge) + if margin_v == null: + continue + var v := float(margin_v) + if v < 0.0 or v > 1.0: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "drag_margins.%s must be in [0, 1] (got %s)" % [edge, v] + ) + var prop_name: String = "drag_%s_margin" % edge + applied[prop_name] = v + old_values[prop_name] = node.get(prop_name) + + if applied.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "No damping params specified; provide at least one of position_speed, rotation_speed, drag_margins, drag_horizontal_enabled, drag_vertical_enabled" + ) + + _undo_redo.create_action("MCP: Set camera damping on %s" % node.name) + for prop_name in applied: + _undo_redo.add_do_property(node, prop_name, applied[prop_name]) + _undo_redo.add_undo_property(node, prop_name, old_values[prop_name]) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "applied": applied.keys(), + "values": applied, + "undoable": true, + } + } + + +# ============================================================================ +# camera_follow_2d +# ============================================================================ + +func follow_2d(params: Dictionary) -> Dictionary: + var resolved := _resolve_camera(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var type_str: String = resolved.type + var scene_root: Node = resolved.scene_root + + if type_str != "2d": + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "camera_follow_2d requires a Camera2D (got %s)" % node.get_class() + ) + + var target_path: String = params.get("target_path", "") + if target_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: target_path") + var target := McpScenePath.resolve(target_path, scene_root) + if target == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, + "target_path: %s" % McpScenePath.format_node_error(target_path, scene_root)) + if not (target is Node2D) and target != scene_root: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Follow target must be a Node2D (got %s)" % target.get_class() + ) + if target == node: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Camera cannot follow itself") + if target.is_ancestor_of(node) and node.get_parent() != target: + # A non-parent ancestor — still valid to reparent under (direct parent). + pass + if node.is_ancestor_of(target): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Cannot follow a descendant of the camera" + ) + + var smoothing_speed := float(params.get("smoothing_speed", 5.0)) + var zero_transform: bool = bool(params.get("zero_transform", true)) + + var old_parent := node.get_parent() + var old_idx: int = node.get_index() if old_parent != null else 0 + var old_position = node.get("position") + var old_rotation = node.get("rotation") + var old_smoothing_enabled: bool = bool(node.get("position_smoothing_enabled")) + var old_smoothing_speed: float = float(node.get("position_smoothing_speed")) + + var already_child: bool = old_parent == target + var reparented: bool = not already_child + + _undo_redo.create_action("MCP: Camera follow %s" % target.name) + if reparented: + _undo_redo.add_do_method(old_parent, "remove_child", node) + _undo_redo.add_do_method(target, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + _undo_redo.add_do_reference(node) + if zero_transform: + if target is Node2D: + _undo_redo.add_do_property(node, "position", Vector2.ZERO) + _undo_redo.add_undo_property(node, "position", old_position) + _undo_redo.add_do_property(node, "rotation", 0.0) + _undo_redo.add_undo_property(node, "rotation", old_rotation) + _undo_redo.add_do_property(node, "position_smoothing_enabled", true) + _undo_redo.add_undo_property(node, "position_smoothing_enabled", old_smoothing_enabled) + if smoothing_speed > 0.0: + _undo_redo.add_do_property(node, "position_smoothing_speed", smoothing_speed) + _undo_redo.add_undo_property(node, "position_smoothing_speed", old_smoothing_speed) + if reparented: + _undo_redo.add_undo_method(target, "remove_child", node) + _undo_redo.add_undo_method(old_parent, "add_child", node, true) + _undo_redo.add_undo_method(old_parent, "move_child", node, old_idx) + _undo_redo.add_undo_method(node, "set_owner", scene_root) + _undo_redo.add_undo_reference(node) + _undo_redo.commit_action() + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "target_path": McpScenePath.from_node(target, scene_root), + "reparented": reparented, + "smoothing_speed": smoothing_speed, + "zero_transform": zero_transform and (target is Node2D), + "undoable": true, + } + } + + +# ============================================================================ +# camera_get +# ============================================================================ + +func get_camera(params: Dictionary) -> Dictionary: + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var camera_path: String = params.get("camera_path", "") + var node: Node = null + var resolved_via: String = "" + if camera_path.is_empty(): + # Empty: prefer the viewport's active camera. In headless editor CI, + # Camera2D.is_current() can lag make_current() briefly even after the + # viewport slot has switched; falling through to "first" during that + # window makes camera_get("") nondeterministic. + var all_cams := _list_cameras_in_scene(scene_root, "") + var logical_current := _logical_current_camera(scene_root) + if logical_current != null and all_cams.has(logical_current): + node = logical_current + resolved_via = "current" + var viewport_current := _viewport_current_camera(scene_root) + if node == null and viewport_current != null and all_cams.has(viewport_current): + node = viewport_current + resolved_via = "current" + for cam in all_cams: + if node != null: + break + if _is_current(cam): + node = cam + resolved_via = "current" + break + if node == null and not all_cams.is_empty(): + node = all_cams[0] + resolved_via = "first" + else: + node = McpScenePath.resolve(camera_path, scene_root) + if node == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_node_error(camera_path, scene_root)) + if not _is_camera(node): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node %s is not a camera (got %s)" % [camera_path, node.get_class()] + ) + resolved_via = "path" + + if node == null: + return { + "data": { + "path": "", + "type": "", + "class": "", + "current": false, + "properties": {}, + "resolved_via": "not_found", + } + } + + var type_str := _camera_type_str(node) + var keys: Array = _KEYS_2D if type_str == "2d" else _KEYS_3D + var prop_types := _property_type_map(node) + var props: Dictionary = {} + var is_current_effective := _resolve_current(scene_root, node) + for key in keys: + if key == "current": + props[key] = is_current_effective + continue + if prop_types.has(key): + props[key] = CameraValues.serialize(node.get(key)) + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "type": type_str, + "class": node.get_class(), + "current": is_current_effective, + "properties": props, + "resolved_via": resolved_via, + } + } + + +# ============================================================================ +# camera_list +# ============================================================================ + +func list_cameras(_params: Dictionary) -> Dictionary: + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var cams := _list_cameras_in_scene(scene_root, "") + var out: Array[Dictionary] = [] + var logical_2d := _logical_current_camera(scene_root, "2d") + var logical_3d := _logical_current_camera(scene_root, "3d") + for cam in cams: + out.append({ + "path": McpScenePath.from_node(cam, scene_root), + "class": cam.get_class(), + "type": _camera_type_str(cam), + "current": _resolve_current_with_logicals(cam, logical_2d, logical_3d), + }) + return {"data": {"cameras": out}} + + +# ============================================================================ +# camera_apply_preset +# ============================================================================ + +func apply_preset(params: Dictionary) -> Dictionary: + var preset_name: String = params.get("preset", "") + if preset_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: preset") + + var overrides: Dictionary = params.get("overrides", {}) + var blueprint = CameraPresets.build(preset_name, overrides) + if blueprint == null: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown preset '%s'. Valid: %s" % [preset_name, ", ".join(CameraPresets.list_presets())] + ) + + var parent_path: String = params.get("parent_path", "") + var node_name: String = params.get("name", "") + var type_str: String = params.get("type", String(blueprint.get("default_type", "2d"))) + var make_current: bool = bool(params.get("make_current", true)) + if node_name.is_empty(): + node_name = preset_name.capitalize() + if not _VALID_TYPES.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid camera type '%s'. Valid: %s" % [type_str, ", ".join(_VALID_TYPES.keys())] + ) + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + var node := _instantiate_camera(type_str) + node.name = node_name + + var preset_props: Dictionary = blueprint.get("properties", {}) + var valid_keys: Array = _KEYS_2D if type_str == "2d" else _KEYS_3D + var prop_types := _property_type_map(node) + var applied: Array[String] = [] + for prop in preset_props: + var prop_name := String(prop) + if not (prop_name in valid_keys): + continue # Silently skip preset keys that don't apply to this camera class. + # `current` lives on methods, not as a writable property on Camera2D — + # always handled via the make_current path below. + if prop_name == "current": + continue + var prop_type: int = prop_types.get(prop_name, TYPE_NIL) + if prop_type == TYPE_NIL: + continue + var coerce_result := CameraValues.coerce(prop_name, preset_props[prop_name], prop_type) + if not coerce_result.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerce_result.error)) + node.set(prop_name, coerce_result.value) + applied.append(prop_name) + + _undo_redo.create_action( + "MCP: Apply camera preset %s" % preset_name, + UndoRedo.MERGE_DISABLE, scene_root + ) + _undo_redo.add_do_method(parent, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + _undo_redo.add_do_reference(node) + if make_current: + _add_make_current_to_action(node, type_str, scene_root) + _undo_redo.add_undo_method(parent, "remove_child", node) + _undo_redo.commit_action() + if make_current: + _verify_current_after_commit(node) + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "parent_path": McpScenePath.from_node(parent, scene_root), + "name": node_name, + "preset": preset_name, + "type": type_str, + "class": _VALID_TYPES[type_str], + "applied": applied, + "current": bool(make_current), + "undoable": true, + } + } + + +# ============================================================================ +# Helpers +# ============================================================================ + +static func _instantiate_camera(type_str: String) -> Node: + match type_str: + "2d": + return Camera2D.new() + "3d": + return Camera3D.new() + return null + + +static func _is_camera(node: Node) -> bool: + return node is Camera2D or node is Camera3D + + +static func _camera_type_str(node: Node) -> String: + if node is Camera2D: + return "2d" + if node is Camera3D: + return "3d" + return "" + + +func _resolve_camera(params: Dictionary) -> Dictionary: + var resolved := McpNodeValidator.resolve_or_error( + params.get("camera_path", ""), "camera_path", + ) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + if not _is_camera(node): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node %s is not a camera (got %s)" % [node_path, node.get_class()] + ) + return { + "node": node, + "path": node_path, + "type": _camera_type_str(node), + "scene_root": scene_root, + } + + +## Walk the edited scene for cameras. class_filter: "2d", "3d", or "" for all. +static func _list_cameras_in_scene(scene_root: Node, class_filter: String) -> Array: + var result: Array = [] + if scene_root == null: + return result + _collect_cameras(scene_root, class_filter, result) + return result + + +static func _collect_cameras(node: Node, class_filter: String, out: Array) -> void: + var matches := false + match class_filter: + "2d": + matches = node is Camera2D + "3d": + matches = node is Camera3D + _: + matches = node is Camera2D or node is Camera3D + if matches: + out.append(node) + for child in node.get_children(): + _collect_cameras(child, class_filter, out) + + +## Build a name -> property-type dict from the object's property list. +## Single walk of get_property_list() amortizes lookups across a batch of +## properties in configure / apply_preset. +static func _property_type_map(obj: Object) -> Dictionary: + var out: Dictionary = {} + if obj == null: + return out + for prop in obj.get_property_list(): + out[prop.name] = int(prop.get("type", TYPE_NIL)) + return out diff --git a/addons/godot_ai/handlers/camera_handler.gd.uid b/addons/godot_ai/handlers/camera_handler.gd.uid new file mode 100644 index 0000000..86d2aae --- /dev/null +++ b/addons/godot_ai/handlers/camera_handler.gd.uid @@ -0,0 +1 @@ +uid://c0lcviccrlrl8 diff --git a/addons/godot_ai/handlers/camera_presets.gd b/addons/godot_ai/handlers/camera_presets.gd new file mode 100644 index 0000000..a1922c2 --- /dev/null +++ b/addons/godot_ai/handlers/camera_presets.gd @@ -0,0 +1,81 @@ +@tool +extends RefCounted + +## Opinionated Camera2D / Camera3D presets. +## +## build(preset_name, overrides) -> {default_type, properties} | null +## properties are merged with caller overrides (overrides win). + + +const _PRESETS := { + # Top-down roguelite / arena — damped follow feel, drag deadzone. + "topdown_2d": { + "default_type": "2d", + "properties": { + "zoom": {"x": 2.0, "y": 2.0}, + "anchor_mode": "drag_center", + "position_smoothing_enabled": true, + "position_smoothing_speed": 5.0, + "rotation_smoothing_enabled": false, + "drag_horizontal_enabled": true, + "drag_vertical_enabled": true, + "drag_left_margin": 0.2, + "drag_right_margin": 0.2, + "drag_top_margin": 0.2, + "drag_bottom_margin": 0.2, + }, + }, + # Platformer — tight horizontal follow, vertical snap with smoothing on. + "platformer_2d": { + "default_type": "2d", + "properties": { + "zoom": {"x": 1.5, "y": 1.5}, + "anchor_mode": "drag_center", + "position_smoothing_enabled": true, + "position_smoothing_speed": 8.0, + "drag_horizontal_enabled": true, + "drag_vertical_enabled": false, + "drag_left_margin": 0.15, + "drag_right_margin": 0.15, + }, + }, + # Cinematic 3D — narrow FOV, long range. Good for dramatic wide shots. + "cinematic_3d": { + "default_type": "3d", + "properties": { + "fov": 40.0, + "near": 0.1, + "far": 500.0, + "projection": "perspective", + }, + }, + # Action 3D — wider FOV for first/third-person action gameplay. + "action_3d": { + "default_type": "3d", + "properties": { + "fov": 70.0, + "near": 0.1, + "far": 200.0, + "projection": "perspective", + }, + }, +} + + +static func list_presets() -> Array: + return _PRESETS.keys() + + +## Build a preset blueprint. Returns null if preset_name is unknown. +## overrides is merged on top of preset defaults (caller values win). +static func build(preset_name: String, overrides: Dictionary) -> Variant: + if not _PRESETS.has(preset_name): + return null + var preset: Dictionary = _PRESETS[preset_name] + var properties: Dictionary = (preset.get("properties", {}) as Dictionary).duplicate(true) + for key in overrides: + properties[key] = overrides[key] + return { + "default_type": preset.get("default_type", "2d"), + "properties": properties, + } diff --git a/addons/godot_ai/handlers/camera_presets.gd.uid b/addons/godot_ai/handlers/camera_presets.gd.uid new file mode 100644 index 0000000..9f9f839 --- /dev/null +++ b/addons/godot_ai/handlers/camera_presets.gd.uid @@ -0,0 +1 @@ +uid://bl3rfy72o3wy5 diff --git a/addons/godot_ai/handlers/camera_values.gd b/addons/godot_ai/handlers/camera_values.gd new file mode 100644 index 0000000..e3c8dea --- /dev/null +++ b/addons/godot_ai/handlers/camera_values.gd @@ -0,0 +1,132 @@ +@tool +extends RefCounted + +## Value coercion helpers for camera authoring. +## +## Handles: +## - enum-by-name (keep_aspect="keep_height" -> Camera3D.KEEP_HEIGHT) +## - {x, y} dict -> Vector2 (zoom, offset, drag_*_offset) +## - serialization back to JSON-friendly shapes + + +const _ENUM_TABLES := { + "projection": { + "perspective": Camera3D.PROJECTION_PERSPECTIVE, + "orthogonal": Camera3D.PROJECTION_ORTHOGONAL, + "frustum": Camera3D.PROJECTION_FRUSTUM, + }, + "keep_aspect": { + "keep_width": Camera3D.KEEP_WIDTH, + "keep_height": Camera3D.KEEP_HEIGHT, + }, + "anchor_mode": { + "fixed_top_left": Camera2D.ANCHOR_MODE_FIXED_TOP_LEFT, + "drag_center": Camera2D.ANCHOR_MODE_DRAG_CENTER, + }, + "doppler_tracking": { + "disabled": Camera3D.DOPPLER_TRACKING_DISABLED, + "idle_step": Camera3D.DOPPLER_TRACKING_IDLE_STEP, + "physics_step": Camera3D.DOPPLER_TRACKING_PHYSICS_STEP, + }, + "process_callback": { + "physics": Camera2D.CAMERA2D_PROCESS_PHYSICS, + "idle": Camera2D.CAMERA2D_PROCESS_IDLE, + }, +} + + +## Return the enum int for (property, string_name), or null if not a known enum string. +static func resolve_enum(property: String, value: Variant) -> Variant: + if not (value is String): + return null + if not _ENUM_TABLES.has(property): + return null + var table: Dictionary = _ENUM_TABLES[property] + var key: String = String(value).to_lower() + if table.has(key): + return table[key] + return null + + +## Valid enum names for a property, for error messages. +static func enum_keys(property: String) -> Array: + if not _ENUM_TABLES.has(property): + return [] + return (_ENUM_TABLES[property] as Dictionary).keys() + + +static func parse_vector2(value: Variant) -> Variant: + ## Camera-specific sugar kept from the pre-#714 copy: a bare number is + ## a uniform zoom, splatted to both axes. Everything else goes through + ## the canonical strict parser. + if value is int or value is float: + return Vector2(float(value), float(value)) + return McpJsonValues.parse_vector2(value) + + +static func parse_vector3(value: Variant) -> Variant: + return McpJsonValues.parse_vector3(value) + + +## Coerce a JSON-shaped value for a camera property against the declared type. +## Returns {ok: true, value: ...} or {ok: false, error: "..."}. +static func coerce(property: String, value: Variant, target_type: int) -> Dictionary: + # Enum-by-name: must match before generic TYPE_INT coercion. + if _ENUM_TABLES.has(property): + if value is String: + var enum_val = resolve_enum(property, value) + if enum_val == null: + return { + "ok": false, + "error": "Invalid %s value: '%s'. Valid: %s" % [ + property, value, ", ".join(enum_keys(property)) + ], + } + return {"ok": true, "value": int(enum_val)} + if value is int or value is float: + return {"ok": true, "value": int(value)} + + match target_type: + TYPE_VECTOR2: + var v2 = parse_vector2(value) + if v2 == null: + return {"ok": false, "error": "Invalid vector2 for %s: %s" % [property, value]} + return {"ok": true, "value": v2} + TYPE_VECTOR3: + var v3 = parse_vector3(value) + if v3 == null: + return {"ok": false, "error": "Invalid vector3 for %s: %s" % [property, value]} + return {"ok": true, "value": v3} + TYPE_BOOL: + if value is bool: + return {"ok": true, "value": value} + if value is int or value is float: + return {"ok": true, "value": bool(value)} + return {"ok": false, "error": "Expected bool for %s" % property} + TYPE_INT: + if value is int: + return {"ok": true, "value": value} + if value is float: + return {"ok": true, "value": int(value)} + return {"ok": false, "error": "Expected int for %s" % property} + TYPE_FLOAT: + if value is float: + return {"ok": true, "value": value} + if value is int: + return {"ok": true, "value": float(value)} + return {"ok": false, "error": "Expected number for %s" % property} + TYPE_STRING: + return {"ok": true, "value": String(value)} + + return {"ok": true, "value": value} + + +## Serialize a Variant into a JSON-friendly shape for responses. +static func serialize(value: Variant) -> Variant: + if value == null: + return null + if value is Vector2: + return {"x": value.x, "y": value.y} + if value is Vector3: + return {"x": value.x, "y": value.y, "z": value.z} + return value diff --git a/addons/godot_ai/handlers/camera_values.gd.uid b/addons/godot_ai/handlers/camera_values.gd.uid new file mode 100644 index 0000000..45e3c09 --- /dev/null +++ b/addons/godot_ai/handlers/camera_values.gd.uid @@ -0,0 +1 @@ +uid://bgjnubgnv6ses diff --git a/addons/godot_ai/handlers/client_handler.gd b/addons/godot_ai/handlers/client_handler.gd new file mode 100644 index 0000000..40e019f --- /dev/null +++ b/addons/godot_ai/handlers/client_handler.gd @@ -0,0 +1,127 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles MCP client configuration commands. + +var _connection +var _fallback_launch_context := {} +var _status_workers: Array[Thread] = [] +var _status_tearing_down := false + + +func _init(connection = null, fallback_launch_context = null) -> void: + _connection = connection + # Lazy-loading this handler can reload ClientConfigurator's static script and + # clear its warmed snapshot. Retain the plugin-start capture as a safe + # fallback; the worker still prefers capture_launch_context()'s live snapshot. + if fallback_launch_context is Dictionary: + _fallback_launch_context = fallback_launch_context.duplicate(true) + + +func configure_client(params: Dictionary) -> Dictionary: + var client_id: String = params.get("client", "") + if not McpClientConfigurator.has_client(client_id): + var valid := ", ".join(McpClientConfigurator.client_ids()) + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unknown client: %s. Use one of: %s" % [client_id, valid]) + var result := McpClientConfigurator.configure(client_id) + if result.get("status") == "error": + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + result.get("message", "Configuration failed for '%s'" % client_id)) + return {"data": result} + + +func remove_client(params: Dictionary) -> Dictionary: + var client_id: String = params.get("client", "") + if not McpClientConfigurator.has_client(client_id): + var valid := ", ".join(McpClientConfigurator.client_ids()) + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unknown client: %s. Use one of: %s" % [client_id, valid]) + var result := McpClientConfigurator.remove(client_id) + if result.get("status") == "error": + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + result.get("message", "Removal failed for '%s'" % client_id)) + return {"data": result} + + +func check_client_status(params: Dictionary) -> Dictionary: + var request_id: String = params.get("_request_id", "") + if _connection == null or request_id.is_empty(): + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Client status requires a deferred request context.", + ) + if _status_tearing_down: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Client status handler is shutting down.") + # Match the dock refresh worker's cold-load guard. This is pure-memory and + # performs no launcher discovery, CLI lookup, or config/status probe. + McpClientConfigurator.warm_status_worker_bytecode() + # Refresh cwd/project roots on main before the status worker starts while + # preserving the startup launch snapshot for the deferred worker. + var status_context := _fallback_launch_context.duplicate(true) + status_context["project_roots"] = McpClientConfigurator.capture_project_roots() + # The aggregate command has a 30-second budget. Its worker resolves the + # shared Claude Desktop/Codex attach launch once, then reuses it for every + # command-shaped client instead of repeating cold launcher discovery. + # Start the worker from the deferred finisher after its first frame. That + # lets the dispatcher register this request before any probe can complete. + _finish_client_status_deferred( + McpClientConfigurator.run_client_status_sweep.bind(status_context), + request_id, + _connection, + ) + return McpDispatcher.DEFERRED_RESPONSE + + +## Called by McpDispatcher.clear() before releasing this lazy handler. Marking +## teardown is deliberately non-blocking: the in-flight coroutine retains this +## handler and its connection across frames, then joins each worker only after +## is_alive() becomes false. New sweeps are rejected immediately. +func prepare_for_teardown() -> void: + _status_tearing_down = true + + +## This instance coroutine intentionally keeps the lazily-created handler and +## deferred-response connection alive until its worker has been polled and +## joined. The first-frame yield is load-bearing: check_client_status() must +## return the deferred sentinel before the worker can produce a response. +func _finish_client_status_deferred( + worker_callable: Callable, request_id: String, connection +) -> void: + if not is_instance_valid(connection): + return + var tree: SceneTree = connection.get_tree() + if tree == null: + return + await tree.process_frame + if not is_instance_valid(connection) or _status_tearing_down: + return + var worker := Thread.new() + _status_workers.append(worker) + var start_error := worker.start(worker_callable) + if start_error != OK: + _status_workers.erase(worker) + connection.send_deferred_response(request_id, ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Could not start client status worker (error %d)." % start_error, + )) + return + while worker.is_alive(): + await tree.process_frame + var payload: Variant = worker.wait_to_finish() + _status_workers.erase(worker) + if _status_tearing_down: + return + if not is_instance_valid(connection): + return + if not payload is Dictionary: + payload = ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Client status worker returned an invalid response.", + ) + elif payload.has("worker_error"): + payload = ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + str(payload.get("worker_error", "Client status worker failed.")), + ) + connection.send_deferred_response(request_id, payload) diff --git a/addons/godot_ai/handlers/client_handler.gd.uid b/addons/godot_ai/handlers/client_handler.gd.uid new file mode 100644 index 0000000..25687f5 --- /dev/null +++ b/addons/godot_ai/handlers/client_handler.gd.uid @@ -0,0 +1 @@ +uid://bmo4foc5fq75c diff --git a/addons/godot_ai/handlers/control_draw_recipe_handler.gd b/addons/godot_ai/handlers/control_draw_recipe_handler.gd new file mode 100644 index 0000000..29e65be --- /dev/null +++ b/addons/godot_ai/handlers/control_draw_recipe_handler.gd @@ -0,0 +1,318 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles the control_draw_recipe MCP command. Attaches a shared DrawRecipe +## script to a Control and stores the caller's ordered draw ops in node +## metadata under "_ops". The DrawRecipe script dispatches each op to a +## CanvasItem draw_* call in _draw(). One Ctrl+Z reverts script + meta as a +## single undo step. + +const DRAW_RECIPE_SCRIPT := preload("res://addons/godot_ai/runtime/draw_recipe.gd") +const UiHandler := preload("res://addons/godot_ai/handlers/ui_handler.gd") + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +func control_draw_recipe(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var ops_raw: Variant = params.get("ops", null) + var clear_existing: bool = bool(params.get("clear_existing", true)) + + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + if typeof(ops_raw) != TYPE_ARRAY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "ops must be an Array") + + var _resolved := McpNodeValidator.resolve_or_error(path, "path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var scene_root: Node = _resolved.scene_root + if not node is Control: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "control_draw_recipe requires a Control node, got %s" % node.get_class() + ) + + var coerced := _coerce_ops(ops_raw) + if coerced.has("error"): + return coerced + var coerced_ops: Array = coerced.ops + + var old_script: Variant = node.get_script() + if old_script != null and old_script != DRAW_RECIPE_SCRIPT: + if not clear_existing: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + ( + "Node %s already has a script. Pass clear_existing=true to replace." + % path + ) + ) + + var had_meta := node.has_meta("_ops") + var old_ops: Variant = node.get_meta("_ops") if had_meta else null + + _undo_redo.create_action("MCP: Draw recipe on %s" % node.name) + _undo_redo.add_do_method(node, "set_script", DRAW_RECIPE_SCRIPT) + _undo_redo.add_do_method(node, "set_meta", "_ops", coerced_ops) + _undo_redo.add_do_method(node, "queue_redraw") + _undo_redo.add_undo_method(node, "set_script", old_script) + if had_meta: + _undo_redo.add_undo_method(node, "set_meta", "_ops", old_ops) + else: + _undo_redo.add_undo_method(node, "remove_meta", "_ops") + _undo_redo.add_undo_method(node, "queue_redraw") + _undo_redo.commit_action() + + return { + "data": + { + "path": McpScenePath.from_node(node, scene_root), + "ops_count": coerced_ops.size(), + "script_attached": old_script == null, + "script_replaced": old_script != null and old_script != DRAW_RECIPE_SCRIPT, + "undoable": true, + } + } + + + +## Validate and coerce every op dict. Returns {"ops": Array} or an error dict. +func _coerce_ops(ops: Array) -> Dictionary: + var result: Array = [] + for i in ops.size(): + var op: Variant = ops[i] + if typeof(op) != TYPE_DICTIONARY: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, "ops[%d] must be a dictionary" % i + ) + var coerced := _coerce_single_op(op, i) + if coerced.has("error"): + return coerced + result.append(coerced.op) + return {"ops": result} + + +func _coerce_single_op(op: Dictionary, idx: int) -> Dictionary: + var draw_type: String = op.get("draw", "") + if draw_type.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, "ops[%d]: missing 'draw' field" % idx + ) + match draw_type: + "line": + return _coerce_line(op, idx) + "rect": + return _coerce_rect(op, idx) + "arc": + return _coerce_arc(op, idx) + "circle": + return _coerce_circle(op, idx) + "polyline": + return _coerce_polyline_or_polygon(op, idx, "polyline") + "polygon": + return _coerce_polyline_or_polygon(op, idx, "polygon") + "string": + return _coerce_string(op, idx) + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "ops[%d]: unknown draw type '%s'" % [idx, draw_type] + ) + + +func _require_fields(op: Dictionary, idx: int, kind: String, fields: Array) -> Dictionary: + for f in fields: + if not op.has(f): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "ops[%d] (%s): missing '%s'" % [idx, kind, f] + ) + return {} + + +func _coerce_typed(value: Variant, prop_type: int, idx: int, kind: String, field: String) -> Dictionary: + var r := UiHandler._coerce_for_type(value, prop_type) + if r.ok: + return {"ok": true, "value": r.value} + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, "ops[%d] (%s): invalid '%s'" % [idx, kind, field] + ) + + +func _coerce_line(op: Dictionary, idx: int) -> Dictionary: + var missing := _require_fields(op, idx, "line", ["from", "to", "color"]) + if missing.has("error"): + return missing + var frm := _coerce_typed(op.from, TYPE_VECTOR2, idx, "line", "from") + if frm.has("error"): + return frm + var to_ := _coerce_typed(op.to, TYPE_VECTOR2, idx, "line", "to") + if to_.has("error"): + return to_ + var c := _coerce_typed(op.color, TYPE_COLOR, idx, "line", "color") + if c.has("error"): + return c + var out := {"draw": "line", "from": frm.value, "to": to_.value, "color": c.value} + if op.has("width"): + out["width"] = float(op.width) + if op.has("antialiased"): + out["antialiased"] = bool(op.antialiased) + return {"op": out} + + +func _coerce_rect(op: Dictionary, idx: int) -> Dictionary: + var missing := _require_fields(op, idx, "rect", ["rect", "color"]) + if missing.has("error"): + return missing + var r := _coerce_typed(op.rect, TYPE_RECT2, idx, "rect", "rect") + if r.has("error"): + return r + var c := _coerce_typed(op.color, TYPE_COLOR, idx, "rect", "color") + if c.has("error"): + return c + var out := {"draw": "rect", "rect": r.value, "color": c.value} + if op.has("filled"): + out["filled"] = bool(op.filled) + if op.has("width"): + out["width"] = float(op.width) + return {"op": out} + + +func _coerce_arc(op: Dictionary, idx: int) -> Dictionary: + var missing := _require_fields( + op, idx, "arc", ["center", "radius", "start_angle", "end_angle", "color"] + ) + if missing.has("error"): + return missing + var center := _coerce_typed(op.center, TYPE_VECTOR2, idx, "arc", "center") + if center.has("error"): + return center + var c := _coerce_typed(op.color, TYPE_COLOR, idx, "arc", "color") + if c.has("error"): + return c + var out := { + "draw": "arc", + "center": center.value, + "radius": float(op.radius), + "start_angle": float(op.start_angle), + "end_angle": float(op.end_angle), + "color": c.value, + } + if op.has("point_count"): + out["point_count"] = int(op.point_count) + if op.has("width"): + out["width"] = float(op.width) + if op.has("antialiased"): + out["antialiased"] = bool(op.antialiased) + return {"op": out} + + +func _coerce_circle(op: Dictionary, idx: int) -> Dictionary: + var missing := _require_fields(op, idx, "circle", ["center", "radius", "color"]) + if missing.has("error"): + return missing + var center := _coerce_typed(op.center, TYPE_VECTOR2, idx, "circle", "center") + if center.has("error"): + return center + var c := _coerce_typed(op.color, TYPE_COLOR, idx, "circle", "color") + if c.has("error"): + return c + return { + "op": + { + "draw": "circle", + "center": center.value, + "radius": float(op.radius), + "color": c.value, + } + } + + +func _coerce_polyline_or_polygon(op: Dictionary, idx: int, kind: String) -> Dictionary: + if not op.has("points"): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, "ops[%d] (%s): missing 'points'" % [idx, kind] + ) + if typeof(op.points) != TYPE_ARRAY: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "ops[%d] (%s): 'points' must be an Array" % [idx, kind] + ) + var points := PackedVector2Array() + for j in op.points.size(): + var p := UiHandler._coerce_for_type(op.points[j], TYPE_VECTOR2) + if not p.ok: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "ops[%d] (%s): points[%d] invalid" % [idx, kind, j] + ) + points.append(p.value) + + var out := {"draw": kind, "points": points} + + if op.has("colors"): + if typeof(op.colors) != TYPE_ARRAY: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "ops[%d] (%s): 'colors' must be an Array" % [idx, kind] + ) + var colors := PackedColorArray() + for k in op.colors.size(): + var ck := UiHandler._coerce_for_type(op.colors[k], TYPE_COLOR) + if not ck.ok: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "ops[%d] (%s): colors[%d] invalid" % [idx, kind, k] + ) + colors.append(ck.value) + out["colors"] = colors + elif op.has("color"): + var c := UiHandler._coerce_for_type(op.color, TYPE_COLOR) + if not c.ok: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, "ops[%d] (%s): invalid 'color'" % [idx, kind] + ) + out["color"] = c.value + else: + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "ops[%d] (%s): missing 'color' or 'colors'" % [idx, kind] + ) + + if op.has("width"): + out["width"] = float(op.width) + if op.has("antialiased"): + out["antialiased"] = bool(op.antialiased) + return {"op": out} + + +func _coerce_string(op: Dictionary, idx: int) -> Dictionary: + var missing := _require_fields(op, idx, "string", ["position", "text", "color"]) + if missing.has("error"): + return missing + var pos := _coerce_typed(op.position, TYPE_VECTOR2, idx, "string", "position") + if pos.has("error"): + return pos + var c := _coerce_typed(op.color, TYPE_COLOR, idx, "string", "color") + if c.has("error"): + return c + var out := { + "draw": "string", + "position": pos.value, + "text": str(op.text), + "color": c.value, + } + if op.has("font_size"): + out["font_size"] = int(op.font_size) + if op.has("align"): + out["align"] = int(op.align) + if op.has("max_width"): + out["max_width"] = float(op.max_width) + return {"op": out} diff --git a/addons/godot_ai/handlers/control_draw_recipe_handler.gd.uid b/addons/godot_ai/handlers/control_draw_recipe_handler.gd.uid new file mode 100644 index 0000000..da0aaf9 --- /dev/null +++ b/addons/godot_ai/handlers/control_draw_recipe_handler.gd.uid @@ -0,0 +1 @@ +uid://buat1mt0fjlqb diff --git a/addons/godot_ai/handlers/csg_handler.gd b/addons/godot_ai/handlers/csg_handler.gd new file mode 100644 index 0000000..6380a9a --- /dev/null +++ b/addons/godot_ai/handlers/csg_handler.gd @@ -0,0 +1,118 @@ +@tool +extends RefCounted + +## CSG authoring — create CSG shapes (box, sphere, cylinder, torus, prism) +## and set their boolean operation (union / intersection / subtraction) so +## agents can carve geometry (holes, caves, tunnels) directly in the editor. +## +## All ops target nodes in the currently edited scene by scene-relative +## path. All write ops are undoable via EditorUndoRedoManager. Sibling CSG +## shapes under the same parent combine automatically; use a CSGCombiner3D +## parent when you need explicit grouping. + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +const SHAPES := { + "box": "CSGBox3D", + "sphere": "CSGSphere3D", + "cylinder": "CSGCylinder3D", + "torus": "CSGTorus3D", + "polygon": "CSGPolygon3D", +} + +const OPERATIONS := { + "union": CSGShape3D.OPERATION_UNION, + "intersection": CSGShape3D.OPERATION_INTERSECTION, + "subtraction": CSGShape3D.OPERATION_SUBTRACTION, +} + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +## Create a CSG shape under a Node3D parent. +## params: {parent_path, name="", shape="box", operation="union"} +## Returns: {path, name, shape, operation, undoable} +func create(params: Dictionary) -> Dictionary: + var parent_path: String = params.get("parent_path", "") + var shape: String = params.get("shape", "box") + var operation: String = params.get("operation", "union") + var scene_file: String = params.get("scene_file", "") + + var shape_class: String = SHAPES.get(shape, "") + if shape_class.is_empty(): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown shape: %s. Valid shapes: %s" % [shape, ", ".join(SHAPES.keys())]) + if not OPERATIONS.has(operation): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown operation: %s. Valid operations: %s" % [operation, ", ".join(OPERATIONS.keys())]) + + var scene_check := McpScenePath.require_edited_scene(scene_file) + if scene_check.has("error"): + return scene_check + var scene_root: Node = scene_check.node + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, + McpScenePath.format_parent_error(parent_path, scene_root)) + if not parent is Node3D: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "CSG parent must be a Node3D (got %s)" % parent.get_class()) + + var node: CSGShape3D = ClassDB.instantiate(shape_class) + if node == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s" % shape_class) + var node_name: String = params.get("name", "") + if node_name.is_empty(): + node_name = shape_class + node.name = node_name + node.operation = OPERATIONS[operation] + + _undo_redo.create_action("MCP: Create %s" % node.name) + _undo_redo.add_do_method(parent, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + _undo_redo.add_do_reference(node) + _undo_redo.add_undo_method(parent, "remove_child", node) + _undo_redo.commit_action() + + return {"data": { + "path": McpScenePath.from_node(node, scene_root), + "name": node.name, + "shape": shape, + "operation": operation, + "undoable": true, + }} + + +## Set the boolean operation of a CSG shape. +## params: {path, operation} +## Returns: {operation, undoable} +func set_operation(params: Dictionary) -> Dictionary: + var operation: String = params.get("operation", "") + if not OPERATIONS.has(operation): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown operation: %s. Valid operations: %s" % [operation, ", ".join(OPERATIONS.keys())]) + var resolved := McpNodeValidator.resolve_or_error( + params.get("path", ""), "path", params.get("scene_file", "")) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + if not node is CSGShape3D: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "Node is not a CSGShape3D: %s" % params.get("path", "")) + var shape: CSGShape3D = node + var prev: int = shape.operation + var next: int = OPERATIONS[operation] + ## Target the node in both callbacks so the action lands in the scene + ## undo history (first-target routing); `set` exists on every Object. + _undo_redo.create_action("MCP: CSG set_operation") + _undo_redo.add_do_method(shape, "set", "operation", next) + _undo_redo.add_undo_method(shape, "set", "operation", prev) + _undo_redo.commit_action() + return {"data": {"operation": operation, "undoable": true}} diff --git a/addons/godot_ai/handlers/csg_handler.gd.uid b/addons/godot_ai/handlers/csg_handler.gd.uid new file mode 100644 index 0000000..0f7b976 --- /dev/null +++ b/addons/godot_ai/handlers/csg_handler.gd.uid @@ -0,0 +1 @@ +uid://c4mb0tptu52x2 diff --git a/addons/godot_ai/handlers/curve_handler.gd b/addons/godot_ai/handlers/curve_handler.gd new file mode 100644 index 0000000..e21c47a --- /dev/null +++ b/addons/godot_ai/handlers/curve_handler.gd @@ -0,0 +1,243 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Replaces all points on a Curve / Curve2D / Curve3D resource. The point +## list shape depends on resource type (see `set_points` for the schemas). +## +## Dedicated tool rather than a property set because Curve2D/Curve3D.add_point +## is a method call, not a property — resource_create's `properties` dict can't +## reach it. + +const NodeHandler := preload("res://addons/godot_ai/handlers/node_handler.gd") + +var _undo_redo: EditorUndoRedoManager +var _connection: McpConnection + + +func _init(undo_redo: EditorUndoRedoManager, connection: McpConnection = null) -> void: + _undo_redo = undo_redo + _connection = connection + + +func set_points(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + var property: String = params.get("property", "") + var resource_path: String = params.get("resource_path", "") + var new_points: Array = params.get("points", []) + + var home_err := McpResourceIO.validate_home(params) + if home_err != null: + return home_err + var has_file_target := not resource_path.is_empty() + if not (new_points is Array): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "points must be an array") + + var curve: Resource + var node: Node = null + var curve_created := false + if has_file_target: + var rpath_err = McpPathValidator.loadable_error(resource_path, "resource_path") + if rpath_err != null: + return rpath_err + if not ResourceLoader.exists(resource_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % resource_path) + # ResourceLoader.load() returns Godot's cached Resource. Duplicate + # before mutating so: (a) open scenes holding a reference to this + # .tres don't silently see the new points outside any undo action, + # and (b) if ResourceSaver.save() fails we haven't corrupted the + # in-memory cache (cache/disk divergence). Also guard against + # ResourceLoader.exists() succeeding but load() returning null + # (corrupt .tres, unregistered class) — otherwise curve.get_class() + # on the response line below would crash the plugin. + var loaded_curve: Resource = ResourceLoader.load(resource_path) + if loaded_curve == null: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to load curve from %s (file exists but load returned null — may be corrupt)" % resource_path + ) + curve = loaded_curve.duplicate() + else: + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + node = McpScenePath.resolve(node_path, scene_root) + if node == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_node_error(node_path, scene_root)) + if not (property in node): + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + McpPropertyErrors.build_message(node, property) + ) + curve = node.get(property) + # Auto-create a fresh Curve subclass if the slot is empty. Infer the + # concrete class from the property's hint_string (e.g. Path3D.curve's + # hint is "Curve3D"). Creation is bundled into the same undo action + # as the point-set below, so Ctrl-Z rolls back both. + if curve == null: + var inferred := _infer_curve_class(node, property) + if inferred.is_empty(): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Curve slot on %s.%s is null and the Curve class can't be inferred from the property hint — create one first with resource_create (type=Curve3D/Curve2D/Curve)" % [node.get_class(), property] + ) + curve = ClassDB.instantiate(inferred) + if curve == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s" % inferred) + curve_created = true + + if not (curve is Curve or curve is Curve2D or curve is Curve3D): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Resource is %s — must be Curve, Curve2D, or Curve3D" % curve.get_class() + ) + + var coerced := _coerce_points(curve, new_points) + if coerced.has("error"): + return coerced.error + + var new_snapshot: Array = coerced.snapshot + + if has_file_target: + _apply_snapshot_to_curve(curve, new_snapshot) + # curve_set_points EDITS an existing .tres, so override the default + # "delete to revert" message via extra_fields. + return McpResourceIO.save_to_disk(curve, resource_path, true, "Curve", { + "curve_class": curve.get_class(), + "point_count": new_snapshot.size(), + "reason": "File save is persistent; edit the .tres file manually to revert", + }, _connection) + + # Inline (node-attached) path: swap the curve property so the action lands + # cleanly in scene history, mirroring the resource-swap pattern used by + # material_handler::assign_material. When curve_created is true the + # "old" value is null — undo clears the slot back to empty. + var new_curve: Resource = curve if curve_created else curve.duplicate() + _apply_snapshot_to_curve(new_curve, new_snapshot) + var old_curve: Resource = null if curve_created else curve + + _undo_redo.create_action("MCP: Set %d points on %s.%s" % [new_snapshot.size(), node.name, property]) + _undo_redo.add_do_property(node, property, new_curve) + _undo_redo.add_undo_property(node, property, old_curve) + _undo_redo.add_do_reference(new_curve) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "property": property, + "curve_class": new_curve.get_class(), + "point_count": new_snapshot.size(), + "curve_created": curve_created, + "undoable": true, + } + } + + +## Infer the concrete Curve class to instantiate for a null property slot. +## Reads the property's hint_string (set by Godot on resource-typed exports) +## to get the exact accepted class name (e.g. "Curve3D" for Path3D.curve). +## Returns empty string if no viable curve class can be determined. +static func _infer_curve_class(node: Node, property: String) -> String: + for prop in node.get_property_list(): + if prop.name != property: + continue + var hint_string: String = prop.get("hint_string", "") + if hint_string.is_empty(): + return "" + if not ClassDB.class_exists(hint_string): + return "" + if hint_string == "Curve" or hint_string == "Curve2D" or hint_string == "Curve3D": + return hint_string + # Some custom properties may list a parent class; require an exact + # match against our three supported types to avoid surprises. + return "" + return "" + + +## Convert input `points` into a normalized snapshot of typed values for +## the given curve type. Returns {snapshot: Array} on success or +## {error: ...} on failure. +static func _coerce_points(curve: Resource, points: Array) -> Dictionary: + var snapshot: Array = [] + if curve is Curve: + for i in range(points.size()): + var p = points[i] + if not (p is Dictionary) or not p.has("offset") or not p.has("value"): + return {"error": ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Curve points[%d] must be {offset, value, [left_tangent, right_tangent]}" % i + )} + snapshot.append({ + "offset": float(p["offset"]), + "value": float(p["value"]), + "left_tangent": float(p.get("left_tangent", 0.0)), + "right_tangent": float(p.get("right_tangent", 0.0)), + }) + elif curve is Curve2D: + var zero2 := {"x": 0, "y": 0} + for i in range(points.size()): + var p2 = points[i] + if not (p2 is Dictionary) or not p2.has("position"): + return {"error": ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Curve2D points[%d] must have 'position' (and optional 'in', 'out')" % i + )} + var axes2 := { + "position": p2["position"], + "in": p2.get("in", zero2), + "out": p2.get("out", zero2), + } + var coerced2 := {} + for field in ["position", "in", "out"]: + var v = NodeHandler._coerce_value(axes2[field], TYPE_VECTOR2) + var err := NodeHandler._check_coerced(v, TYPE_VECTOR2, "Curve2D points[%d].%s" % [i, field]) + if err != null: + return {"error": err} + coerced2[field] = v + snapshot.append(coerced2) + else: # Curve3D + var zero3 := {"x": 0, "y": 0, "z": 0} + for i in range(points.size()): + var p3 = points[i] + if not (p3 is Dictionary) or not p3.has("position"): + return {"error": ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Curve3D points[%d] must have 'position' (and optional 'in', 'out', 'tilt')" % i + )} + var axes3 := { + "position": p3["position"], + "in": p3.get("in", zero3), + "out": p3.get("out", zero3), + } + var coerced3 := {} + for field in ["position", "in", "out"]: + var v = NodeHandler._coerce_value(axes3[field], TYPE_VECTOR3) + var err := NodeHandler._check_coerced(v, TYPE_VECTOR3, "Curve3D points[%d].%s" % [i, field]) + if err != null: + return {"error": err} + coerced3[field] = v + coerced3["tilt"] = float(p3.get("tilt", 0.0)) + snapshot.append(coerced3) + return {"snapshot": snapshot} + + +func _apply_snapshot_to_curve(curve: Resource, snapshot: Array) -> void: + curve.clear_points() + if curve is Curve: + for p: Dictionary in snapshot: + curve.add_point( + Vector2(p.offset, p.value), + p.left_tangent, + p.right_tangent + ) + elif curve is Curve2D: + for p: Dictionary in snapshot: + curve.add_point(p.position, p["in"], p.out) + elif curve is Curve3D: + for i in range(snapshot.size()): + var p: Dictionary = snapshot[i] + curve.add_point(p.position, p["in"], p.out) + curve.set_point_tilt(i, p.tilt) diff --git a/addons/godot_ai/handlers/curve_handler.gd.uid b/addons/godot_ai/handlers/curve_handler.gd.uid new file mode 100644 index 0000000..8eb5b25 --- /dev/null +++ b/addons/godot_ai/handlers/curve_handler.gd.uid @@ -0,0 +1 @@ +uid://dboqr06a1fvqx diff --git a/addons/godot_ai/handlers/editor_handler.gd b/addons/godot_ai/handlers/editor_handler.gd new file mode 100644 index 0000000..8516eed --- /dev/null +++ b/addons/godot_ai/handlers/editor_handler.gd @@ -0,0 +1,1060 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const Telemetry := preload("res://addons/godot_ai/telemetry.gd") +const VisionRoutingScript := preload("res://addons/godot_ai/vision_routing.gd") + +## Handles editor state, selection, log, screenshot, and performance commands. + +const UpdateMixedState := preload("res://addons/godot_ai/utils/update_mixed_state.gd") + +var _log_buffer: McpLogBuffer +var _connection: McpConnection +var _debugger_plugin: McpDebuggerPlugin +var _game_log_buffer: McpGameLogBuffer +var _editor_log_buffer: McpEditorLogBuffer +var _debugger_errors_root: Node +var _surfaced_error_tracker +var _vision_routing: VisionRoutingScript = null + + +func _init(log_buffer: McpLogBuffer, connection: McpConnection = null, debugger_plugin: McpDebuggerPlugin = null, game_log_buffer: McpGameLogBuffer = null, editor_log_buffer: McpEditorLogBuffer = null, debugger_errors_root: Node = null, surfaced_error_tracker = null, vision_routing: VisionRoutingScript = null) -> void: + _log_buffer = log_buffer + _connection = connection + _debugger_plugin = debugger_plugin + _game_log_buffer = game_log_buffer + _editor_log_buffer = editor_log_buffer + _debugger_errors_root = debugger_errors_root + _surfaced_error_tracker = surfaced_error_tracker + _vision_routing = vision_routing + if _surfaced_error_tracker == null: + _surfaced_error_tracker = McpSurfacedErrorTracker.new(_editor_log_buffer, _game_log_buffer, _debugger_errors_root) + + +func get_editor_state(_params: Dictionary) -> Dictionary: + var scene_root := EditorInterface.get_edited_scene_root() + var game_status := _current_game_status() + var data := { + "godot_version": Engine.get_version_info().get("string", "unknown"), + "project_name": ProjectSettings.get_setting("application/config/name", ""), + "current_scene": scene_root.scene_file_path if scene_root else "", + "is_playing": EditorInterface.is_playing_scene(), + "readiness": McpConnection.get_readiness(), + ## True once the game subprocess autoload has beaconed mcp:hello; + ## false between Play→Stop cycles. Lets capture-source=game callers + ## poll for a real ready signal instead of guessing with sleep(). + "game_capture_ready": _debugger_plugin != null and _debugger_plugin.is_game_capture_ready(), + "game_status": game_status, + "helper_live": bool(game_status.get("helper_live", false)), + "session_active": bool(game_status.get("session_active", false)), + } + ## Half-installed addon tree from a failed self-update rollback. When + ## non-empty, the agent / dock paint the operator-facing recovery copy + ## from `update_mixed_state.gd::diagnose`. Field omitted when the + ## addons tree is clean so editor_state's normal payload stays small. + ## See issue #354 / audit-v2 #10. + var mixed_state := UpdateMixedState.diagnose() + if not mixed_state.is_empty(): + data["mixed_state"] = mixed_state + return {"data": data} + + +func get_selection(_params: Dictionary) -> Dictionary: + var scene_root := EditorInterface.get_edited_scene_root() + var selected := EditorInterface.get_selection().get_selected_nodes() + var paths: Array[String] = [] + for node in selected: + paths.append(McpScenePath.from_node(node, scene_root)) + return {"data": {"selected_paths": paths, "count": paths.size()}} + + +const VALID_LOG_SOURCES := ["plugin", "game", "editor", "all"] + +## Deferred budget for the `input_sequence` game op. Unlike the one-shot game +## ops (covered by game_command's 15s entry), it drives the game forward one +## frame per step, so the reply legitimately takes seconds. The game side caps +## the sequence length (GameHelper.MAX_SEQUENCE_FRAMES) well inside this; the +## budget is the backstop for a frozen game loop, mirroring take_screenshot. +const INPUT_SEQUENCE_TIMEOUT_SEC := 30.0 + + +func get_logs(params: Dictionary) -> Dictionary: + ## Coerce defensively — MCP clients can send JSON numbers as floats or + ## stray `null` values that would otherwise fail the typed locals + ## before we ever reach the INVALID_PARAMS return below. + var count: int = maxi(0, int(params.get("count", 50))) + var offset: int = maxi(0, int(params.get("offset", 0))) + var source: String = str(params.get("source", "plugin")) + var include_details: bool = bool(params.get("include_details", false)) + var has_since_cursor := params.has("since_cursor") and params.get("since_cursor") != null + var since_cursor: int = maxi(0, int(params.get("since_cursor", 0))) + var since_run_id := "" if params.get("since_run_id", null) == null else str(params.get("since_run_id", "")) + if not source in VALID_LOG_SOURCES: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid source '%s' — use 'plugin', 'game', 'editor', or 'all'" % source, + ) + + match source: + "plugin": + return _get_plugin_logs(count, offset) + "game": + return _get_game_logs(count, offset, include_details, since_run_id) + "editor": + return _get_editor_logs(count, offset, include_details, has_since_cursor, since_cursor) + "all": + return _get_all_logs(count, offset, include_details) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Unreachable") + + +func _current_game_status() -> Dictionary: + if _debugger_plugin == null: + return McpDebuggerPlugin.with_liveness_flags({ + "status": "stopped", + "active": false, + "ready": false, + "helper_expected": true, + }) + return _debugger_plugin.get_game_status() + + +func _get_plugin_logs(count: int, offset: int) -> Dictionary: + var all_lines := _log_buffer.get_recent(_log_buffer.total_count()) + var page: Array[Dictionary] = [] + var stop := mini(all_lines.size(), offset + count) + for i in range(mini(offset, all_lines.size()), stop): + page.append({"source": "plugin", "level": "info", "text": all_lines[i]}) + return { + "data": { + "source": "plugin", + "lines": page, + "total_count": all_lines.size(), + "returned_count": page.size(), + "offset": offset, + } + } + + +func _get_game_logs(count: int, offset: int, include_details: bool, since_run_id: String = "") -> Dictionary: + var game_status := _current_game_status() + var helper_live := bool(game_status.get("helper_live", false)) + var session_active := bool(game_status.get("session_active", false)) + if _game_log_buffer == null: + return { + "data": { + "source": "game", + "lines": [], + "total_count": 0, + "returned_count": 0, + "offset": offset, + "run_id": "", + "current_run_id": "", + "is_running": session_active, + "helper_live": helper_live, + "session_active": session_active, + "game_status": game_status, + "dropped_count": 0, + "stale_run_id": false, + } + } + var current_run_id := _game_log_buffer.run_id() + var target_run_id := since_run_id if not since_run_id.is_empty() else current_run_id + var stale_run_id := not since_run_id.is_empty() and since_run_id != current_run_id + var run_page := _game_log_buffer.get_run_page(target_run_id, offset, count) + var page := _entries_for_response(run_page.get("entries", []), include_details) + var data := { + "source": "game", + "lines": page, + "total_count": int(run_page.get("total_count", 0)), + "returned_count": page.size(), + "offset": offset, + "run_id": target_run_id, + "current_run_id": current_run_id, + "is_running": session_active, + "helper_live": helper_live, + "session_active": session_active, + "game_status": game_status, + "dropped_count": _game_log_buffer.dropped_count(), + "stale_run_id": stale_run_id, + } + _merge_editor_errors_hint(data, game_status) + return {"data": data} + + +## #641: boot-time parse errors happen while autoload scripts compile — before +## the game helper's logger attaches via OS.add_logger — so they can NEVER +## appear in the game buffer. They surface only through the editor scope +## (Errors-tab rows + editor logger). Cross-reference them here so an +## empty/clean game log is not mistaken for a clean launch. +func _merge_editor_errors_hint(data: Dictionary, game_status: Dictionary) -> void: + if _debugger_plugin == null: + return + ## A since_run_id read of a prior run must not carry the CURRENT run's + ## editor errors — the hint interprets the run being read. + if bool(data.get("stale_run_id", false)): + return + ## run_token == 0 means no tracked run ever started this session; the + ## run-start cursor would be 0 and every retained editor error would be + ## misattributed to "this run". + if int(game_status.get("run_token", 0)) <= 0: + return + ## One-shot read — force the scan so rows that landed after the last + ## gated scan (and before the deferred timers fire) make the FIRST + ## logs_read(source='game') response, not just a later one. + var errors_info: Dictionary = _debugger_plugin.recent_editor_errors_since( + int(game_status.get("editor_log_cursor", 0)), true) + if str(errors_info.get("scope", "none")) != "run": + return + var errors: Array = errors_info.get("errors", []) + if errors.is_empty(): + return + data["editor_errors_count"] = errors.size() + data["editor_errors_hint"] = ( + "%d editor-side error%s from this run (first: %s) missing from the game log — boot-time parse/load errors occur before the game helper's logger attaches. Read logs_read(source='editor', include_details=true)." + % [errors.size(), "s" if errors.size() != 1 else "", _format_editor_error_summary(errors[0])] + ) + + +func _format_editor_error_summary(entry: Dictionary) -> String: + return McpSurfacedErrorTracker.format_editor_error_summary(entry) + + +func _get_editor_logs(count: int, offset: int, include_details: bool, has_since_cursor: bool = false, since_cursor: int = 0) -> Dictionary: + ## Editor-process script errors (parse errors, @tool runtime errors, + ## EditorPlugin errors, push_error/push_warning). Captured by + ## editor_logger.gd via OS.add_logger and gated on Godot 4.5+; on older + ## engines the buffer can be null. Godot also sends GDScript reload + ## warnings/errors straight to the Debugger dock's Errors tab; those do + ## not flow through OS.add_logger, so merge the visible tree rows here. + if has_since_cursor: + return _get_editor_logs_since(count, since_cursor, include_details) + var all_entries := _collect_editor_log_entries() + var page := _entries_for_response(_slice_entries(all_entries, offset, count), include_details) + var appended_total := _editor_log_buffer.appended_total() if _editor_log_buffer != null else 0 + return { + "data": { + "source": "editor", + "lines": page, + "total_count": all_entries.size(), + "returned_count": page.size(), + "offset": offset, + "dropped_count": _editor_log_buffer.dropped_count() if _editor_log_buffer != null else 0, + "next_cursor": appended_total, + "appended_total": appended_total, + } + } + + +func _get_editor_logs_since(count: int, since_cursor: int, include_details: bool) -> Dictionary: + ## Cursor reads are defined over the monotonic editor logger ring only. + ## Visible Debugger Errors-tab rows are live UI state, not ring entries, + ## so regular offset reads still merge them while since_cursor polling + ## reports only Logger-backed entries. + var captured := { + "cursor": since_cursor, + "oldest_cursor": 0, + "next_cursor": 0, + "appended_total": 0, + "truncated": false, + "has_more": false, + "entries": [], + } + var dropped := 0 + if _editor_log_buffer != null: + captured = _editor_log_buffer.get_since(since_cursor, count) + dropped = _editor_log_buffer.dropped_count() + var page := _entries_for_response(captured.get("entries", []), include_details) + return { + "data": { + "source": "editor", + "lines": page, + "total_count": int(captured.get("appended_total", 0)), + "returned_count": page.size(), + "offset": 0, + "dropped_count": dropped, + "cursor": int(captured.get("cursor", since_cursor)), + "oldest_cursor": int(captured.get("oldest_cursor", 0)), + "next_cursor": int(captured.get("next_cursor", 0)), + "appended_total": int(captured.get("appended_total", 0)), + "truncated": bool(captured.get("truncated", false)), + "has_more": bool(captured.get("has_more", false)), + } + } + + +func _get_all_logs(count: int, offset: int, include_details: bool) -> Dictionary: + ## Plugin lines have no timestamp, so we can't merge chronologically. + ## Concatenate plugin → editor → game and apply the offset/count window + ## over the combined list. The per-line `source` field tells callers + ## where each entry came from. Editor goes between plugin and game so + ## script errors stay grouped near the plugin recv/send traffic that + ## triggered them, with game runtime logs at the end. + var combined: Array[Dictionary] = [] + for line in _log_buffer.get_recent(_log_buffer.total_count()): + combined.append({"source": "plugin", "level": "info", "text": line}) + for entry in _collect_editor_log_entries(): + combined.append(entry) + var run_id := "" + var current_run_id := "" + var dropped := 0 + if _game_log_buffer != null: + run_id = _game_log_buffer.run_id() + current_run_id = run_id + dropped = _game_log_buffer.dropped_count() + var run_page := _game_log_buffer.get_run_page(run_id, 0, McpGameLogBuffer.MAX_LINES) + for entry in run_page.get("entries", []): + combined.append(entry) + var stop := mini(combined.size(), offset + count) + var page: Array[Dictionary] = [] + for i in range(mini(offset, combined.size()), stop): + page.append(combined[i]) + page = _entries_for_response(page, include_details) + if _editor_log_buffer != null: + dropped += _editor_log_buffer.dropped_count() + var game_status := _current_game_status() + return { + "data": { + "source": "all", + "lines": page, + "total_count": combined.size(), + "returned_count": page.size(), + "offset": offset, + "run_id": run_id, + "current_run_id": current_run_id, + "is_running": bool(game_status.get("session_active", false)), + "helper_live": bool(game_status.get("helper_live", false)), + "session_active": bool(game_status.get("session_active", false)), + "game_status": game_status, + "dropped_count": dropped, + } + } + + +func _entries_for_response(entries: Array[Dictionary], include_details: bool) -> Array[Dictionary]: + ## Compact responses only drop the top-level "details" key, so a shallow + ## copy is enough; the deep copy is reserved for the opt-in details path + ## where nested dicts leave the buffer. + var out: Array[Dictionary] = [] + for entry in entries: + if include_details: + out.append(entry.duplicate(true)) + else: + var copy: Dictionary = entry.duplicate(false) + copy.erase("details") + out.append(copy) + return out + + +func _collect_editor_log_entries() -> Array[Dictionary]: + return _surfaced_error_tracker.collect_editor_log_entries() + + +static func _slice_entries(entries: Array[Dictionary], offset: int, count: int) -> Array[Dictionary]: + var page: Array[Dictionary] = [] + var stop := mini(entries.size(), offset + count) + for i in range(mini(offset, entries.size()), stop): + page.append(entries[i]) + return page + + +## Map of human-readable monitor names to Performance.Monitor enum values. +const MONITORS := { + "time/fps": Performance.TIME_FPS, + "time/process": Performance.TIME_PROCESS, + "time/physics_process": Performance.TIME_PHYSICS_PROCESS, + "time/navigation_process": Performance.TIME_NAVIGATION_PROCESS, + "memory/static": Performance.MEMORY_STATIC, + "memory/static_max": Performance.MEMORY_STATIC_MAX, + "memory/message_buffer_max": Performance.MEMORY_MESSAGE_BUFFER_MAX, + "object/count": Performance.OBJECT_COUNT, + "object/resource_count": Performance.OBJECT_RESOURCE_COUNT, + "object/node_count": Performance.OBJECT_NODE_COUNT, + "object/orphan_node_count": Performance.OBJECT_ORPHAN_NODE_COUNT, + "render/total_objects_in_frame": Performance.RENDER_TOTAL_OBJECTS_IN_FRAME, + "render/total_primitives_in_frame": Performance.RENDER_TOTAL_PRIMITIVES_IN_FRAME, + "render/total_draw_calls_in_frame": Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME, + "render/video_mem_used": Performance.RENDER_VIDEO_MEM_USED, + "physics_2d/active_objects": Performance.PHYSICS_2D_ACTIVE_OBJECTS, + "physics_2d/collision_pairs": Performance.PHYSICS_2D_COLLISION_PAIRS, + "physics_2d/island_count": Performance.PHYSICS_2D_ISLAND_COUNT, + "physics_3d/active_objects": Performance.PHYSICS_3D_ACTIVE_OBJECTS, + "physics_3d/collision_pairs": Performance.PHYSICS_3D_COLLISION_PAIRS, + "physics_3d/island_count": Performance.PHYSICS_3D_ISLAND_COUNT, + "navigation/active_maps": Performance.NAVIGATION_ACTIVE_MAPS, + "navigation/region_count": Performance.NAVIGATION_REGION_COUNT, + "navigation/agent_count": Performance.NAVIGATION_AGENT_COUNT, + "navigation/link_count": Performance.NAVIGATION_LINK_COUNT, + "navigation/polygon_count": Performance.NAVIGATION_POLYGON_COUNT, + "navigation/edge_count": Performance.NAVIGATION_EDGE_COUNT, + "navigation/edge_merge_count": Performance.NAVIGATION_EDGE_MERGE_COUNT, + "navigation/edge_connection_count": Performance.NAVIGATION_EDGE_CONNECTION_COUNT, + "navigation/edge_free_count": Performance.NAVIGATION_EDGE_FREE_COUNT, +} + + +## Compute coverage angles from the target's AABB geometry. +## Returns an establishing perspective shot (faces the longest ground axis) +## and an orthographic top-down for spatial layout. The AI iterates from +## there with explicit elevation/azimuth/fov for closeups and detail shots. +func _compute_coverage_angles(aabb: AABB) -> Array[Dictionary]: + var size := aabb.size + var ground_x := maxf(size.x, 0.01) + var ground_z := maxf(size.z, 0.01) + + ## Face the longest ground axis — establishing shot shows maximum extent + var estab_azimuth: float + if ground_x >= ground_z: + estab_azimuth = 0.0 # face along Z, showing X width + else: + estab_azimuth = 90.0 # face along X, showing Z width + + ## FOV: wider for spread-out subjects, narrower for compact ones + var ground_ratio := maxf(ground_x, ground_z) / minf(ground_x, ground_z) + var estab_fov := clampf(40.0 + ground_ratio * 5.0, 45.0, 65.0) + + return [ + {"label": "establishing", "elevation": 25.0, "azimuth": estab_azimuth + 20.0, + "fov": estab_fov, "ortho": false, "padding": 1.8}, + {"label": "top", "elevation": 90.0, "azimuth": 0.0, + "fov": 0.0, "ortho": true}, + ] + + +func take_screenshot(params: Dictionary) -> Dictionary: + ## Vision Routing hook: when enabled, the capture is described by the + ## configured vision provider on a worker thread and the text description + ## is returned instead of the raw image (see vision_routing.gd). Off, no + ## key, or non-image results keep the original behavior. The single source + ## of truth for the `match source:` dispatch lives in _take_screenshot_impl + ## (pinned by tests/unit/test_docs_screenshot_sources.py). + if _vision_routing != null and _vision_routing.is_routing_enabled(): + return _vision_routing.route_editor_screenshot(params, Callable(self, "_take_screenshot_impl"), _connection) + return _take_screenshot_impl(params) + + +func _take_screenshot_impl(params: Dictionary) -> Dictionary: + var source: String = params.get("source", "viewport") + var max_resolution: int = params.get("max_resolution", 0) + var view_target: String = params.get("view_target", "") + var coverage: bool = params.get("coverage", false) + var custom_elevation = params.get("elevation", null) + var custom_azimuth = params.get("azimuth", null) + var custom_fov = params.get("fov", null) + + var viewport: Viewport + match source: + "viewport": + viewport = EditorInterface.get_editor_viewport_3d() + if viewport == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_VIEWPORT_UNAVAILABLE, + "No 3D viewport available", false) + ## The 3D viewport's texture is empty when the edited scene + ## has no Node3D content (2D-only scene, or no scene open), + ## and the empty-image guard further down used to surface + ## that as INTERNAL_ERROR — leaving callers with no signal + ## that the failure was caller-side. Reject up front with a + ## structured hint so the LLM can pick a sensible next step + ## (open a 3D scene, switch to source="cinematic", etc.). + var precheck := viewport_screenshot_precheck(EditorInterface.get_edited_scene_root()) + if precheck.has("error"): + return precheck + "game": + if not EditorInterface.is_playing_scene(): + ## Same editor state as game_eval/game_command's gate below — + ## same EDITOR_NOT_READY shape, not INVALID_PARAMS (the params + ## were fine; the editor just isn't in the required state). + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_GAME_NOT_RUNNING, + "Game is not running — start the project first", false, + "Use source='viewport' for the editor viewport, or start the game with project_run and retry.") + ## The game is always a separate OS process (embedded mode just + ## reparents its window into the editor). Reach the framebuffer + ## via the debugger channel: the `_mcp_game_helper` autoload + ## inside the game process replies with a PNG, and + ## McpDebuggerPlugin pushes the response back through our + ## WebSocket with the same request_id via McpConnection.send_deferred_response. + if _debugger_plugin == null or _connection == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Debugger bridge unavailable — plugin may not be fully initialised") + var request_id: String = params.get("_request_id", "") + if request_id.is_empty(): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Missing request_id — cannot correlate deferred response") + _debugger_plugin.request_game_screenshot(request_id, max_resolution, _connection) + return McpDispatcher.DEFERRED_RESPONSE + "cinematic": + return _take_cinematic_screenshot(max_resolution) + "viewport_2d": + viewport = EditorInterface.get_editor_viewport_2d() + if viewport == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_VIEWPORT_UNAVAILABLE, + "No 2D viewport available", false) + var scene_root_2d := EditorInterface.get_edited_scene_root() + if scene_root_2d == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_NO_SCENE, + "No scene open — open a scene first", false, + "Call scene_open with a scene path (e.g. \"res://main.tscn\") first.") + if not view_target.is_empty() or coverage or custom_elevation != null or custom_azimuth != null or custom_fov != null: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "view_target, coverage, elevation, azimuth, and fov are not supported with source='viewport_2d'" + ) + ## Capture the 2D editor viewport directly; no view_target/coverage for 2D. + RenderingServer.force_draw(false) + var image_2d: Image = viewport.get_texture().get_image() + if image_2d == null or image_2d.is_empty(): + return _empty_image_error( + "viewport_2d", + "Captured an empty image from the 2D viewport. The 2D viewport produced no output — typically headless mode or the 2D viewport has not drawn a frame yet." + ) + return _finalize_image(image_2d, "viewport_2d", max_resolution) + _: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Invalid source '%s' — use 'viewport', 'viewport_2d', 'cinematic', or 'game'" % source) + + ## Handle view_target: temporarily reposition the editor's own camera to + ## frame one or more target nodes, force a render, capture, then restore. + if not view_target.is_empty() and source == "viewport": + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + ## Parse comma-separated paths, deduplicate + var raw_paths := view_target.split(",") + var seen := {} + var unique_paths: Array[String] = [] + for rp in raw_paths: + var p := rp.strip_edges() + if not p.is_empty() and not seen.has(p): + seen[p] = true + unique_paths.append(p) + + ## Resolve each path, collect valid Node3D targets + var targets: Array[Node3D] = [] + var not_found: Array[String] = [] + for p in unique_paths: + var node := McpScenePath.resolve(p, scene_root) + if node == null: + not_found.append(p) + elif not node is Node3D: + not_found.append(p) + else: + targets.append(node as Node3D) + + if targets.is_empty(): + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, "No valid Node3D targets found: %s" % ", ".join(not_found)) + + var cam := viewport.get_camera_3d() + if cam == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_VIEWPORT_UNAVAILABLE, + "No camera in 3D viewport", false) + + ## Merge AABBs from all targets + var combined_aabb := _get_visual_aabb(targets[0]) + for i in range(1, targets.size()): + combined_aabb = combined_aabb.merge(_get_visual_aabb(targets[i])) + + var cam_rid := cam.get_camera_rid() + var saved_xform := cam.global_transform + var saved_fov := cam.fov + var saved_near := cam.near + var saved_far := cam.far + + ## --- Coverage path: multi-angle sweep --- + if coverage: + var images: Array[Dictionary] = [] + for preset in _compute_coverage_angles(combined_aabb): + if preset.get("ortho", false): + ## Orthographic top-down view + var ortho_size := combined_aabb.size.length() * 1.8 + var cam_height := maxf(combined_aabb.size.length() * 3.0, 10.0) + var center := combined_aabb.get_center() + var xform := Transform3D(Basis.IDENTITY, center + Vector3.UP * cam_height) + xform = xform.looking_at(center, Vector3.FORWARD) + RenderingServer.camera_set_orthogonal(cam_rid, ortho_size, saved_near, maxf(saved_far, cam_height * 2.0)) + RenderingServer.camera_set_transform(cam_rid, xform) + else: + ## Perspective view — padding per preset (wide for establishing, tight for detail) + var pad: float = preset.get("padding", 2.5) + var xform := _frame_transform_for_aabb(combined_aabb, preset.fov, preset.elevation, preset.azimuth, pad) + RenderingServer.camera_set_perspective(cam_rid, preset.fov, saved_near, saved_far) + RenderingServer.camera_set_transform(cam_rid, xform) + RenderingServer.force_draw(false) + var img: Image = viewport.get_texture().get_image() + if img != null and not img.is_empty(): + var entry := _finalize_image(img, "viewport", max_resolution) + entry.data["label"] = preset.label + entry.data["elevation"] = preset.elevation + entry.data["azimuth"] = preset.azimuth + entry.data["fov"] = preset.fov + entry.data["ortho"] = preset.get("ortho", false) + images.append(entry.data) + + ## Restore camera state (back to perspective + original transform) + RenderingServer.camera_set_perspective(cam_rid, saved_fov, saved_near, saved_far) + RenderingServer.camera_set_transform(cam_rid, saved_xform) + + ## Consistent with single-shot path: error if no frames rendered + ## (e.g. headless mode where force_draw produces no output). + if images.is_empty(): + return _empty_image_error( + "viewport", + "Coverage sweep rendered no images. The 3D viewport produced no output across any of the preset angles — typically because the editor is in headless mode (force_draw has no rendered output) or the 3D viewport has not drawn a frame yet." + ) + + var aabb_center := combined_aabb.get_center() + var aabb_size := combined_aabb.size + var result_data := { + "source": "viewport", + "view_target": view_target, + "view_target_count": targets.size(), + "coverage": true, + "images": images, + "aabb_center": [aabb_center.x, aabb_center.y, aabb_center.z], + "aabb_size": [aabb_size.x, aabb_size.y, aabb_size.z], + "aabb_longest_ground_axis": "x" if aabb_size.x >= aabb_size.z else "z", + } + if not not_found.is_empty(): + result_data["view_target_not_found"] = not_found + return {"data": result_data} + + ## --- Custom angle / FOV path --- + var use_elev: float = 25.0 if custom_elevation == null else float(custom_elevation) + var use_azim: float = 30.0 if custom_azimuth == null else float(custom_azimuth) + var use_fov: float = saved_fov if custom_fov == null else float(custom_fov) + + var cam_xform := _frame_transform_for_aabb(combined_aabb, use_fov, use_elev, use_azim) + + if custom_fov != null: + RenderingServer.camera_set_perspective(cam_rid, use_fov, saved_near, saved_far) + RenderingServer.camera_set_transform(cam_rid, cam_xform) + RenderingServer.force_draw(false) + + var image: Image = viewport.get_texture().get_image() + + ## Restore camera state + if custom_fov != null: + RenderingServer.camera_set_perspective(cam_rid, saved_fov, saved_near, saved_far) + RenderingServer.camera_set_transform(cam_rid, saved_xform) + + if image == null or image.is_empty(): + return _empty_image_error( + "viewport", + "Framed viewport rendered an empty image after repositioning the camera onto the view_target. The 3D viewport produced no output — typically headless mode or the 3D viewport has not drawn a frame yet." + ) + + var result := _finalize_image(image, "viewport", max_resolution) + result.data["view_target"] = view_target + result.data["view_target_count"] = targets.size() + var aabb_c := combined_aabb.get_center() + var aabb_s := combined_aabb.size + result.data["aabb_center"] = [aabb_c.x, aabb_c.y, aabb_c.z] + result.data["aabb_size"] = [aabb_s.x, aabb_s.y, aabb_s.z] + result.data["aabb_longest_ground_axis"] = "x" if aabb_s.x >= aabb_s.z else "z" + if custom_elevation != null or custom_azimuth != null: + result.data["elevation"] = use_elev + result.data["azimuth"] = use_azim + if custom_fov != null: + result.data["fov"] = use_fov + if not not_found.is_empty(): + result.data["view_target_not_found"] = not_found + return result + + var image: Image = viewport.get_texture().get_image() + + if image == null or image.is_empty(): + return _empty_image_error( + source, + "Captured an empty image from %s. The 3D viewport produced no output — typically headless mode or the 3D viewport has not drawn a frame yet." % source + ) + + return _finalize_image(image, source, max_resolution) + + +## Render the edited scene through its active Camera3D without running the +## game. Mirrors Godot's "Cinematic Preview" display mode but via a +## throwaway SubViewport, so the output has no editor gizmos, selection +## outlines, or grid lines. +func _take_cinematic_screenshot(max_resolution: int) -> Dictionary: + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var scene_camera := _find_current_camera_3d(scene_root) + if scene_camera == null: + return ErrorCodes.make( + ErrorCodes.NODE_NOT_FOUND, + "No current Camera3D in scene — mark a Camera3D as `current` or add one to the scene", + ) + + ## Default to a 16:9 HD capture; size is overridden by _finalize_image's + ## `max_resolution` downscale step when requested. + var render_size := Vector2i(1920, 1080) + var edit_vp := EditorInterface.get_editor_viewport_3d() + if edit_vp != null: + var vs := edit_vp.get_visible_rect().size + if vs.x >= 1.0 and vs.y >= 1.0: + render_size = Vector2i(int(vs.x), int(vs.y)) + + var sub_vp := SubViewport.new() + sub_vp.size = render_size + sub_vp.own_world_3d = false + sub_vp.transparent_bg = false + sub_vp.render_target_update_mode = SubViewport.UPDATE_ONCE + + var cam := Camera3D.new() + cam.fov = scene_camera.fov + cam.near = scene_camera.near + cam.far = scene_camera.far + cam.projection = scene_camera.projection + cam.size = scene_camera.size + cam.keep_aspect = scene_camera.keep_aspect + cam.cull_mask = scene_camera.cull_mask + cam.environment = scene_camera.environment + cam.attributes = scene_camera.attributes + cam.current = true + + sub_vp.add_child(cam) + scene_root.add_child(sub_vp) + ## global_transform is resolved against the ancestor Node3D chain, so it + ## must be set after parenting — otherwise the camera ends up at origin. + cam.global_transform = scene_camera.global_transform + ## NOTIFICATION_TRANSFORM_CHANGED is delivered deferred (next frame's + ## flush_transform_notifications), but force_draw renders immediately — + ## without this flush the RenderingServer still has the identity + ## transform pushed at ENTER_WORLD and the capture shows only sky + ## instead of the camera's actual view (issue #650). + cam.force_update_transform() + + RenderingServer.force_draw(false) + var image: Image = sub_vp.get_texture().get_image() + + scene_root.remove_child(sub_vp) + sub_vp.queue_free() + + if image == null or image.is_empty(): + return _empty_image_error( + "cinematic", + "Cinematic render produced an empty image. The SubViewport returned no texture — typically headless mode (force_draw has no rendered output) or the scene's Camera3D is positioned so nothing visible is in frame." + ) + + var result := _finalize_image(image, "cinematic", max_resolution) + result.data["camera_path"] = McpScenePath.from_node(scene_camera, scene_root) + return result + + +## Reject a `source="viewport"` screenshot before we ever pull the +## texture if the edited scene has no Node3D content. The 3D viewport +## returns an empty (or stale) image in that case; surfacing it as +## INTERNAL_ERROR ("Failed to capture image from viewport") gave LLM +## callers no signal that the right move is to switch source or open a +## 3D scene. 152 hits / 63 uuids in 24h across plugin versions 2.5.0 -> +## 2.5.6 traced back to this. Returns `{}` on success. +## +## Caller passes `EditorInterface.get_edited_scene_root()`; the static +## form lets tests exercise the branches with a synthetic scene root +## without driving the editor. +static func viewport_screenshot_precheck(scene_root: Node) -> Dictionary: + if scene_root == null: + var no_scene_err := _make_viewport_not_3d_error( + "", + "The editor 3D viewport is empty because no scene is open. Open a scene with `scene_open` first." + ) + ## The honest state here is "no scene", not "scene lacks 3D content" + ## — relabel the sub-code so telemetry doesn't conflate the two. + ## `editor_state` stays "viewport_not_3d" for pre-#651 consumers. + no_scene_err["error"]["data"]["sub_code"] = ErrorCodes.SUB_EDITOR_NO_SCENE + return no_scene_err + ## A scene with any Node3D content — root or descendant — has + ## something the 3D viewport can render. Walking the tree (rather + ## than only checking the root type) avoids a false reject on the + ## common `Node` / `Node2D` root + Node3D descendant pattern. + if _scene_has_node3d_content(scene_root): + return {} + var root_type := scene_root.get_class() + var hint: String + var is_2d_scene := scene_root is CanvasItem + if is_2d_scene: + hint = ( + "The 3D viewport is empty because the current scene is 2D (%s root) with no Node3D descendants. " + + "Options: (a) open a 3D scene, " + + "(b) use source=\"cinematic\" if a Camera3D exists in the scene, " + + "(c) use source=\"viewport_2d\" to capture the 2D editor viewport directly, " + + "(d) call scene_get_hierarchy first to inspect what's available." + ) % root_type + else: + hint = ( + "The 3D viewport is empty because the current scene (%s root) has no Node3D content anywhere in the tree. " + + "Options: (a) open or add a Node3D, " + + "(b) use source=\"cinematic\" if a Camera3D exists in the scene, " + + "(c) call scene_get_hierarchy first to inspect what's available." + ) % root_type + var err := _make_viewport_not_3d_error(root_type, hint) + if is_2d_scene: + err["error"]["data"]["suggestion"] = "use source='viewport_2d' for 2D scenes" + return err + + +## True if scene_root is itself a Node3D or owns any Node3D descendant. +## DFS short-circuits on the first hit so empty 2D scenes stay cheap. +static func _scene_has_node3d_content(scene_root: Node) -> bool: + if scene_root is Node3D: + return true + var stack: Array[Node] = [scene_root] + while not stack.is_empty(): + var node: Node = stack.pop_back() + for child in node.get_children(): + if child is Node3D: + return true + stack.append(child) + return false + + +static func _make_viewport_not_3d_error(scene_root_type: String, hint: String) -> Dictionary: + ## `hint` becomes `error.message`; not duplicated into `data` because + ## `GodotCommandError`'s string form already appends every `data` key + ## as a suffix on the agent-visible error. + var err := ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_VIEWPORT_NOT_3D, hint, false) + err["error"]["data"]["editor_state"] = "viewport_not_3d" + err["error"]["data"]["scene_root_type"] = scene_root_type + return err + + +## Reached only when the precheck passed but the texture still came +## back empty — headless rendering, a freshly opened editor whose 3D +## viewport hasn't drawn a frame, or a SubViewport that lost its target. +static func _empty_image_error(source: String, hint: String) -> Dictionary: + ## retryable=false: an empty capture is usually headless mode, where a + ## retry loops forever — the not-yet-drawn-frame case is transient but + ## indistinguishable from here, so don't invite a retry loop. + var err := ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_VIEWPORT_EMPTY, hint, false) + err["error"]["data"]["editor_state"] = "viewport_empty" + err["error"]["data"]["source"] = source + return err + + +## Return the Camera3D that would be active if the scene were running. +## Preference: a descendant with `current=true`, else the first Camera3D +## found in a depth-first walk. +func _find_current_camera_3d(root: Node) -> Camera3D: + var first: Camera3D = null + var stack: Array[Node] = [root] + while not stack.is_empty(): + var node: Node = stack.pop_back() + if node is Camera3D: + if node.current: + return node + if first == null: + first = node + for child in node.get_children(): + stack.append(child) + return first + + +func _finalize_image(image: Image, source: String, max_resolution: int) -> Dictionary: + ## Shared with the game-process copy in runtime/game_helper.gd (#716). + var encoded := McpScreenshotEncode.downscale_and_encode(image, max_resolution) + return { + "data": { + "source": source, + "width": encoded.width, + "height": encoded.height, + "original_width": encoded.original_width, + "original_height": encoded.original_height, + "format": "png", + "image_base64": encoded.base64, + } + } + + +## Recursively compute the visual bounding box of a Node3D and its children. +func _get_visual_aabb(node: Node3D) -> AABB: + var aabb := AABB() + var found := false + if node is VisualInstance3D: + aabb = node.global_transform * node.get_aabb() + found = true + for child in node.get_children(): + if child is Node3D: + var child_aabb := _get_visual_aabb(child) + if child_aabb.size != Vector3.ZERO: + if found: + aabb = aabb.merge(child_aabb) + else: + aabb = child_aabb + found = true + if not found: + aabb = AABB(node.global_position - Vector3(0.5, 0.5, 0.5), Vector3(1, 1, 1)) + return aabb + + +## Calculate a camera Transform3D that frames the given AABB nicely. +## elevation_deg: camera elevation (0 = level, 90 = directly above). Default 25. +## azimuth_deg: camera azimuth (0 = front, 90 = right side). Default 30. +## padding: distance multiplier for breathing room (1.2 = tight, 2.5 = context). Default 1.8. +func _frame_transform_for_aabb(aabb: AABB, fov_degrees: float = 75.0, elevation_deg: float = 25.0, azimuth_deg: float = 30.0, padding: float = 1.8) -> Transform3D: + var center := aabb.get_center() + var radius := aabb.size.length() * 0.5 + var fov_rad := deg_to_rad(fov_degrees) + var distance := radius / tan(fov_rad * 0.5) * padding + ## Floor with an absolute offset so unit-scale AABBs don't place the camera + ## inside or against the target. `radius * 2.0` alone scales to zero as the + ## AABB shrinks; the +1.0 guarantees a minimum of ~1 world-unit of standoff. + distance = maxf(distance, radius * 2.0 + 1.0) + var elev := deg_to_rad(elevation_deg) + var azim := deg_to_rad(azimuth_deg) + var cam_pos := center + Vector3( + distance * cos(elev) * sin(azim), + distance * sin(elev), + distance * cos(elev) * cos(azim), + ) + var xform := Transform3D(Basis.IDENTITY, cam_pos) + ## At ~90° elevation the view direction is parallel to Vector3.UP — use + ## FORWARD as the up hint so looking_at doesn't degenerate. + var up := Vector3.FORWARD if elevation_deg > 85.0 else Vector3.UP + return xform.looking_at(center, up) + + +func get_performance_monitors(params: Dictionary) -> Dictionary: + var filter: Array = params.get("monitors", []) + var result := {} + + if filter.is_empty(): + for key in MONITORS: + result[key] = Performance.get_monitor(MONITORS[key]) + else: + for key in filter: + if MONITORS.has(key): + result[key] = Performance.get_monitor(MONITORS[key]) + + return { + "data": { + "monitors": result, + "monitor_count": result.size(), + } + } + + +func clear_logs(params: Dictionary) -> Dictionary: + var count := _log_buffer.total_count() + _log_buffer.clear() + var data := {"cleared_count": count} + ## The Debugger Errors panel is user-visible editor UI, not an MCP-owned + ## buffer — wiping it stays behind an explicit opt-in. + if bool(params.get("clear_debugger_errors", false)): + data["debugger_errors_cleared"] = _clear_debugger_error_trees() + return {"data": data} + + +func _clear_debugger_error_trees() -> int: + return _surfaced_error_tracker.clear_debugger_error_trees() + + +func reload_plugin(_params: Dictionary) -> Dictionary: + _log_buffer.log("reload_plugin requested, reloading next frame") + ## Persist a pending plugin_reload telemetry event *before* the + ## disable kills the live WebSocket. The re-enabled plugin's + ## _enter_tree flushes via `_telemetry.flush_pending_plugin_reload()`. + Telemetry.record_pending_plugin_reload("mcp_tool") + _do_reload_plugin.call_deferred() + return {"data": {"status": "reloading", "message": "Plugin reload initiated"}} + + +## Force a filesystem rescan before toggling the plugin, so Godot's +## class-name registry picks up any .gd files added since the last scan +## (e.g. via git pull or an agent-driven sync). Without this, re-enable can +## fail with "Could not find type X" when new class_name scripts are on disk +## but not yet registered, leaving the plugin disabled with no recovery path +## short of killing the editor. See issue #83. +# `static` is load-bearing: the deferred coroutine captures no `self`, so +# it survives even if the EditorHandler RefCounted is freed mid-await — +# which is exactly what reload does to this handler's owner. An instance +# coroutine here resumes on a freed object under reload churn. +static func _do_reload_plugin() -> void: + var fs := EditorInterface.get_resource_filesystem() + fs.scan() + var tree := Engine.get_main_loop() as SceneTree + # Cap the wait so a long scan (huge project) doesn't hang reload. + var deadline_ms := Time.get_ticks_msec() + 5000 + while fs.is_scanning() and Time.get_ticks_msec() < deadline_ms: + await tree.process_frame + EditorInterface.set_plugin_enabled("res://addons/godot_ai/plugin.cfg", false) + EditorInterface.set_plugin_enabled("res://addons/godot_ai/plugin.cfg", true) + + +func quit_editor(_params: Dictionary) -> Dictionary: + _log_buffer.log("quit_editor requested, quitting next frame") + ## Defer the quit so the response is sent back before the editor exits. + EditorInterface.get_base_control().get_tree().call_deferred("quit") + return {"data": {"status": "quitting", "message": "Editor quit initiated"}} + + +func game_eval(params: Dictionary) -> Dictionary: + var code: String = params.get("code", "") + if code.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "code is required") + + if _debugger_plugin == null or _connection == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Debugger bridge unavailable — plugin may not be fully initialised") + + if not EditorInterface.is_playing_scene(): + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_GAME_NOT_RUNNING, + "Game is not running — start the project first", false, + "Start the game with project_run (or wait for the user to run it), then retry.") + + var request_id: String = params.get("_request_id", "") + if request_id.is_empty(): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Missing request_id — cannot correlate deferred response") + + _debugger_plugin.request_game_eval(code, request_id, _connection) + return McpDispatcher.DEFERRED_RESPONSE + + +func game_command(params: Dictionary) -> Dictionary: + var op: String = str(params.get("op", "")) + if op.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "op is required") + + if _debugger_plugin == null or _connection == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Debugger bridge unavailable — plugin may not be fully initialised") + + if not EditorInterface.is_playing_scene(): + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_GAME_NOT_RUNNING, + "Game is not running — start the project first", false, + "Start the game with project_run (or wait for the user to run it), then retry.") + + var request_id: String = params.get("_request_id", "") + if request_id.is_empty(): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Missing request_id — cannot correlate deferred response") + + var command_params: Dictionary = params.get("params", {}) + + ## input_sequence steps the game forward frame-by-frame in one call, so it + ## needs a far larger budget than the one-shot game ops that share the + ## `game_command` deferred entry (15s). Widen both timers only for it: the + ## debugger-side pending timer (below) and the dispatcher-side deferred + ## budget (via the sentinel's `_deferred_timeout_ms`). Every other op keeps + ## request_game_command's tight default. + if op == "input_sequence": + _debugger_plugin.request_game_command( + op, command_params, request_id, _connection, INPUT_SEQUENCE_TIMEOUT_SEC + ) + return { + "_deferred": true, + "_deferred_timeout_ms": int(INPUT_SEQUENCE_TIMEOUT_SEC * 1000.0), + } + + _debugger_plugin.request_game_command(op, command_params, request_id, _connection) + return McpDispatcher.DEFERRED_RESPONSE diff --git a/addons/godot_ai/handlers/editor_handler.gd.uid b/addons/godot_ai/handlers/editor_handler.gd.uid new file mode 100644 index 0000000..16d785f --- /dev/null +++ b/addons/godot_ai/handlers/editor_handler.gd.uid @@ -0,0 +1 @@ +uid://dcro7yc8bor6v diff --git a/addons/godot_ai/handlers/environment_handler.gd b/addons/godot_ai/handlers/environment_handler.gd new file mode 100644 index 0000000..6729f1e --- /dev/null +++ b/addons/godot_ai/handlers/environment_handler.gd @@ -0,0 +1,181 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Creates an Environment (+ optional Sky + ProceduralSkyMaterial) chain and +## either assigns it to a WorldEnvironment node or saves it to a .tres file. +## Bundles sub-resource creation + assignment in a single undo action. + +const ResourceHandler := preload("res://addons/godot_ai/handlers/resource_handler.gd") + +var _undo_redo: EditorUndoRedoManager +var _connection: McpConnection + + +func _init(undo_redo: EditorUndoRedoManager, connection: McpConnection = null) -> void: + _undo_redo = undo_redo + _connection = connection + + +const _PRESETS := { + "default": {"sky": true, "fog": false}, + "clear": {"sky": true, "fog": false}, + "sunset": {"sky": true, "fog": false}, + "night": {"sky": true, "fog": false}, + "fog": {"sky": true, "fog": true}, +} + + +func create_environment(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + var resource_path: String = params.get("resource_path", "") + var overwrite: bool = params.get("overwrite", false) + var preset: String = params.get("preset", "default") + var properties: Dictionary = params.get("properties", {}) + var sky_param = params.get("sky", null) # nullable — falls back to preset default + + # environment_create targets the whole WorldEnvironment node (no separate + # `property` param) — pass require_property=false. + var home_err := McpResourceIO.validate_home(params, false) + if home_err != null: + return home_err + + if not _PRESETS.has(preset): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid preset '%s'. Valid: %s" % [preset, ", ".join(_PRESETS.keys())] + ) + + var preset_config: Dictionary = _PRESETS[preset] + var want_sky: bool = preset_config.sky + var sky_properties: Dictionary = {} + if sky_param != null: + if sky_param is bool: + want_sky = sky_param + elif sky_param is Dictionary: + var sky_config: Dictionary = (sky_param as Dictionary).duplicate() + var material_type: String = String(sky_config.get("sky_material", "procedural")).to_lower() + if material_type != "procedural": + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "sky.sky_material must be 'procedural' when sky is a dictionary" + ) + sky_config.erase("sky_material") + sky_properties = sky_config + want_sky = true + else: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "sky must be a bool, null, or dictionary of ProceduralSkyMaterial properties" + ) + + var env := Environment.new() + var sky: Sky = null + var sky_material: ProceduralSkyMaterial = null + if want_sky: + sky_material = ProceduralSkyMaterial.new() + sky = Sky.new() + sky.sky_material = sky_material + env.background_mode = Environment.BG_SKY + env.sky = sky + else: + env.background_mode = Environment.BG_CLEAR_COLOR + + _apply_preset(env, sky_material, preset) + if not sky_properties.is_empty(): + var sky_apply_err := ResourceHandler._apply_resource_properties(sky_material, sky_properties) + if sky_apply_err != null: + return sky_apply_err + if preset_config.fog: + env.volumetric_fog_enabled = true + env.volumetric_fog_density = 0.03 + + if not properties.is_empty(): + var apply_err := ResourceHandler._apply_resource_properties(env, properties) + if apply_err != null: + return apply_err + + if not resource_path.is_empty(): + return _save_environment(env, sky, sky_material, resource_path, overwrite, preset) + return _assign_environment(env, sky, sky_material, node_path, preset) + + +static func _apply_preset(env: Environment, sky_material: ProceduralSkyMaterial, preset: String) -> void: + match preset: + "default", "clear": + if sky_material != null: + sky_material.sky_top_color = Color(0.38, 0.45, 0.55) + sky_material.sky_horizon_color = Color(0.65, 0.67, 0.7) + sky_material.ground_horizon_color = Color(0.65, 0.67, 0.7) + sky_material.ground_bottom_color = Color(0.2, 0.17, 0.13) + sky_material.sun_angle_max = 30.0 + env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY + env.ambient_light_energy = 1.0 + "sunset": + if sky_material != null: + sky_material.sky_top_color = Color(0.25, 0.3, 0.55) + sky_material.sky_horizon_color = Color(1.0, 0.55, 0.3) + sky_material.ground_horizon_color = Color(0.85, 0.4, 0.25) + sky_material.ground_bottom_color = Color(0.2, 0.12, 0.1) + env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY + env.ambient_light_color = Color(1.0, 0.75, 0.55) + env.ambient_light_energy = 0.8 + "night": + if sky_material != null: + sky_material.sky_top_color = Color(0.02, 0.02, 0.07) + sky_material.sky_horizon_color = Color(0.05, 0.07, 0.15) + sky_material.ground_horizon_color = Color(0.04, 0.05, 0.1) + sky_material.ground_bottom_color = Color(0.0, 0.0, 0.02) + env.ambient_light_source = Environment.AMBIENT_SOURCE_COLOR + env.ambient_light_color = Color(0.2, 0.22, 0.35) + env.ambient_light_energy = 0.4 + "fog": + if sky_material != null: + sky_material.sky_top_color = Color(0.65, 0.65, 0.7) + sky_material.sky_horizon_color = Color(0.8, 0.8, 0.82) + sky_material.ground_horizon_color = Color(0.7, 0.7, 0.72) + sky_material.ground_bottom_color = Color(0.3, 0.3, 0.32) + env.ambient_light_source = Environment.AMBIENT_SOURCE_SKY + env.ambient_light_energy = 0.7 + + +func _assign_environment(env: Environment, sky: Sky, sky_material: ProceduralSkyMaterial, node_path: String, preset: String) -> Dictionary: + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + if not (node is WorldEnvironment): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node at %s is %s — must be WorldEnvironment" % [node_path, node.get_class()] + ) + + var old_env = (node as WorldEnvironment).environment + + _undo_redo.create_action("MCP: Create Environment (%s) for %s" % [preset, node.name]) + _undo_redo.add_do_property(node, "environment", env) + _undo_redo.add_undo_property(node, "environment", old_env) + _undo_redo.add_do_reference(env) + if sky != null: + _undo_redo.add_do_reference(sky) + if sky_material != null: + _undo_redo.add_do_reference(sky_material) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "preset": preset, + "sky_created": sky != null, + "sky_material_class": sky_material.get_class() if sky_material != null else "", + "undoable": true, + } + } + + +func _save_environment(env: Environment, _sky: Sky, _sky_material: ProceduralSkyMaterial, resource_path: String, overwrite: bool, preset: String) -> Dictionary: + return McpResourceIO.save_to_disk(env, resource_path, overwrite, "Environment", { + "preset": preset, + }, _connection) diff --git a/addons/godot_ai/handlers/environment_handler.gd.uid b/addons/godot_ai/handlers/environment_handler.gd.uid new file mode 100644 index 0000000..f495f8f --- /dev/null +++ b/addons/godot_ai/handlers/environment_handler.gd.uid @@ -0,0 +1 @@ +uid://b1k7jldwjp5jt diff --git a/addons/godot_ai/handlers/filesystem_handler.gd b/addons/godot_ai/handlers/filesystem_handler.gd new file mode 100644 index 0000000..b17ccc9 --- /dev/null +++ b/addons/godot_ai/handlers/filesystem_handler.gd @@ -0,0 +1,312 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const ScriptHandler := preload("res://addons/godot_ai/handlers/script_handler.gd") + +## Handles file read/write operations and reimport within the Godot project. + +## Bounds for the deferred scan wait. `write_file`/`reimport` register single +## files with `update_file()` (cheap, no global-class rebuild); `scan_filesystem` +## is the heavier, explicit "rebuild the class registry" path agents call after +## adding `class_name` scripts headlessly (no window focus to trigger it). +## Kept under the dispatcher's "scan_filesystem" deferred timeout (30s) so we +## always send a real reply before a DEFERRED_TIMEOUT is synthesised. +const _SCAN_START_GRACE_MSEC := 750 +const _SCAN_SETTLE_MAX_MSEC := 28000 + +## Sidecar the editor writes next to every imported resource. `reimport` reads +## it to tell imported assets from files that merely have a filesystem entry +## (see `_is_imported_resource`). +const IMPORT_SIDECAR_SUFFIX := ".import" + +## Shared single-flight latch for scan_filesystem. `is_scanning()` alone can't +## enforce single-flight: `EditorFileSystem.scan()` doesn't flip `is_scanning()` +## for a frame or two (hence _SCAN_START_GRACE_MSEC), so a second request landing +## in that window would observe `false` and stack another scan() — the exact +## stacked-worker SIGABRT this op exists to avoid (dsarno/godot#6). The latch is +## set before the first scan() and cleared when its settle coroutine finishes; +## concurrent requests coalesce onto the running scan instead of starting one. +## `static` so it's shared across handler instances; it resets on plugin reload +## (script re-parse), which self-heals any latch orphaned by a mid-await teardown. +static var _scan_in_flight := false + +var _connection: McpConnection + + +func _init(connection: McpConnection = null) -> void: + _connection = connection + + +func read_file(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + + var path_err = McpPathValidator.path_error(path, "path") + if path_err != null: + return path_err + + if not FileAccess.file_exists(path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "File not found: %s" % path) + + var file := FileAccess.open(path, FileAccess.READ) + if file == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to open file: %s" % path) + + var content := file.get_as_text() + file.close() + + return { + "data": { + "path": path, + "content": content, + "size": content.length(), + "line_count": content.count("\n") + (1 if not content.is_empty() else 0), + } + } + + +func write_file(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var content: String = params.get("content", "") + + var path_err = McpPathValidator.path_error(path, "path", true) + if path_err != null: + return path_err + + var existed_before := FileAccess.file_exists(path) + + # Shared write path (#714): parent mkdir + write/flush + explicit error + # check live on McpResourceIO so this can't drift from create_script. + var write_failure: Variant = McpResourceIO.write_text_to_disk(path, content) + if write_failure != null: + return write_failure + + # Single-file register, not a full scan() — a scan() per write stacks + # filesystem WorkerThreadPool tasks under concurrent writes and can SIGABRT + # in the global-class update (see dsarno/godot#6 and create_script in + # script_handler.gd). update_file() is what reimport()/material/theme use. + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(path) + + var data := { + "path": path, + "size": content.length(), + "undoable": false, + "reason": "File system operations cannot be undone via editor undo", + } + var is_gdscript := path.ends_with(".gd") + ## A .gd written through the filesystem tool used to skip the parse + ## diagnostics create_script attaches (#714) — the agent's broken + ## script reported plain success and the parse error surfaced only in + ## later editor logs. Same shared check, same response fields. A bare + ## ScriptHandler works here: the diagnostics path touches no instance + ## state (it stays an instance method only for test stubbing). + if is_gdscript: + ScriptHandler.new(null)._attach_gdscript_diagnostics(data, path, content) + data["committed"] = true + data["import_settled"] = existed_before + data["import_settle"] = "already_known" if existed_before else "not_waited" + McpResourceIO.attach_cleanup_hint(data, existed_before, [path]) + + ## Fresh `.gd` writes take create_script's import-settle deferral (#714, + ## #261): reply only once ResourceLoader can see the new resource (or the + ## bounded window elapses), so write_file -> script_attach back-to-back + ## can't 404 on the not-yet-imported script. This CHANGES write_file's + ## response timing for that case — the reply lands up to + ## McpResourceIO.IMPORT_SETTLE_MAX_MSEC later instead of immediately. + ## Scoped to .gd: ResourceLoader never learns plain text files, so an + ## unconditional wait would burn the full window on every fresh .txt. + ## Overwrites, batch_execute (no request_id) and unit-test contexts (no + ## connection) keep the synchronous reply. + var request_id: String = params.get("_request_id", "") + if is_gdscript and not existed_before and _connection != null and not request_id.is_empty(): + McpResourceIO.finish_text_write_deferred(_connection, request_id, path, data) + return McpDispatcher.DEFERRED_RESPONSE + + return {"data": data} + + +func reimport(params: Dictionary) -> Dictionary: + var paths: Array = params.get("paths", []) + + if paths.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: paths (non-empty array)") + + var efs := EditorInterface.get_resource_filesystem() + if efs == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "EditorFileSystem not available", false) + + var reimported: Array[String] = [] + var skipped_non_imported: Array[String] = [] + var not_found: Array[String] = [] + + for path_variant in paths: + var path: String = str(path_variant) + var path_err := McpPathValidator.validate_resource_path(path) + if not path_err.is_empty(): + not_found.append("%s (%s)" % [path, path_err]) + continue + if not FileAccess.file_exists(path): + not_found.append("%s (file does not exist)" % path) + continue + efs.update_file(path) + if _is_imported_resource(path): + reimported.append(path) + else: + skipped_non_imported.append(path) + + var data := { + "reimported": reimported, + "skipped_non_imported": skipped_non_imported, + "not_found": not_found, + "reimported_count": reimported.size(), + "skipped_non_imported_count": skipped_non_imported.size(), + "not_found_count": not_found.size(), + "undoable": false, + "reason": "Reimport is a file system operation", + } + ## Only when it applies: a hint on every call would cost tokens on the + ## all-assets path this op is actually for. + if not skipped_non_imported.is_empty(): + data["skipped_non_imported_hint"] = ( + "%d path(s) are not imported resources. Their editor filesystem entry was " + + "refreshed, but no import ran — a success here is not evidence that a " + + "script parsed or that diagnostics were produced. Use script_patch/" + + "script_create for GDScript diagnostics, or filesystem_manage(op=\"scan\") " + + "for an asset the editor has not imported yet." + ) % skipped_non_imported.size() + return {"data": data} + + +## #778: `update_file()` registers a path with the resource pipeline; it only +## runs an *import* for files that have one. Scripts, scenes and hand-written +## `.tres` are not imported resources, so listing them under `reimported` reads +## as proof that a parse or import ran when nothing did. +## +## The `.import` sidecar is the editor's own record that a path goes through +## the import pipeline, so it decides the split. An extension allow-list was +## rejected: importers come and go with plugins, so the list would drift out of +## agreement with the editor it claims to describe. +## +## Known edge: an asset the editor has never imported (just written, no scan +## yet) has no sidecar and reports as non-imported. That is accurate at the +## moment of the call — `update_file()` did not import it either — and the +## hint names `scan` as the way through. +## +## Behaviour is unchanged for every path: `update_file()` still runs on all of +## them, because refreshing an externally-edited `.tscn`/`.tres` is a real use +## of this op. This splits the report, not the work. +static func _is_imported_resource(path: String) -> bool: + if path.ends_with(IMPORT_SIDECAR_SUFFIX): + return false ## The sidecar itself is not an imported resource. + return FileAccess.file_exists(path + IMPORT_SIDECAR_SUFFIX) + + +## Force a full EditorFileSystem scan and wait for it to settle. This is the +## headless equivalent of the editor regaining window focus: `update_file()` +## (used by write_file/reimport/script_create) registers a single file with the +## resource pipeline but does NOT rebuild the global `class_name` table, so a +## freshly-created `class_name MyThing extends Resource` stays invisible to +## `ClassDB`/`ProjectSettings.get_global_class_list()` until a scan runs. Agents +## driving the editor without focus call this once after a batch of script +## creates to make new types instantiable/referenceable. See issue #83. +func scan_filesystem(params: Dictionary) -> Dictionary: + var efs := EditorInterface.get_resource_filesystem() + if efs == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "EditorFileSystem not available", false) + + var request_id: String = params.get("_request_id", "") + # Async path: a scan can't be awaited on the calling frame without freezing + # the editor, so hand control back to the dispatcher (DEFERRED_RESPONSE) and + # push the real reply from a static coroutine once the scan settles — by + # which point new class_names are registered. + if _connection != null and not request_id.is_empty(): + _finish_scan_deferred(_connection, request_id, efs) + return McpDispatcher.DEFERRED_RESPONSE + + # Synchronous fallback: batch_execute (no request_id) and unit-test contexts + # (no connection) can't await, so kick a single-flight scan and return + # immediately without the settle confirmation. Respect the latch so we don't + # stack onto a deferred scan; don't set it (there's no coroutine here to + # clear it — the brief is_scanning() window covers the rest). + var already := _scan_in_flight or efs.is_scanning() + if not already: + efs.scan() + return { + "data": { + "scan_completed": false, + "scan_settle": "not_waited", + "was_already_scanning": already, + "global_class_count": ProjectSettings.get_global_class_list().size(), + # Present in both paths for a consistent response shape; the sync + # path doesn't await, so it can't measure a delta. + "global_classes_registered_delta": 0, + "undoable": false, + "reason": "Filesystem scan is an editor operation", + } + } + + +## `static` is load-bearing for the same reason as ScriptHandler's deferred +## finish: the coroutine must outlive the handler RefCounted, which can be freed +## mid-await (e.g. an editor_reload_plugin fired during the scan). Parameterise +## everything; reference no instance state. +static func _finish_scan_deferred( + connection: McpConnection, + request_id: String, + efs: EditorFileSystem, +) -> void: + if not is_instance_valid(connection): + return + var tree := connection.get_tree() + if tree == null: + return + var classes_before := ProjectSettings.get_global_class_list().size() + # Single-flight via the shared `_scan_in_flight` latch (NOT is_scanning(), + # which lags scan() by a frame or two — see the latch declaration). Only the + # request that sets the latch calls scan(); concurrent requests coalesce and + # just await the running scan. This is what actually prevents the stacked + # scan() SIGABRT (dsarno/godot#6), even within the start-grace window. + var was_already_scanning := _scan_in_flight or efs.is_scanning() + var we_started := not was_already_scanning + if we_started: + _scan_in_flight = true + efs.scan() + # Hand back a frame so _dispatch() registers this request as deferred before + # the coroutine can push a reply (mirrors McpResourceIO.finish_text_write_deferred). + await tree.process_frame + var deadline_ms := Time.get_ticks_msec() + _SCAN_SETTLE_MAX_MSEC + var start_grace_ms := Time.get_ticks_msec() + _SCAN_START_GRACE_MSEC + var saw_scanning := efs.is_scanning() + while Time.get_ticks_msec() < deadline_ms: + if efs.is_scanning(): + saw_scanning = true + elif saw_scanning or Time.get_ticks_msec() > start_grace_ms: + # Either the scan ran and finished, or it never flipped is_scanning() + # within the grace window (a no-op scan because nothing changed). + break + await tree.process_frame + # Clear the latch in all paths (no try/finally in GDScript): do it before the + # is_instance_valid early-return so a freed connection can't orphan it. + if we_started: + _scan_in_flight = false + if not is_instance_valid(connection): + return + var completed := not efs.is_scanning() + var classes_after := ProjectSettings.get_global_class_list().size() + connection.send_deferred_response(request_id, { + "data": { + "scan_completed": completed, + "scan_settle": "settled" if completed else "timeout", + "was_already_scanning": was_already_scanning, + "global_class_count": classes_after, + "global_classes_registered_delta": classes_after - classes_before, + "undoable": false, + "reason": "Filesystem scan is an editor operation", + } + }) diff --git a/addons/godot_ai/handlers/filesystem_handler.gd.uid b/addons/godot_ai/handlers/filesystem_handler.gd.uid new file mode 100644 index 0000000..94135a4 --- /dev/null +++ b/addons/godot_ai/handlers/filesystem_handler.gd.uid @@ -0,0 +1 @@ +uid://c7ovtpdiumtju diff --git a/addons/godot_ai/handlers/gridmap_handler.gd b/addons/godot_ai/handlers/gridmap_handler.gd new file mode 100644 index 0000000..75016e4 --- /dev/null +++ b/addons/godot_ai/handlers/gridmap_handler.gd @@ -0,0 +1,192 @@ +@tool +extends RefCounted + +## GridMap authoring — set, fill, clear, and read 3D cells plus mesh-library +## items directly in the editor scene with full undo/redo support. +## +## All ops target GridMap nodes in the currently edited scene by +## scene-relative path (e.g. "/Main/Terrain"). All write ops are undoable +## via EditorUndoRedoManager. + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const MAX_FILL_CELLS := 4096 + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +## Set a single cell item. item = -1 erases the cell. +## params: {path, item, map_x, map_y, map_z, orientation=0} +## Returns: {map_x, map_y, map_z, item, orientation, undoable} +func set_item(params: Dictionary) -> Dictionary: + var gm := _resolve_gridmap(params) + if gm.has("error"): return gm + var node: GridMap = gm.node + var pos := Vector3i(int(params.get("map_x", 0)), int(params.get("map_y", 0)), int(params.get("map_z", 0))) + var item := int(params.get("item", 0)) + var orientation := int(params.get("orientation", 0)) + if orientation < 0 or orientation > 24: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "orientation must be in 0..24 (GridMap baked rotations), got %d" % orientation) + var prev := _capture_cell_state(node, pos) + _undo_redo.create_action("MCP: GridMap set_item") + _undo_redo.add_do_method(node, "set_cell_item", pos, item, orientation) + _undo_redo.add_undo_method(self, "_restore_cell_state", node, pos, prev) + _undo_redo.commit_action() + return {"data": {"map_x": pos.x, "map_y": pos.y, "map_z": pos.z, + "item": item, "orientation": orientation, "undoable": true}} + + +## Fill a box region with one item in a single undo action. +## params: {path, item, rect_x, rect_y, rect_z, rect_w, rect_h, rect_d, orientation=0} +## Returns: {cells_filled, rect: {x, y, z, w, h, d}} +func fill(params: Dictionary) -> Dictionary: + var gm := _resolve_gridmap(params) + if gm.has("error"): return gm + var node: GridMap = gm.node + var item := int(params.get("item", 0)) + var orientation := int(params.get("orientation", 0)) + if orientation < 0 or orientation > 24: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "orientation must be in 0..24 (GridMap baked rotations), got %d" % orientation) + var rx := int(params.get("rect_x", 0)); var ry := int(params.get("rect_y", 0)); var rz := int(params.get("rect_z", 0)) + var rw := int(params.get("rect_w", 1)); var rh := int(params.get("rect_h", 1)); var rd := int(params.get("rect_d", 1)) + if rw <= 0 or rh <= 0 or rd <= 0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "rect_w, rect_h and rect_d must be > 0 (got %d x %d x %d)" % [rw, rh, rd]) + var cell_count := rw * rh * rd + if cell_count > MAX_FILL_CELLS: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Region too large: %d cells exceeds max %d" % [cell_count, MAX_FILL_CELLS]) + var snapshot: Array[Dictionary] = [] + for x in range(rx, rx + rw): + for y in range(ry, ry + rh): + for z in range(rz, rz + rd): + var pos := Vector3i(x, y, z) + snapshot.append({"pos": pos, "state": _capture_cell_state(node, pos)}) + _undo_redo.create_action("MCP: GridMap fill %dx%dx%d" % [rw, rh, rd]) + ## First callback targets the node so the action lands in the scene undo + ## history (first-target routing); _apply_fill batches the rest of the + ## region into a single history entry instead of one per cell. + _undo_redo.add_do_method(node, "set_cell_item", snapshot[0].pos, item, orientation) + _undo_redo.add_do_method(self, "_apply_fill", node, snapshot, item, orientation) + _undo_redo.add_undo_method(self, "_restore_rect_snapshot", node, snapshot) + _undo_redo.commit_action() + return {"data": {"cells_filled": snapshot.size(), + "rect": {"x": rx, "y": ry, "z": rz, "w": rw, "h": rh, "d": rd}, "undoable": true}} + + +## Remove all cells from the GridMap. +## params: {path} +## Returns: {cleared: true} +func clear_layer(params: Dictionary) -> Dictionary: + var gm := _resolve_gridmap(params) + if gm.has("error"): return gm + var node: GridMap = gm.node + var used := node.get_used_cells() + if used.size() > MAX_FILL_CELLS: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "GridMap has %d cells, exceeds max %d for undoable clear" + % [used.size(), MAX_FILL_CELLS]) + var snapshot := _capture_used_cells_snapshot(node) + _undo_redo.create_action("MCP: GridMap clear") + _undo_redo.add_do_method(node, "clear") + _undo_redo.add_undo_method(self, "_restore_cells_snapshot", node, snapshot) + _undo_redo.commit_action() + return {"data": {"cleared": true, "undoable": true}} + + +## Return all used cell coordinates. +## params: {path} +## Returns: {cells: [{x, y, z}, ...], count: int} +func get_used_cells(params: Dictionary) -> Dictionary: + var gm := _resolve_gridmap(params) + if gm.has("error"): return gm + var node: GridMap = gm.node + var result: Array = [] + for c in node.get_used_cells(): + result.append({"x": c.x, "y": c.y, "z": c.z}) + return {"data": {"cells": result, "count": result.size()}} + + +## List the items available in the GridMap's MeshLibrary, so agents can +## discover item ids and names before placing cells (the 3D analogue of +## tileset atlas inspection). +## params: {path} +## Returns: {library: res:// path or "", items: [{item, name, mesh}...], count} +func list_library_items(params: Dictionary) -> Dictionary: + var gm := _resolve_gridmap(params) + if gm.has("error"): return gm + var node: GridMap = gm.node + var library: MeshLibrary = node.mesh_library + if library == null: + return {"data": {"library": "", "items": [], "count": 0}} + var items: Array = [] + var ids := library.get_item_list() + ids.sort() + for item in ids: + var mesh: Mesh = library.get_item_mesh(item) + var mesh_path := mesh.resource_path if mesh != null else "" + items.append({ + "item": item, + "name": library.get_item_name(item), + "mesh": mesh_path, + }) + return {"data": {"library": library.resource_path, "items": items, "count": items.size()}} + + +## Resolve a GridMap node from params["path"] in the currently edited +## scene. Returns {"node": GridMap} on success, or an error dict. +func _resolve_gridmap(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var scene_file: String = params.get("scene_file", "") + var resolved := McpNodeValidator.resolve_or_error(path, "path", scene_file) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + if not node is GridMap: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "Node is not a GridMap: %s" % path) + return {"node": node} + + +func _capture_cell_state(node: GridMap, pos: Vector3i) -> Dictionary: + var item := node.get_cell_item(pos) + if item == -1: + return {"has_item": false} + return {"has_item": true, "item": item, "orientation": node.get_cell_item_orientation(pos)} + + +func _capture_used_cells_snapshot(node: GridMap) -> Array[Dictionary]: + var snapshot: Array[Dictionary] = [] + for pos in node.get_used_cells(): + snapshot.append({"pos": pos, "state": _capture_cell_state(node, pos)}) + return snapshot + + +func _restore_cells_snapshot(node: GridMap, snapshot: Array[Dictionary]) -> void: + node.clear() + for entry in snapshot: + _restore_cell_state(node, entry.pos, entry.state) + + +## Batched do-method for fill: one undo-history entry applies the whole +## region instead of one entry per cell. +func _apply_fill(node: GridMap, snapshot: Array[Dictionary], item: int, orientation: int) -> void: + for entry in snapshot: + node.set_cell_item(entry.pos, item, orientation) + + +func _restore_rect_snapshot(node: GridMap, snapshot: Array[Dictionary]) -> void: + for entry in snapshot: + _restore_cell_state(node, entry.pos, entry.state) + + +func _restore_cell_state(node: GridMap, pos: Vector3i, state: Dictionary) -> void: + if not state.get("has_item", false): + node.set_cell_item(pos, -1) + return + node.set_cell_item(pos, int(state.get("item", 0)), int(state.get("orientation", 0))) diff --git a/addons/godot_ai/handlers/gridmap_handler.gd.uid b/addons/godot_ai/handlers/gridmap_handler.gd.uid new file mode 100644 index 0000000..35bb1d0 --- /dev/null +++ b/addons/godot_ai/handlers/gridmap_handler.gd.uid @@ -0,0 +1 @@ +uid://cdv1yrjeyo5es diff --git a/addons/godot_ai/handlers/input_handler.gd b/addons/godot_ai/handlers/input_handler.gd new file mode 100644 index 0000000..78ddd22 --- /dev/null +++ b/addons/godot_ai/handlers/input_handler.gd @@ -0,0 +1,462 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles input action listing, creation, removal, and event binding. +## Actions are persisted via ProjectSettings so they survive editor restarts. + + +func list_actions(params: Dictionary) -> Dictionary: + var include_builtin: bool = params.get("include_builtin", false) + ## Authoritative source for user-authored actions is the ``[input]`` + ## section of ``project.godot``. ``ProjectSettings.has_setting`` is not + ## reliable here because Godot registers ``ui_*`` defaults via + ## ``GLOBAL_DEF_BASIC``, which makes ``has_setting`` return true for + ## them. Reading the file via ``ConfigFile`` distinguishes the user's + ## entries from engine-registered defaults regardless of namespace. + ## See #213. + var user_authored := _read_user_authored_actions() + var actions: Array[Dictionary] = [] + var seen := {} + for action_name in InputMap.get_actions(): + var name_str := str(action_name) + var is_user_action := user_authored.has(name_str) + if not include_builtin and not is_user_action: + continue + seen[name_str] = true + var events: Array[Dictionary] = [] + for event in InputMap.action_get_events(action_name): + events.append(_serialize_event(event)) + actions.append({ + "name": name_str, + "events": events, + "event_count": events.size(), + "is_builtin": not is_user_action, + "loaded_in_input_map": true, + }) + for action_name in user_authored.keys(): + var name_str := str(action_name) + if seen.has(name_str): + continue + var setting: Dictionary = user_authored.get(name_str, {}) + var events: Array[Dictionary] = [] + for event in setting.get("events", []): + if event is InputEvent: + events.append(_serialize_event(event)) + else: + events.append({"type": type_string(typeof(event)), "string": str(event)}) + actions.append({ + "name": name_str, + "events": events, + "event_count": events.size(), + "is_builtin": false, + "loaded_in_input_map": false, + }) + return {"data": {"actions": actions, "count": actions.size()}} + + +func _read_user_authored_actions() -> Dictionary: + var cfg := ConfigFile.new() + if cfg.load("res://project.godot") != OK: + return {} + if not cfg.has_section("input"): + return {} + var result: Dictionary = {} + for key in cfg.get_section_keys("input"): + var value = cfg.get_value("input", key, {}) + result[key] = value if value is Dictionary else {} + return result + + +func add_action(params: Dictionary) -> Dictionary: + var action: String = params.get("action", "") + var deadzone: float = params.get("deadzone", 0.5) + + if action.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: action") + + var deadzone_error := _validate_deadzone(deadzone) + if deadzone_error.has("error"): + return deadzone_error + + if InputMap.has_action(action): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Action '%s' already exists" % action) + + InputMap.add_action(action, deadzone) + + var key := "input/%s" % action + ProjectSettings.set_setting(key, { + "deadzone": deadzone, + "events": [], + }) + var err := ProjectSettings.save() + if err != OK: + InputMap.erase_action(action) + ProjectSettings.clear(key) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Failed to save project settings while adding action '%s': %s (error %d)" % [action, error_string(err), err]) + + return { + "data": { + "action": action, + "deadzone": deadzone, + "undoable": false, + "reason": "Input actions are saved to project.godot", + } + } + + +func ensure_action(params: Dictionary) -> Dictionary: + var action: String = params.get("action", "") + var deadzone: float = params.get("deadzone", 0.5) + + if action.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: action") + + var deadzone_error := _validate_deadzone(deadzone) + if deadzone_error.has("error"): + return deadzone_error + + var result := _ensure_action_state(action, deadzone) + if result.has("error"): + return result + return {"data": result} + + +func remove_action(params: Dictionary) -> Dictionary: + var action: String = params.get("action", "") + if action.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: action") + + var key := "input/%s" % action + var was_loaded := InputMap.has_action(action) + var old_setting = ProjectSettings.get_setting(key) if ProjectSettings.has_setting(key) else null + + ## An action can live in the editor process's InputMap, in project.godot, + ## or both. Actions persisted by a previous editor session exist only on + ## disk (`loaded_in_input_map: false` in list_actions) — those must still + ## be removable. #632 + if not was_loaded and old_setting == null: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Action '%s' not found" % action) + + if was_loaded: + InputMap.erase_action(action) + + if old_setting != null: + ProjectSettings.clear(key) + var err := ProjectSettings.save() + if err != OK: + if was_loaded: + var dz: float = old_setting.get("deadzone", 0.5) if old_setting is Dictionary else 0.5 + InputMap.add_action(action, dz) + if old_setting is Dictionary: + for ev in old_setting.get("events", []): + if ev is InputEvent: + InputMap.action_add_event(action, ev) + ProjectSettings.set_setting(key, old_setting) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Failed to save project settings while removing action '%s': %s (error %d)" % [action, error_string(err), err]) + + return { + "data": { + "action": action, + "removed": true, + "was_loaded": was_loaded, + "undoable": false, + "reason": "Input actions are saved to project.godot", + } + } + + +func bind_event(params: Dictionary) -> Dictionary: + var action: String = params.get("action", "") + var event_type: String = params.get("event_type", "") + + if action.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: action") + if event_type.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: event_type") + + if not InputMap.has_action(action): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Action '%s' not found. Call input_map_manage(op='add_action', params={action: '%s'}) first." % [action, action]) + + var event_or_error = _create_event(event_type, params) + if event_or_error is Dictionary: + return event_or_error + var event: InputEvent = event_or_error + + InputMap.action_add_event(action, event) + + var err := _save_action_events(action) + if err != OK: + InputMap.action_erase_event(action, event) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Failed to save project settings while binding event to action '%s': %s (error %d)" % [action, error_string(err), err]) + + return { + "data": { + "action": action, + "event": _serialize_event(event), + "undoable": false, + "reason": "Input bindings are saved to project.godot", + } + } + + +func ensure_binding(params: Dictionary) -> Dictionary: + var action: String = params.get("action", "") + var event_type: String = params.get("event_type", "") + var deadzone: float = params.get("deadzone", 0.5) + + if action.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: action") + if event_type.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: event_type") + + var deadzone_error := _validate_deadzone(deadzone) + if deadzone_error.has("error"): + return deadzone_error + + var event_or_error = _create_event(event_type, params) + if event_or_error is Dictionary: + return event_or_error + var event: InputEvent = event_or_error + + var ensured := _ensure_action_state(action, deadzone) + if ensured.has("error"): + return ensured + + for existing in InputMap.action_get_events(action): + if _events_match(existing, event): + return { + "data": { + "action": action, + "event": _serialize_event(existing), + "already_bound": true, + "action_created": ensured.get("created", false), + "undoable": false, + "reason": "Input binding already exists", + } + } + + InputMap.action_add_event(action, event) + var err := _save_action_events(action) + if err != OK: + InputMap.action_erase_event(action, event) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Failed to save project settings while binding event to action '%s': %s (error %d)" % [action, error_string(err), err]) + + return { + "data": { + "action": action, + "event": _serialize_event(event), + "already_bound": false, + "action_created": ensured.get("created", false), + "undoable": false, + "reason": "Input bindings are saved to project.godot", + } + } + + +func _validate_deadzone(deadzone: float) -> Dictionary: + if deadzone < 0.0 or deadzone > 1.0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "deadzone must be in [0.0, 1.0] (got %s). Typical values are 0.2-0.5; default is 0.5." % deadzone) + return {} + + +func _ensure_action_state(action: String, deadzone: float) -> Dictionary: + var key := "input/%s" % action + var user_authored := _read_user_authored_actions() + var existed_in_input_map := InputMap.has_action(action) + var existed_in_project := user_authored.has(action) or ProjectSettings.has_setting(key) + var old_setting = user_authored.get(action, null) if user_authored.has(action) else null + if old_setting == null and ProjectSettings.has_setting(key): + old_setting = ProjectSettings.get_setting(key) + + if not existed_in_input_map: + var dz := deadzone + if old_setting is Dictionary: + dz = float(old_setting.get("deadzone", deadzone)) + InputMap.add_action(action, dz) + if old_setting is Dictionary: + for ev in old_setting.get("events", []): + if ev is InputEvent: + InputMap.action_add_event(action, ev) + + if not existed_in_project: + var err := _save_action_events(action) + if err != OK: + if not existed_in_input_map: + InputMap.erase_action(action) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, + "Failed to save project settings while ensuring action '%s': %s (error %d)" % [action, error_string(err), err]) + + var stored_deadzone := deadzone + if ProjectSettings.has_setting(key): + var stored = ProjectSettings.get_setting(key) + if stored is Dictionary: + stored_deadzone = float(stored.get("deadzone", deadzone)) + return { + "action": action, + "deadzone": stored_deadzone, + "created": not existed_in_input_map and not existed_in_project, + "already_exists": existed_in_input_map or existed_in_project, + "loaded_in_input_map": true, + "persisted": true, + "undoable": false, + "reason": "Input actions are saved to project.godot", + } + + +## Returns an InputEvent on success, or a Dictionary error on failure. +## Caller must check ``result is Dictionary`` before treating it as an event. +func _create_event(event_type: String, params: Dictionary): + match event_type: + "key": + var ev := InputEventKey.new() + var keycode_str: String = params.get("keycode", "") + if keycode_str.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, + "event_type='key' requires keycode (e.g. 'Space', 'A', 'Enter', 'Escape', 'F1').") + ev.keycode = OS.find_keycode_from_string(keycode_str) + if ev.keycode == KEY_NONE: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid keycode '%s'. Use Godot keycode names like 'A', 'Space', 'Enter', 'Escape', 'F1', 'Left', 'Right'." % keycode_str) + ev.ctrl_pressed = params.get("ctrl", false) + ev.alt_pressed = params.get("alt", false) + ev.shift_pressed = params.get("shift", false) + ev.meta_pressed = params.get("meta", false) + ev.device = -1 + return ev + "mouse_button": + if not params.has("button"): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, + "event_type='mouse_button' requires button (1=left, 2=right, 3=middle, 4=wheel up, 5=wheel down).") + var button: int = int(params.get("button", 0)) + if button <= 0: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "mouse_button button must be > 0 (got %d). Use 1=left, 2=right, 3=middle, 4=wheel up, 5=wheel down." % button) + var ev := InputEventMouseButton.new() + ev.button_index = button + ev.device = -1 + return ev + "joy_button": + if not params.has("button"): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, + "event_type='joy_button' requires button (JoyButton index, e.g. 0=A/Cross, 1=B/Circle).") + var ev := InputEventJoypadButton.new() + ev.button_index = int(params.get("button", 0)) + return ev + "joy_axis": + var axis_param = params.get("axis", null) + if axis_param == null: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, + "event_type='joy_axis' requires axis (JoyAxis index, e.g. 0=left stick X, 1=left stick Y).") + var axis: int + match typeof(axis_param): + TYPE_INT: + axis = axis_param + TYPE_FLOAT: + if axis_param != floor(axis_param): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "joy_axis axis must be an integer JoyAxis index (got %s)." % str(axis_param)) + axis = int(axis_param) + TYPE_STRING: + var axis_text := str(axis_param) + if not axis_text.is_valid_int(): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "joy_axis axis must be an integer JoyAxis index (got '%s')." % axis_text) + axis = int(axis_text) + _: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "joy_axis axis must be an integer JoyAxis index (got %s)." % type_string(typeof(axis_param))) + var ev := InputEventJoypadMotion.new() + ev.axis = axis + ev.axis_value = float(params.get("axis_value", 1.0)) + return ev + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Unsupported event_type: '%s'. Use 'key', 'mouse_button', 'joy_button', or 'joy_axis'." % event_type) + + +func _serialize_event(event: InputEvent) -> Dictionary: + if event is InputEventKey: + return { + "type": "key", + "keycode": OS.get_keycode_string(event.keycode), + "physical_keycode": OS.get_keycode_string(event.physical_keycode), + "ctrl": event.ctrl_pressed, + "alt": event.alt_pressed, + "shift": event.shift_pressed, + "meta": event.meta_pressed, + } + if event is InputEventMouseButton: + return { + "type": "mouse_button", + "button": event.button_index, + } + if event is InputEventJoypadButton: + return { + "type": "joy_button", + "button": event.button_index, + } + if event is InputEventJoypadMotion: + return { + "type": "joy_axis", + "axis": event.axis, + "axis_value": event.axis_value, + } + return {"type": event.get_class(), "string": str(event)} + + +func _events_match(a: InputEvent, b: InputEvent) -> bool: + if a is InputEventKey and b is InputEventKey: + return _key_events_match(a as InputEventKey, b as InputEventKey) + return _serialize_event(a) == _serialize_event(b) + + +func _key_events_match(a: InputEventKey, b: InputEventKey) -> bool: + if a.ctrl_pressed != b.ctrl_pressed: + return false + if a.alt_pressed != b.alt_pressed: + return false + if a.shift_pressed != b.shift_pressed: + return false + if a.meta_pressed != b.meta_pressed: + return false + var a_codes := [a.keycode, a.physical_keycode] + var b_codes := [b.keycode, b.physical_keycode] + for a_code in a_codes: + if int(a_code) == KEY_NONE: + continue + for b_code in b_codes: + if int(b_code) != KEY_NONE and int(a_code) == int(b_code): + return true + return false + + +func _save_action_events(action: String) -> int: + var events: Array = [] + for event in InputMap.action_get_events(action): + events.append(event) + var key := "input/%s" % action + var had_setting := ProjectSettings.has_setting(key) + var old_setting = ProjectSettings.get_setting(key) if had_setting else null + var deadzone: float = 0.5 + if old_setting is Dictionary: + deadzone = old_setting.get("deadzone", 0.5) + elif InputMap.has_action(action): + deadzone = InputMap.action_get_deadzone(action) + ProjectSettings.set_setting(key, { + "deadzone": deadzone, + "events": events, + }) + var err := ProjectSettings.save() + if err != OK: + if had_setting: + ProjectSettings.set_setting(key, old_setting) + else: + ProjectSettings.clear(key) + return err diff --git a/addons/godot_ai/handlers/input_handler.gd.uid b/addons/godot_ai/handlers/input_handler.gd.uid new file mode 100644 index 0000000..7d509f4 --- /dev/null +++ b/addons/godot_ai/handlers/input_handler.gd.uid @@ -0,0 +1 @@ +uid://buk68rbwssqwp diff --git a/addons/godot_ai/handlers/material_handler.gd b/addons/godot_ai/handlers/material_handler.gd new file mode 100644 index 0000000..d8a4981 --- /dev/null +++ b/addons/godot_ai/handlers/material_handler.gd @@ -0,0 +1,809 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles Material authoring: creating .tres files, setting BaseMaterial3D +## properties / shader uniforms, assigning to nodes, high-level presets. +## +## File-resource lifecycle mirrors ThemeHandler (create/load/mutate/save). +## Undo pattern mirrors AnimationHandler (single create_action bundles +## every dependency spawn). + +const MaterialValues := preload("res://addons/godot_ai/handlers/material_values.gd") +const MaterialPresets := preload("res://addons/godot_ai/handlers/material_presets.gd") + +const _TYPE_TO_CLASS := { + "standard": "StandardMaterial3D", + "orm": "ORMMaterial3D", + "canvas_item": "CanvasItemMaterial", + "shader": "ShaderMaterial", +} + +const _SUPPORTED_SUFFIXES := [".tres", ".material", ".res"] + + +var _undo_redo: EditorUndoRedoManager +var _connection: McpConnection + + +func _init(undo_redo: EditorUndoRedoManager, connection: McpConnection = null) -> void: + _undo_redo = undo_redo + _connection = connection + + +# ============================================================================ +# material_create +# ============================================================================ + +func create_material(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var type_str: String = params.get("type", "standard") + var shader_path: String = params.get("shader_path", "") + var overwrite: bool = params.get("overwrite", false) + + var err := _validate_material_path(path, "path", true) + if err != null: + return err + + if not _TYPE_TO_CLASS.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid material type '%s'. Valid: %s" % [type_str, ", ".join(_TYPE_TO_CLASS.keys())] + ) + + var existed_before := FileAccess.file_exists(path) + if existed_before and not overwrite: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Material already exists at %s (pass overwrite=true to replace)" % path + ) + + var mat := _instantiate_material(type_str) + if mat == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate material") + + if type_str == "shader": + if shader_path.is_empty(): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "ShaderMaterial requires shader_path (res:// / uid:// / user:// path to a .gdshader)" + ) + var shader_path_err = McpPathValidator.loadable_error(shader_path, "shader_path") + if shader_path_err != null: + return shader_path_err + if not ResourceLoader.exists(shader_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Shader not found: %s" % shader_path) + var shader_res := ResourceLoader.load(shader_path) + if not (shader_res is Shader): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Shader" % shader_path) + (mat as ShaderMaterial).shader = shader_res + + var dir_path := path.get_base_dir() + var mkdir_err := DirAccess.make_dir_recursive_absolute(dir_path) + if mkdir_err != OK and mkdir_err != ERR_ALREADY_EXISTS: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to create directory: %s (error %d)" % [dir_path, mkdir_err] + ) + + var save_err := McpResourceIO.guarded_save(mat, path, _connection) + if save_err != OK: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to save material to %s (error %d)" % [path, save_err] + ) + + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(path) + + return { + "data": { + "path": path, + "type": type_str, + "class": mat.get_class(), + "shader_path": shader_path, + "overwritten": existed_before, + "undoable": false, + "reason": "File creation is persistent; delete the file manually to revert", + } + } + + +# ============================================================================ +# material_set_param +# ============================================================================ + +func set_param(params: Dictionary) -> Dictionary: + var load_result := _load_material_from_path(params.get("path", ""), true) + if load_result.has("error"): + return load_result + var mat: Material = load_result.material + var mat_path: String = load_result.path + + var property: String = params.get("param", "") + if property.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: param") + + if not ("value" in params): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: value") + + var raw_value = params.get("value") + + # Probe the property. We allow any property present in get_property_list, + # plus `shader` on ShaderMaterial. + var prop_type: int = TYPE_NIL + var property_exists := false + for prop in mat.get_property_list(): + if prop.name == property: + property_exists = true + prop_type = prop.get("type", TYPE_NIL) + break + if not property_exists: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + McpPropertyErrors.build_message(mat, property) + ) + + var coerced := MaterialValues.coerce_material_value(property, raw_value, prop_type) + if not coerced.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerced.error)) + var new_value = coerced.value + + var old_value = mat.get(property) + + _undo_redo.create_action("MCP: Set material %s.%s" % [mat_path.get_file(), property]) + _undo_redo.add_do_method(self, "_apply_param", mat_path, property, new_value, false) + _undo_redo.add_undo_method(self, "_apply_param", mat_path, property, old_value, false) + _undo_redo.commit_action() + + return { + "data": { + "path": mat_path, + "property": property, + "value": MaterialValues.serialize_value(new_value), + "previous_value": MaterialValues.serialize_value(old_value), + "undoable": true, + } + } + + +# ============================================================================ +# material_set_shader_param +# ============================================================================ + +func set_shader_param(params: Dictionary) -> Dictionary: + var load_result := _load_material_from_path(params.get("path", ""), true) + if load_result.has("error"): + return load_result + var mat: Material = load_result.material + var mat_path: String = load_result.path + + if not (mat is ShaderMaterial): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Material at %s is %s, not ShaderMaterial" % [mat_path, mat.get_class()] + ) + var shader_mat := mat as ShaderMaterial + if shader_mat.shader == null: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "ShaderMaterial at %s has no shader assigned" % mat_path + ) + + var param_name: String = params.get("param", "") + if param_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: param") + + if not ("value" in params): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: value") + + # Verify the uniform exists in the shader. + var uniform_type := _shader_uniform_type(shader_mat.shader, param_name) + if uniform_type == TYPE_NIL: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Shader uniform '%s' not declared on shader at %s" % [param_name, shader_mat.shader.resource_path] + ) + + var raw_value = params.get("value") + var coerced := MaterialValues.coerce_material_value(param_name, raw_value, uniform_type) + if not coerced.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerced.error)) + var new_value = coerced.value + + var old_value = shader_mat.get_shader_parameter(param_name) + + _undo_redo.create_action("MCP: Set shader param %s.%s" % [mat_path.get_file(), param_name]) + _undo_redo.add_do_method(self, "_apply_shader_param", mat_path, param_name, new_value) + _undo_redo.add_undo_method(self, "_apply_shader_param", mat_path, param_name, old_value) + _undo_redo.commit_action() + + return { + "data": { + "path": mat_path, + "param": param_name, + "value": MaterialValues.serialize_value(new_value), + "previous_value": MaterialValues.serialize_value(old_value), + "undoable": true, + } + } + + +# ============================================================================ +# material_get +# ============================================================================ + +func get_material(params: Dictionary) -> Dictionary: + var load_result := _load_material_from_path(params.get("path", "")) + if load_result.has("error"): + return load_result + var mat: Material = load_result.material + var mat_path: String = load_result.path + + var properties: Array[Dictionary] = [] + for prop in mat.get_property_list(): + var usage: int = prop.get("usage", 0) + if not (usage & PROPERTY_USAGE_EDITOR): + continue + var name: String = prop.name + if name.begins_with("shader_parameter/"): + continue # handled below + var value = mat.get(name) + if value == null and prop.type != TYPE_NIL: + continue + properties.append({ + "name": name, + "type": type_string(prop.type), + "value": MaterialValues.serialize_value(value), + }) + + var shader_params: Array[Dictionary] = [] + if mat is ShaderMaterial: + var shader_mat := mat as ShaderMaterial + if shader_mat.shader != null: + for u in shader_mat.shader.get_shader_uniform_list(): + var u_name: String = u.get("name", "") + if u_name.is_empty(): + continue + shader_params.append({ + "name": u_name, + "type": type_string(u.get("type", TYPE_NIL)), + "value": MaterialValues.serialize_value(shader_mat.get_shader_parameter(u_name)), + }) + + var reverse_type_map := _reverse_type_map() + + var shader_path_str := "" + if mat is ShaderMaterial: + var sm := mat as ShaderMaterial + if sm.shader != null: + shader_path_str = sm.shader.resource_path + + return { + "data": { + "path": mat_path, + "class": mat.get_class(), + "type": reverse_type_map.get(mat.get_class(), ""), + "properties": properties, + "property_count": properties.size(), + "shader_parameters": shader_params, + "shader_path": shader_path_str, + } + } + + +# ============================================================================ +# material_list +# ============================================================================ + +func list_materials(params: Dictionary) -> Dictionary: + var root: String = params.get("root", "res://") + var type_filter: String = params.get("type", "") + + var root_err = McpPathValidator.path_error(root, "root") + if root_err != null: + return root_err + + var efs := EditorInterface.get_resource_filesystem() + if efs == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "EditorFileSystem not available", false) + + var results: Array[Dictionary] = [] + var start_dir := efs.get_filesystem_path(root) + if start_dir == null: + start_dir = efs.get_filesystem() + _scan_materials(start_dir, type_filter, root, results) + + return {"data": {"materials": results, "count": results.size()}} + + +func _scan_materials(dir: EditorFileSystemDirectory, type_filter: String, root: String, out: Array[Dictionary]) -> void: + if dir == null: + return + for i in dir.get_file_count(): + var file_path := dir.get_file_path(i) + if not file_path.begins_with(root): + continue + var file_type := dir.get_file_type(i) + var is_material := file_type == "Material" or ClassDB.is_parent_class(file_type, "Material") + if not is_material: + # Some material variants serialize as specific classes. + if not (file_type in _TYPE_TO_CLASS.values()): + continue + + if not type_filter.is_empty(): + if file_type != type_filter and not ClassDB.is_parent_class(file_type, type_filter): + continue + + out.append({"path": file_path, "class": file_type}) + + for i in dir.get_subdir_count(): + _scan_materials(dir.get_subdir(i), type_filter, root, out) + + +# ============================================================================ +# material_assign +# ============================================================================ + +func assign_material(params: Dictionary) -> Dictionary: + var node_path: String = params.get("node_path", "") + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: node_path") + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + + var slot: String = params.get("slot", "override") + var resource_path: String = params.get("resource_path", "") + var create_if_missing: bool = params.get("create_if_missing", false) + var type_str: String = params.get("type", "standard") + + var slot_result := _resolve_slot_property(node, slot) + if slot_result.has("error"): + return slot_result + var property: String = slot_result.property + + # Load or create the material. + var mat: Material = null + var material_created := false + if not resource_path.is_empty(): + var rpath_err = McpPathValidator.loadable_error(resource_path, "resource_path") + if rpath_err != null: + return rpath_err + if not ResourceLoader.exists(resource_path): + if create_if_missing: + # We'd need to create a new file here — refuse; callers should + # use material_create first or omit resource_path to get an + # inline material. + return ErrorCodes.make( + ErrorCodes.RESOURCE_NOT_FOUND, + "Resource not found: %s. Create it first with material_create or omit resource_path for an inline material." % resource_path + ) + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % resource_path) + var loaded := ResourceLoader.load(resource_path) + if not (loaded is Material): + var loaded_class := "null" + if loaded != null: + loaded_class = loaded.get_class() + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Resource at %s is not a Material (got %s)" % [resource_path, loaded_class] + ) + mat = loaded + else: + if not create_if_missing: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Missing resource_path (pass create_if_missing=true to create a new inline material)" + ) + if not _TYPE_TO_CLASS.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid material type '%s'" % type_str + ) + mat = _instantiate_material(type_str) + material_created = true + + var old_value = node.get(property) + + _undo_redo.create_action("MCP: Assign material to %s.%s" % [node.name, property]) + _undo_redo.add_do_property(node, property, mat) + _undo_redo.add_undo_property(node, property, old_value) + if material_created: + _undo_redo.add_do_reference(mat) + _undo_redo.commit_action() + + return { + "data": { + "node_path": node_path, + "property": property, + "slot": slot, + "resource_path": resource_path, + "material_class": mat.get_class(), + "material_created": material_created, + "undoable": true, + } + } + + +# ============================================================================ +# material_apply_to_node +# ============================================================================ + +func apply_to_node(params: Dictionary) -> Dictionary: + var node_path: String = params.get("node_path", "") + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: node_path") + + var type_str: String = params.get("type", "standard") + if not _TYPE_TO_CLASS.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid material type '%s'. Valid: %s" % [type_str, ", ".join(_TYPE_TO_CLASS.keys())] + ) + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + + var slot: String = params.get("slot", "override") + var slot_result := _resolve_slot_property(node, slot) + if slot_result.has("error"): + return slot_result + var property: String = slot_result.property + + var mat := _instantiate_material(type_str) + + var props_to_set: Dictionary = params.get("params", {}) + var applied: Array[String] = [] + for prop_name in props_to_set: + var apply_err := _apply_one_param_on_instance(mat, String(prop_name), props_to_set[prop_name]) + if apply_err != null: + return apply_err + applied.append(String(prop_name)) + + var save_to: String = params.get("save_to", "") + var saved := false + var overwritten := false + if not save_to.is_empty(): + var save_err_validation := _validate_material_path(save_to, "save_to", true) + if save_err_validation != null: + return save_err_validation + # Same clobber guard as create_material/apply_preset: agents reuse + # names like res://materials/metal.tres, and a silent save here + # destroys a hand-authored file that undo can't restore (undo only + # reverts the node's slot assignment, not file contents). See #685. + var existed_before := FileAccess.file_exists(save_to) + if existed_before and not params.get("overwrite", false): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Material already exists at %s (pass overwrite=true to replace)" % save_to + ) + overwritten = existed_before + var dir_path := save_to.get_base_dir() + var mkdir_err := DirAccess.make_dir_recursive_absolute(dir_path) + if mkdir_err != OK and mkdir_err != ERR_ALREADY_EXISTS: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to create directory: %s" % dir_path) + var save_err := McpResourceIO.guarded_save(mat, save_to, _connection) + if save_err != OK: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to save material to %s (error %d)" % [save_to, save_err]) + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(save_to) + # Prefer the on-disk reference (keeps the scene ref small), but fall + # back to the in-memory material if the reload fails — otherwise a null + # would clear the slot and crash mat.get_class() below. + var reloaded := ResourceLoader.load(save_to) + if reloaded != null: + mat = reloaded + saved = true + + var old_value = node.get(property) + + _undo_redo.create_action("MCP: Apply %s material to %s" % [type_str, node.name]) + _undo_redo.add_do_property(node, property, mat) + _undo_redo.add_undo_property(node, property, old_value) + _undo_redo.add_do_reference(mat) + _undo_redo.commit_action() + + return { + "data": { + "node_path": node_path, + "property": property, + "slot": slot, + "type": type_str, + "class": mat.get_class(), + "applied_params": applied, + "material_created": true, + "saved_to": save_to if saved else "", + "overwritten": overwritten, + "undoable": true, + } + } + + +# ============================================================================ +# material_apply_preset +# ============================================================================ + +func apply_preset(params: Dictionary) -> Dictionary: + var preset_name: String = params.get("preset", "") + if preset_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: preset") + + var overrides: Dictionary = params.get("overrides", {}) + var blueprint = MaterialPresets.build(preset_name, overrides) + if blueprint == null: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown preset '%s'. Valid: %s" % [preset_name, ", ".join(MaterialPresets.list())] + ) + + var type_str: String = blueprint.get("type", "standard") + var preset_params: Dictionary = blueprint.get("params", {}) + + var path: String = params.get("path", "") + var node_path: String = params.get("node_path", "") + + if path.is_empty() and node_path.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "Pass at least one of: path (save to disk), node_path (assign to node)" + ) + + # If both path and node_path, save to disk, then assign the saved resource. + # If only path, save to disk. + # If only node_path, inline material via apply_to_node. + + if not node_path.is_empty() and path.is_empty(): + # Inline + var inline_result := apply_to_node({ + "node_path": node_path, + "type": type_str, + "params": preset_params, + "slot": params.get("slot", "override"), + }) + if inline_result.has("data"): + inline_result.data["preset"] = preset_name + inline_result.data["assigned"] = true + inline_result.data["path"] = "" + inline_result.data["saved_to_disk"] = false + inline_result.data["reason"] = "Inline material assigned to node" + return inline_result + + # Save-to-disk path. Validate the path BEFORE the exists/overwrite + # check, matching create_material's order — an invalid path should + # always be reported as invalid, not as an overwrite conflict. + var path_err := _validate_material_path(path, "path", true) + if path_err != null: + return path_err + + var existed_before := FileAccess.file_exists(path) + if existed_before and not params.get("overwrite", false): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Material already exists at %s (pass overwrite=true to replace)" % path + ) + + var mat := _instantiate_material(type_str) + for prop_name in preset_params: + var apply_err := _apply_one_param_on_instance(mat, String(prop_name), preset_params[prop_name]) + if apply_err != null: + return apply_err + + var dir_path := path.get_base_dir() + var mkdir_err := DirAccess.make_dir_recursive_absolute(dir_path) + if mkdir_err != OK and mkdir_err != ERR_ALREADY_EXISTS: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to create directory: %s" % dir_path) + + var save_err := McpResourceIO.guarded_save(mat, path, _connection) + if save_err != OK: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to save material: %s" % path) + + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(path) + + var assigned := false + if not node_path.is_empty(): + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + var slot_result := _resolve_slot_property(node, params.get("slot", "override")) + if slot_result.has("error"): + return slot_result + var property: String = slot_result.property + var saved_mat := ResourceLoader.load(path) + var old_value = node.get(property) + _undo_redo.create_action("MCP: Apply preset %s to %s" % [preset_name, node.name]) + _undo_redo.add_do_property(node, property, saved_mat) + _undo_redo.add_undo_property(node, property, old_value) + _undo_redo.commit_action() + assigned = true + + return { + "data": { + "preset": preset_name, + "type": type_str, + "path": path, + "node_path": node_path, + "material_created": true, + "assigned": assigned, + "saved_to_disk": true, + "undoable": assigned, # assign is undoable; save is not + "reason": "" if assigned else "File save is not undoable", + } + } + + +# ============================================================================ +# Undo-callable: applies a param on the loaded resource and saves. +# ============================================================================ + +func _apply_param(mat_path: String, property: String, value: Variant, _is_shader: bool) -> void: + var mat: Material = ResourceLoader.load(mat_path) + if mat == null: + push_warning("MCP: Failed to load material for undo/redo: %s" % mat_path) + return + mat.set(property, value) + McpResourceIO.guarded_save(mat, mat_path, _connection) + + +func _apply_shader_param(mat_path: String, param_name: String, value: Variant) -> void: + var mat: Material = ResourceLoader.load(mat_path) + if mat == null or not (mat is ShaderMaterial): + push_warning("MCP: Failed to load shader material for undo/redo: %s" % mat_path) + return + (mat as ShaderMaterial).set_shader_parameter(param_name, value) + McpResourceIO.guarded_save(mat, mat_path, _connection) + + +# ============================================================================ +# Helpers +# ============================================================================ + +static func _instantiate_material(type_str: String) -> Material: + match type_str: + "standard": + return StandardMaterial3D.new() + "orm": + return ORMMaterial3D.new() + "canvas_item": + return CanvasItemMaterial.new() + "shader": + return ShaderMaterial.new() + return null + + +static func _reverse_type_map() -> Dictionary: + var out := {} + for k in _TYPE_TO_CLASS: + out[_TYPE_TO_CLASS[k]] = k + return out + + +static func _validate_material_path(path: String, param_name: String, for_write: bool = false) -> Variant: + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: %s" % param_name) + var path_err := McpPathValidator.validate_resource_path(path, for_write) + if not path_err.is_empty(): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "%s: %s" % [param_name, path_err]) + var has_suffix := false + for s in _SUPPORTED_SUFFIXES: + if path.ends_with(s): + has_suffix = true + break + if not has_suffix: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "%s must end with one of %s (got %s)" % [param_name, ", ".join(_SUPPORTED_SUFFIXES), path] + ) + return null + + +func _load_material_from_path(path: String, for_write: bool = false) -> Dictionary: + var err := _validate_material_path(path, "path", for_write) + if err != null: + return err + if not ResourceLoader.exists(path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Material not found: %s" % path) + var res := ResourceLoader.load(path) + if res == null or not (res is Material): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Material" % path) + return {"material": res, "path": path} + + +## Map a slot name to a Godot property name on the given node. +## Returns {property: "..."} or an error dict. +func _resolve_slot_property(node: Node, slot: String) -> Dictionary: + if slot == "override": + if node is MeshInstance3D or node is CSGShape3D: + return {"property": "material_override"} + if node is CanvasItem: + return {"property": "material"} + if node is GPUParticles3D or node is GPUParticles2D or node is CPUParticles3D or node is CPUParticles2D: + return {"property": "material_override"} if node is GeometryInstance3D else {"property": "material"} + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Slot 'override' not supported on %s" % node.get_class() + ) + if slot == "canvas": + if node is CanvasItem: + return {"property": "material"} + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Slot 'canvas' requires a CanvasItem (got %s)" % node.get_class() + ) + if slot == "process": + if node is GPUParticles3D or node is GPUParticles2D: + return {"property": "process_material"} + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Slot 'process' requires a GPUParticles2D/3D (got %s)" % node.get_class() + ) + if slot.begins_with("surface_"): + if not (node is MeshInstance3D): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Slot '%s' requires a MeshInstance3D (got %s)" % [slot, node.get_class()] + ) + var idx_str := slot.substr(len("surface_")) + if not idx_str.is_valid_int(): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Invalid surface slot: %s" % slot) + var idx := int(idx_str) + var mi := node as MeshInstance3D + var surf_count := mi.mesh.get_surface_count() if mi.mesh != null else 0 + if idx < 0 or idx >= surf_count: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Surface index %d out of range (mesh has %d surfaces)" % [idx, surf_count] + ) + return {"property": "surface_material_override/%d" % idx} + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown slot '%s'. Valid: override, canvas, process, surface_N" % slot + ) + + +## Apply one property to an in-memory material instance; returns null on +## success or an error dict on failure. +func _apply_one_param_on_instance(mat: Material, property: String, raw_value: Variant) -> Variant: + var prop_type: int = TYPE_NIL + var property_exists := false + for prop in mat.get_property_list(): + if prop.name == property: + property_exists = true + prop_type = prop.get("type", TYPE_NIL) + break + if not property_exists: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + McpPropertyErrors.build_message(mat, property) + ) + var coerced := MaterialValues.coerce_material_value(property, raw_value, prop_type) + if not coerced.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerced.error)) + mat.set(property, coerced.value) + return null + + +## Inspect a shader to get the Variant type of a uniform. Returns TYPE_NIL if +## the uniform is not declared. +static func _shader_uniform_type(shader: Shader, name: String) -> int: + if shader == null: + return TYPE_NIL + for u in shader.get_shader_uniform_list(): + if u.get("name", "") == name: + return int(u.get("type", TYPE_NIL)) + return TYPE_NIL diff --git a/addons/godot_ai/handlers/material_handler.gd.uid b/addons/godot_ai/handlers/material_handler.gd.uid new file mode 100644 index 0000000..fdf789a --- /dev/null +++ b/addons/godot_ai/handlers/material_handler.gd.uid @@ -0,0 +1 @@ +uid://blh4norn3rjga diff --git a/addons/godot_ai/handlers/material_presets.gd b/addons/godot_ai/handlers/material_presets.gd new file mode 100644 index 0000000..db48036 --- /dev/null +++ b/addons/godot_ai/handlers/material_presets.gd @@ -0,0 +1,92 @@ +@tool +extends RefCounted + +## Curated material preset blueprints. +## +## Each preset returns {type, params}. Handler applies them through the +## normal material build path so they get undo + validation for free. + + +const _PRESETS := { + "metal": { + "type": "orm", + "params": { + "metallic": 1.0, + "roughness": 0.25, + "albedo_color": {"r": 0.85, "g": 0.85, "b": 0.88, "a": 1.0}, + }, + }, + "glass": { + "type": "standard", + "params": { + "transparency": "alpha", + "albedo_color": {"r": 0.9, "g": 0.95, "b": 1.0, "a": 0.3}, + "metallic": 0.0, + "metallic_specular": 0.5, + "roughness": 0.05, + "refraction_enabled": true, + "refraction_scale": 0.05, + }, + }, + "emissive": { + "type": "standard", + "params": { + "emission_enabled": true, + "emission_energy_multiplier": 3.0, + "emission": {"r": 1.0, "g": 1.0, "b": 1.0, "a": 1.0}, + "albedo_color": {"r": 1.0, "g": 1.0, "b": 1.0, "a": 1.0}, + }, + }, + "unlit": { + "type": "standard", + "params": { + "shading_mode": "unshaded", + "albedo_color": {"r": 1.0, "g": 1.0, "b": 1.0, "a": 1.0}, + }, + }, + "matte": { + "type": "standard", + "params": { + "roughness": 1.0, + "metallic": 0.0, + "albedo_color": {"r": 0.7, "g": 0.7, "b": 0.7, "a": 1.0}, + }, + }, + "ceramic": { + "type": "standard", + "params": { + "roughness": 0.4, + "metallic": 0.0, + "clearcoat_enabled": true, + "clearcoat": 0.7, + "clearcoat_roughness": 0.15, + "albedo_color": {"r": 0.95, "g": 0.95, "b": 0.95, "a": 1.0}, + }, + }, +} + + +static func list() -> Array: + return _PRESETS.keys() + + +static func has(preset_name: String) -> bool: + return _PRESETS.has(preset_name) + + +## Returns a deep-copied {type, params} blueprint for the named preset, or +## null if the preset is unknown. Overrides are merged into params. +static func build(preset_name: String, overrides: Dictionary) -> Variant: + if not _PRESETS.has(preset_name): + return null + var entry: Dictionary = _PRESETS[preset_name].duplicate(true) + var params: Dictionary = entry.get("params", {}) + # Allow overrides to change type, too. + if overrides.has("type"): + entry["type"] = overrides["type"] + for key in overrides: + if key == "type": + continue + params[key] = overrides[key] + entry["params"] = params + return entry diff --git a/addons/godot_ai/handlers/material_presets.gd.uid b/addons/godot_ai/handlers/material_presets.gd.uid new file mode 100644 index 0000000..2f46051 --- /dev/null +++ b/addons/godot_ai/handlers/material_presets.gd.uid @@ -0,0 +1 @@ +uid://bnuwye1r8ow7g diff --git a/addons/godot_ai/handlers/material_values.gd b/addons/godot_ai/handlers/material_values.gd new file mode 100644 index 0000000..d6a7f1d --- /dev/null +++ b/addons/godot_ai/handlers/material_values.gd @@ -0,0 +1,194 @@ +@tool +extends RefCounted + +## Value coercion helpers for material authoring. +## +## Extends node_handler._coerce_value with material-specific cases: +## - enum-by-name (transparency="alpha" → TRANSPARENCY_ALPHA) +## - texture path → Texture2D +## - {r,g,b,a} dict → Color (also handled by node coerce, but we want it inline) + + +const _ENUM_TABLES := { + "transparency": { + "disabled": BaseMaterial3D.TRANSPARENCY_DISABLED, + "alpha": BaseMaterial3D.TRANSPARENCY_ALPHA, + "alpha_scissor": BaseMaterial3D.TRANSPARENCY_ALPHA_SCISSOR, + "alpha_hash": BaseMaterial3D.TRANSPARENCY_ALPHA_HASH, + "alpha_depth_pre_pass": BaseMaterial3D.TRANSPARENCY_ALPHA_DEPTH_PRE_PASS, + }, + "shading_mode": { + "unshaded": BaseMaterial3D.SHADING_MODE_UNSHADED, + "per_pixel": BaseMaterial3D.SHADING_MODE_PER_PIXEL, + "per_vertex": BaseMaterial3D.SHADING_MODE_PER_VERTEX, + }, + "blend_mode": { + "mix": BaseMaterial3D.BLEND_MODE_MIX, + "add": BaseMaterial3D.BLEND_MODE_ADD, + "sub": BaseMaterial3D.BLEND_MODE_SUB, + "mul": BaseMaterial3D.BLEND_MODE_MUL, + }, + "cull_mode": { + "back": BaseMaterial3D.CULL_BACK, + "front": BaseMaterial3D.CULL_FRONT, + "disabled": BaseMaterial3D.CULL_DISABLED, + }, + "depth_draw_mode": { + "opaque_only": BaseMaterial3D.DEPTH_DRAW_OPAQUE_ONLY, + "always": BaseMaterial3D.DEPTH_DRAW_ALWAYS, + "disabled": BaseMaterial3D.DEPTH_DRAW_DISABLED, + }, + "diffuse_mode": { + "burley": BaseMaterial3D.DIFFUSE_BURLEY, + "lambert": BaseMaterial3D.DIFFUSE_LAMBERT, + "lambert_wrap": BaseMaterial3D.DIFFUSE_LAMBERT_WRAP, + "toon": BaseMaterial3D.DIFFUSE_TOON, + }, + "specular_mode": { + "schlick_ggx": BaseMaterial3D.SPECULAR_SCHLICK_GGX, + "toon": BaseMaterial3D.SPECULAR_TOON, + "disabled": BaseMaterial3D.SPECULAR_DISABLED, + }, + "billboard_mode": { + "disabled": BaseMaterial3D.BILLBOARD_DISABLED, + "enabled": BaseMaterial3D.BILLBOARD_ENABLED, + "fixed_y": BaseMaterial3D.BILLBOARD_FIXED_Y, + "particles": BaseMaterial3D.BILLBOARD_PARTICLES, + }, + "texture_filter": { + "nearest": BaseMaterial3D.TEXTURE_FILTER_NEAREST, + "linear": BaseMaterial3D.TEXTURE_FILTER_LINEAR, + "nearest_mipmap": BaseMaterial3D.TEXTURE_FILTER_NEAREST_WITH_MIPMAPS, + "linear_mipmap": BaseMaterial3D.TEXTURE_FILTER_LINEAR_WITH_MIPMAPS, + }, +} + + +## Return the enum int for (property, string_name), or null if not a known enum string. +static func resolve_enum(property: String, value: Variant) -> Variant: + if not (value is String): + return null + if not _ENUM_TABLES.has(property): + return null + var table: Dictionary = _ENUM_TABLES[property] + var key: String = String(value).to_lower() + if table.has(key): + return table[key] + return null + + +## Parse a color from Color, "#rrggbb(aa)", named string, {r,g,b[,a]} dict, +## or [r,g,b(,a)] array. Delegates to the canonical parser (#714); returns +## null if the input cannot be parsed. +static func parse_color(value: Variant) -> Variant: + return McpJsonValues.parse_color(value) + + +static func parse_vector3(value: Variant) -> Variant: + return McpJsonValues.parse_vector3(value) + + +static func parse_vector2(value: Variant) -> Variant: + return McpJsonValues.parse_vector2(value) + + +## Load a Texture2D from a res:// / uid:// / user:// path (validate_loadable_path). +## Returns null on failure (including a path that fails confinement / traversal). +static func load_texture(path: String) -> Texture2D: + if not McpPathValidator.validate_loadable_path(path).is_empty(): + return null + if not ResourceLoader.exists(path): + return null + var res := ResourceLoader.load(path) + if res is Texture2D: + return res + return null + + +## Coerce a JSON-shaped value for a material property. +## Returns a dict {ok: true, value: ...} on success, or {ok: false, error: "..."} on failure. +## For properties the coercer doesn't have special logic for, falls back to target_type. +static func coerce_material_value(property: String, value: Variant, target_type: int) -> Dictionary: + # Enum-by-name: must match before generic TYPE_INT coercion. + if _ENUM_TABLES.has(property): + if value is String: + var enum_val = resolve_enum(property, value) + if enum_val == null: + return { + "ok": false, + "error": "Invalid %s value: '%s'. Valid: %s" % [ + property, value, ", ".join(_ENUM_TABLES[property].keys()) + ], + } + return {"ok": true, "value": int(enum_val)} + if value is int or value is float: + return {"ok": true, "value": int(value)} + + match target_type: + TYPE_COLOR: + var c = parse_color(value) + if c == null: + return {"ok": false, "error": "Invalid color for %s: %s" % [property, value]} + return {"ok": true, "value": c} + TYPE_VECTOR3: + var v3 = parse_vector3(value) + if v3 == null: + return {"ok": false, "error": "Invalid vector3 for %s: %s" % [property, value]} + return {"ok": true, "value": v3} + TYPE_VECTOR2: + var v2 = parse_vector2(value) + if v2 == null: + return {"ok": false, "error": "Invalid vector2 for %s: %s" % [property, value]} + return {"ok": true, "value": v2} + TYPE_BOOL: + if value is bool: + return {"ok": true, "value": value} + if value is int or value is float: + return {"ok": true, "value": bool(value)} + return {"ok": false, "error": "Expected bool for %s" % property} + TYPE_INT: + if value is int: + return {"ok": true, "value": value} + if value is float: + return {"ok": true, "value": int(value)} + return {"ok": false, "error": "Expected int for %s" % property} + TYPE_FLOAT: + if value is float: + return {"ok": true, "value": value} + if value is int: + return {"ok": true, "value": float(value)} + return {"ok": false, "error": "Expected number for %s" % property} + TYPE_OBJECT: + if value == null: + return {"ok": true, "value": null} + if value is Object: + return {"ok": true, "value": value} + if value is String: + var tex := load_texture(value) + if tex == null: + return {"ok": false, "error": "Resource not found or wrong type: %s" % value} + return {"ok": true, "value": tex} + return {"ok": false, "error": "Expected resource path (string) for %s" % property} + TYPE_STRING: + return {"ok": true, "value": String(value)} + + # Unknown target type — pass through. + return {"ok": true, "value": value} + + +## Serialize a Variant into JSON-friendly shape for responses. +static func serialize_value(value: Variant) -> Variant: + if value == null: + return null + if value is Color: + return {"r": value.r, "g": value.g, "b": value.b, "a": value.a} + if value is Vector3: + return {"x": value.x, "y": value.y, "z": value.z} + if value is Vector2: + return {"x": value.x, "y": value.y} + if value is Resource: + var path := (value as Resource).resource_path + if path.is_empty(): + return {"type": value.get_class(), "path": ""} + return {"type": value.get_class(), "path": path} + return value diff --git a/addons/godot_ai/handlers/material_values.gd.uid b/addons/godot_ai/handlers/material_values.gd.uid new file mode 100644 index 0000000..7f8bbe9 --- /dev/null +++ b/addons/godot_ai/handlers/material_values.gd.uid @@ -0,0 +1 @@ +uid://daqgjkflia8nk diff --git a/addons/godot_ai/handlers/node_handler.gd b/addons/godot_ai/handlers/node_handler.gd new file mode 100644 index 0000000..6d7e1ff --- /dev/null +++ b/addons/godot_ai/handlers/node_handler.gd @@ -0,0 +1,1390 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const VariantSerializer := preload("res://addons/godot_ai/utils/variant_serializer.gd") + +## Handles node creation and manipulation with undo/redo support. + +const ResourceHandler := preload("res://addons/godot_ai/handlers/resource_handler.gd") + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +func create_node(params: Dictionary) -> Dictionary: + var node_type: String = params.get("type", "") + var node_name: String = params.get("name", "") + var parent_path: String = params.get("parent_path", "") + var scene_path: String = params.get("scene_path", "") + + var scene_check := McpScenePath.require_edited_scene(params.get("scene_file", "")) + if scene_check.has("error"): + return scene_check + var scene_root: Node = scene_check.node + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + var new_node: Node + + if not scene_path.is_empty(): + # Scene instancing path — load and instantiate a PackedScene. + # GEN_EDIT_STATE_INSTANCE makes the editor treat the result as a real + # scene instance (foldout icon, the .tscn stores a reference instead of + # an exploded subtree). Descendants remain owned by their sub-scene; + # setting their owner to our scene_root would break the instance link. + var scene_path_err = McpPathValidator.loadable_error(scene_path, "scene_path") + if scene_path_err != null: + return scene_path_err + if not ResourceLoader.exists(scene_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Scene not found: %s" % scene_path) + var packed_scene = ResourceLoader.load(scene_path) + if packed_scene == null or not packed_scene is PackedScene: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a PackedScene" % scene_path) + new_node = packed_scene.instantiate(PackedScene.GEN_EDIT_STATE_INSTANCE) + if new_node == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate scene: %s" % scene_path) + else: + # ClassDB path — create by type. + if node_type.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: type (or provide scene_path)") + if not ClassDB.class_exists(node_type): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unknown node type: %s" % node_type) + if not ClassDB.is_parent_class(node_type, "Node"): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "%s is not a Node type" % node_type) + new_node = ClassDB.instantiate(node_type) + if new_node == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s" % node_type) + + if not node_name.is_empty(): + new_node.name = node_name + + _undo_redo.create_action("MCP: Create %s" % new_node.name) + _undo_redo.add_do_method(parent, "add_child", new_node, true) + _undo_redo.add_do_method(new_node, "set_owner", scene_root) + _undo_redo.add_do_reference(new_node) + _undo_redo.add_undo_method(parent, "remove_child", new_node) + _undo_redo.commit_action() + + var response := { + "name": new_node.name, + "type": new_node.get_class(), + "path": McpScenePath.from_node(new_node, scene_root), + "parent_path": McpScenePath.from_node(parent, scene_root), + "undoable": true, + } + if not scene_path.is_empty(): + response["scene_path"] = scene_path + return {"data": response} + + +func delete_node(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + var root_err := _reject_if_scene_root(node, scene_root, "delete") + if root_err != null: + return root_err + + var parent := node.get_parent() + var idx := node.get_index() + + _undo_redo.create_action("MCP: Delete %s" % node.name) + _undo_redo.add_do_method(parent, "remove_child", node) + _undo_redo.add_undo_method(parent, "add_child", node, true) + _undo_redo.add_undo_method(parent, "move_child", node, idx) + _undo_redo.add_undo_method(node, "set_owner", scene_root) + _undo_redo.add_undo_reference(node) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "undoable": true, + } + } + + +func reparent_node(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + var new_parent_path: String = params.get("new_parent", "") + if new_parent_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: new_parent") + + var new_parent := McpScenePath.resolve(new_parent_path, scene_root) + if new_parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(new_parent_path, scene_root)) + + var root_err := _reject_if_scene_root(node, scene_root, "reparent") + if root_err != null: + return root_err + + # Prevent reparenting a node to itself or to one of its own descendants. + # Godot's `A.is_ancestor_of(B)` returns true iff B is a descendant of A, so + # the direction here matters: we want `node.is_ancestor_of(new_parent)` to + # catch "new_parent is below node in the tree" and thus would create a + # cycle. The previous direction (`new_parent.is_ancestor_of(node)`) asked + # the opposite question — whether we were trying to move a node to one of + # its own ancestors — which is a perfectly valid operation. See issue #121. + if node == new_parent or node.is_ancestor_of(new_parent): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Cannot reparent a node to itself or its descendant") + + var old_parent := node.get_parent() + var old_idx := node.get_index() + + _undo_redo.create_action("MCP: Reparent %s" % node.name) + _undo_redo.add_do_method(old_parent, "remove_child", node) + _undo_redo.add_do_method(new_parent, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + _undo_redo.add_do_reference(node) + _undo_redo.add_undo_method(new_parent, "remove_child", node) + _undo_redo.add_undo_method(old_parent, "add_child", node, true) + _undo_redo.add_undo_method(old_parent, "move_child", node, old_idx) + _undo_redo.add_undo_method(node, "set_owner", scene_root) + _undo_redo.add_undo_reference(node) + _undo_redo.commit_action() + + # Re-set owner for all descendants (reparent can break ownership chain) + _set_owner_recursive(node, scene_root) + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "old_parent": McpScenePath.from_node(old_parent, scene_root), + "new_parent": McpScenePath.from_node(new_parent, scene_root), + "undoable": true, + } + } + + +func set_property(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + var property: String = params.get("property", "") + if property.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: property") + + if not "value" in params: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: value") + + var value = params.get("value") + + var found := false + var prop_type: int = TYPE_NIL + for prop in node.get_property_list(): + if prop.name == property: + found = true + prop_type = prop.get("type", TYPE_NIL) + break + if not found: + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, McpPropertyErrors.build_message(node, property)) + + var old_value = node.get(property) + # Prefer declared property type; fall back to runtime type for dynamic props + # (scripted @export vars can report TYPE_NIL in the property list). + var target_type: int = prop_type if prop_type != TYPE_NIL else typeof(old_value) + + var instantiated_resource := false + + # Some MCP clients (Cline) stringify the documented {"__class__": "BoxMesh", ...} + # value before sending. Promote that string back to a Dictionary here so the + # `__class__` branch below handles it, instead of the next branch treating + # the JSON blob as a res:// path and emitting "Resource not found: {...}". + # See #206. + if target_type == TYPE_OBJECT and value is String and value.begins_with("{"): + var json := JSON.new() + if json.parse(value) == OK and json.data is Dictionary and (json.data as Dictionary).has("__class__"): + value = json.data + + var nil_resource_string: bool = target_type == TYPE_NIL and (value == "" or (value is String and value.begins_with("res://"))) + var resource_string_value: bool = value is String and (target_type == TYPE_OBJECT or nil_resource_string) + if resource_string_value: + if value == "": + value = null + else: + var value_path_err = McpPathValidator.loadable_error(value, "value") + if value_path_err != null: + return value_path_err + if not ResourceLoader.exists(value): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % value) + var loaded := ResourceLoader.load(value) + if loaded == null: + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % value) + value = loaded + elif target_type == TYPE_OBJECT and value is Dictionary and value.has("__class__"): + # Shortcut: {"__class__": "BoxMesh", "size": {...}} instantiates a + # fresh Resource subclass and applies the remaining keys as + # properties. Mirrors resource_create's inline-assign path but + # avoids a separate tool call for the common case. + var type_str: String = value.get("__class__", "") + var made := ResourceHandler._instantiate_resource(type_str) + if made is Dictionary: + return made + var res: Resource = made + var remaining: Dictionary = (value as Dictionary).duplicate() + remaining.erase("__class__") + if not remaining.is_empty(): + var apply_err := ResourceHandler._apply_resource_properties(res, remaining) + if apply_err != null: + return apply_err + value = res + instantiated_resource = true + elif target_type == TYPE_ARRAY and old_value is Array and (old_value as Array).is_typed(): + ## Typed Array[T] slot (#612): the generic TYPE_ARRAY passthrough + ## hands an untyped Array to Godot's typed setter, which rejects it + ## wholesale and leaves the slot at its default — with success still + ## reported. Route through the element-aware coercer instead; errors + ## name the offending element index. + var typed_out: Variant = _coerce_typed_array(value, old_value) + if typed_out is Dictionary: + return typed_out + value = typed_out + elif ( + target_type == TYPE_DICTIONARY + and old_value is Dictionary + and (old_value as Dictionary).is_typed() + ): + ## Typed Dictionary[K, V] slot (#612 stage 3) — same silent-drop + ## family as typed arrays. A successful result is always a TYPED + ## Dictionary (a cleared duplicate of the slot), while the error + ## envelope is an untyped {"error": ...} — that's the discriminator + ## (a legit payload could contain an "error" key; typedness can't lie). + var typed_dict_out: Dictionary = _coerce_typed_dictionary(value, old_value) + if not typed_dict_out.is_typed(): + return typed_dict_out + value = typed_dict_out + else: + value = _coerce_value(value, target_type) + ## Refuse any value that didn't land as the target compound Variant + ## — wrong-shape dict (#123) or non-dict input like list / JSON string + ## that used to silently default-construct Vector3.ZERO (#191). + var coerce_err := _check_coerced(value, target_type) + if coerce_err != null: + return coerce_err + + _undo_redo.create_action("MCP: Set %s.%s" % [node.name, property]) + _undo_redo.add_do_property(node, property, value) + _undo_redo.add_undo_property(node, property, old_value) + if instantiated_resource: + _undo_redo.add_do_reference(value) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "property": property, + "value": _serialize_value(node.get(property)), + "old_value": _serialize_value(old_value), + "undoable": true, + } + } + + +func rename_node(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + var new_name: String = params.get("new_name", "") + if new_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: new_name") + + ## The scene root's name is baked into the .tscn serialization and is + ## referenced by every NodePath that starts with `/` (AnimationPlayer + ## tracks, RemoteTransform3D targets, exported NodePath @vars, etc.). + ## Renaming it silently breaks those references. The MCP tool's docstring + ## has always promised "Cannot rename the scene root" — enforce it. #122 + if node == scene_root: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Cannot rename the scene root") + + if new_name.validate_node_name() != new_name: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Invalid characters in name: %s" % new_name) + + var old_name := String(node.name) + if old_name == new_name: + return { + "data": { + "path": node_path, + "name": new_name, + "old_name": old_name, + "unchanged": true, + "undoable": false, + "reason": "Name unchanged", + } + } + + var parent := node.get_parent() + for sibling in parent.get_children(): + if sibling != node and String(sibling.name) == new_name: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "A sibling already has the name '%s'" % new_name) + + _undo_redo.create_action("MCP: Rename %s to %s" % [old_name, new_name]) + _undo_redo.add_do_property(node, "name", new_name) + _undo_redo.add_undo_property(node, "name", old_name) + _undo_redo.commit_action() + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "old_path": node_path, + "name": String(node.name), + "old_name": old_name, + "undoable": true, + } + } + + +func duplicate_node(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + var root_err := _reject_if_scene_root(node, scene_root, "duplicate") + if root_err != null: + return root_err + + var parent := node.get_parent() + var dup: Node = node.duplicate() + if dup == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to duplicate node") + + # Apply optional name + var new_name: String = params.get("name", "") + if not new_name.is_empty(): + dup.name = new_name + + _undo_redo.create_action("MCP: Duplicate %s" % node.name) + _undo_redo.add_do_method(parent, "add_child", dup, true) + _undo_redo.add_do_method(dup, "set_owner", scene_root) + _undo_redo.add_do_reference(dup) + _undo_redo.add_undo_method(parent, "remove_child", dup) + _undo_redo.commit_action() + + # Set owner for all descendants of the duplicate + _set_owner_recursive(dup, scene_root) + + return { + "data": { + "path": McpScenePath.from_node(dup, scene_root), + "original_path": node_path, + "name": dup.name, + "type": dup.get_class(), + "undoable": true, + } + } + + +func move_node(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + var root_err := _reject_if_scene_root(node, scene_root, "reorder") + if root_err != null: + return root_err + + if not "index" in params: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: index") + + var new_index: int = params.get("index", 0) + var parent := node.get_parent() + var old_index := node.get_index() + var sibling_count := parent.get_child_count() + + if new_index < 0 or new_index >= sibling_count: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Index %d out of range (0..%d)" % [new_index, sibling_count - 1]) + + _undo_redo.create_action("MCP: Move %s to index %d" % [node.name, new_index]) + _undo_redo.add_do_method(parent, "move_child", node, new_index) + _undo_redo.add_undo_method(parent, "move_child", node, old_index) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "old_index": old_index, + "new_index": new_index, + "undoable": true, + } + } + + +func add_to_group(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + + var group_value: Variant = params.get("group", "") + var type_err := McpParamValidators.require_string("group", group_value) + if type_err != null: + return type_err + var group := String(group_value) + if group.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: group") + + if node.is_in_group(group): + return {"data": {"path": node_path, "group": group, "already_member": true, "undoable": false, "reason": "No change made"}} + + _undo_redo.create_action("MCP: Add %s to group %s" % [node.name, group]) + _undo_redo.add_do_method(node, "add_to_group", group, true) + _undo_redo.add_undo_method(node, "remove_from_group", group) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "group": group, + "undoable": true, + } + } + + +func remove_from_group(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + + var group_value: Variant = params.get("group", "") + var type_err := McpParamValidators.require_string("group", group_value) + if type_err != null: + return type_err + var group := String(group_value) + if group.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: group") + + if not node.is_in_group(group): + return {"data": {"path": node_path, "group": group, "not_member": true, "undoable": false, "reason": "Node not in group"}} + + _undo_redo.create_action("MCP: Remove %s from group %s" % [node.name, group]) + _undo_redo.add_do_method(node, "remove_from_group", group) + _undo_redo.add_undo_method(node, "add_to_group", group, true) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "group": group, + "undoable": true, + } + } + + +func set_selection(params: Dictionary) -> Dictionary: + var paths: Array = params.get("paths", []) + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var selection := EditorInterface.get_selection() + selection.clear() + + var selected: Array[String] = [] + var not_found: Array[String] = [] + for path_variant in paths: + var path: String = str(path_variant) + var node := McpScenePath.resolve(path, scene_root) + if node: + selection.add_node(node) + selected.append(path) + else: + not_found.append(path) + + return { + "data": { + "selected": selected, + "not_found": not_found, + "count": selected.size(), + "undoable": false, + "reason": "Selection changes are not tracked in undo history", + } + } + + +func _set_owner_recursive(node: Node, owner: Node) -> void: + for child in node.get_children(): + child.set_owner(owner) + _set_owner_recursive(child, owner) + + +## Canonical dict-key sets for dict→Variant coercion. Alpha on `COLOR_KEYS` +## is optional — the coercer defaults it to 1.0 when absent. +const VECTOR2_KEYS: Array[String] = ["x", "y"] +const VECTOR3_KEYS: Array[String] = ["x", "y", "z"] +const VECTOR4_KEYS: Array[String] = ["x", "y", "z", "w"] +const COLOR_KEYS: Array[String] = ["r", "g", "b"] + + +## End-to-end coerce check for compound JSON-shaped targets +## (Vector2/Vector3/Color). Returns a full `make(...)`-shaped error dict +## if `value` didn't land as the target Variant after `_coerce_value`, +## else null. Wrong-shape dicts get the `_check_dict_coerce_failed` +## message (expected-vs-got keys); non-dict inputs (Array, String, +## primitive) name the received type and a JSON shape hint. No-op for +## non-compound targets — Godot's setter handles those. +## +## Used by set_property, resource_handler, and validation handlers +## (curve, texture). Issue #191 — passing a list, JSON string, or +## anything else to a Vector3 property used to silently store +## Vector3.ZERO; this gates that path. +static func _check_coerced(value: Variant, target_type: int, prefix: String = "") -> Variant: + var ok := false + match target_type: + TYPE_VECTOR2: + ok = value is Vector2 + TYPE_VECTOR3: + ok = value is Vector3 + TYPE_COLOR: + ok = value is Color + TYPE_PACKED_VECTOR2_ARRAY: + ok = value is PackedVector2Array + TYPE_PACKED_VECTOR3_ARRAY: + ok = value is PackedVector3Array + TYPE_PACKED_VECTOR4_ARRAY: + ok = value is PackedVector4Array + TYPE_PACKED_COLOR_ARRAY: + ok = value is PackedColorArray + TYPE_PACKED_INT32_ARRAY: + ok = value is PackedInt32Array + TYPE_PACKED_INT64_ARRAY: + ok = value is PackedInt64Array + TYPE_PACKED_FLOAT32_ARRAY: + ok = value is PackedFloat32Array + TYPE_PACKED_FLOAT64_ARRAY: + ok = value is PackedFloat64Array + TYPE_PACKED_STRING_ARRAY: + ok = value is PackedStringArray + TYPE_VECTOR2I: ok = value is Vector2i + TYPE_VECTOR3I: ok = value is Vector3i + TYPE_VECTOR4: ok = value is Vector4 + TYPE_VECTOR4I: ok = value is Vector4i + TYPE_QUATERNION: ok = value is Quaternion + TYPE_RECT2: ok = value is Rect2 + TYPE_RECT2I: ok = value is Rect2i + TYPE_AABB: ok = value is AABB + TYPE_PLANE: ok = value is Plane + TYPE_BASIS: ok = value is Basis + TYPE_TRANSFORM2D: ok = value is Transform2D + TYPE_TRANSFORM3D: ok = value is Transform3D + TYPE_PROJECTION: ok = value is Projection + _: + # null / untyped-TYPE_NIL / already-correct-type are handled by + # Godot's setter; anything else would silently no-op, so error. + if value == null or target_type == TYPE_NIL or typeof(value) == target_type: + return null + var unsupported := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Cannot write %s to a %s property; godot-ai has no coercion for that type" % [ + type_string(typeof(value)), type_string(target_type), + ], + ) + return ErrorCodes.prefix_message(unsupported, prefix) + if ok: + return null + var dict_err := _check_dict_coerce_failed(value, target_type) + if dict_err != null: + return ErrorCodes.prefix_message(dict_err, prefix) + ## Wording stays neutral on shape — `_shape_hint` already produces a + ## dict-shaped string for Vector2/3/Color and a list-shaped one for + ## the Packed*Array slots. The old "expected a dict like [...]" phrasing + ## read self-contradictory for packed targets (PR #424 review). + var err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Cannot coerce %s to %s; expected %s" % [ + type_string(typeof(value)), type_string(target_type), _shape_hint(target_type), + ], + ) + return ErrorCodes.prefix_message(err, prefix) + + +## Build a "{\"x\":1,...}" hint string from the canonical key constants +## so adding a key (e.g. Vector4) only touches VECTORN_KEYS. Packed*Array +## targets short-circuit to a literal list-shaped hint. +static func _shape_hint(target_type: int) -> String: + match target_type: + TYPE_PACKED_VECTOR2_ARRAY: + return "[{\"x\":0,\"y\":0}, ...]" + TYPE_PACKED_VECTOR3_ARRAY: + return "[{\"x\":0,\"y\":0,\"z\":0}, ...]" + TYPE_PACKED_VECTOR4_ARRAY: + return "[{\"x\":0,\"y\":0,\"z\":0,\"w\":0}, ...]" + TYPE_PACKED_COLOR_ARRAY: + return "[{\"r\":0,\"g\":0,\"b\":0,\"a\":1}, ...]" + TYPE_PACKED_INT32_ARRAY, TYPE_PACKED_INT64_ARRAY: + return "[int, ...]" + TYPE_PACKED_FLOAT32_ARRAY, TYPE_PACKED_FLOAT64_ARRAY: + return "[float, ...]" + TYPE_PACKED_STRING_ARRAY: + return "[\"...\", ...]" + TYPE_VECTOR2I: + return "{\"x\":0,\"y\":0}" + TYPE_VECTOR3I: + return "{\"x\":0,\"y\":0,\"z\":0}" + TYPE_VECTOR4, TYPE_VECTOR4I, TYPE_QUATERNION: + return "{\"x\":0,\"y\":0,\"z\":0,\"w\":0}" + TYPE_RECT2, TYPE_RECT2I, TYPE_AABB: + return "{\"position\":{...},\"size\":{...}}" + TYPE_PLANE: + return "{\"normal\":{...},\"d\":0}" + TYPE_BASIS: + return "{\"x\":{...},\"y\":{...},\"z\":{...}}" + TYPE_TRANSFORM2D: + return "{\"x\":{...},\"y\":{...},\"origin\":{...}}" + TYPE_TRANSFORM3D: + return "{\"basis\":{...},\"origin\":{...}}" + TYPE_PROJECTION: + return "{\"x\":{...},\"y\":{...},\"z\":{...},\"w\":{...}}" + var keys: Array[String] = [] + match target_type: + TYPE_VECTOR2: keys = VECTOR2_KEYS + TYPE_VECTOR3: keys = VECTOR3_KEYS + TYPE_COLOR: keys = COLOR_KEYS + var pairs: Array[String] = [] + for k in keys: + pairs.append("\"%s\":0" % k) + return "{" + ",".join(pairs) + "}" + + +## Detect a failed dict→typed-Variant coercion. Returns an INVALID_PARAMS +## error dict if `value` is still a Dictionary after a coercion attempt +## targeting a Vector2/Vector3/Color slot, else null. Message names the +## expected keys and the keys actually received so agents self-correct +## on the next retry. +static func _check_dict_coerce_failed(value: Variant, target_type: int) -> Variant: + if not (value is Dictionary): + return null + var expected: Array[String] = [] + var type_name := "" + match target_type: + TYPE_VECTOR2: + expected = VECTOR2_KEYS + type_name = "Vector2" + TYPE_VECTOR3: + expected = VECTOR3_KEYS + type_name = "Vector3" + TYPE_COLOR: + expected = COLOR_KEYS + type_name = "Color" + _: + return null + var got_keys: Array = (value as Dictionary).keys() + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Cannot coerce dict to %s: expected keys %s; got %s" % [type_name, str(expected), str(got_keys)] + ) + + +## Coerce JSON-shaped values into Godot Variants when the target property +## type is known. Returns the coerced value on success, or the input +## unchanged on failure — callers detect the type mismatch via an +## `is ` check (curve_handler, texture_handler) or via the +## `_check_dict_coerce_failed` helper (set_property, resource_handler). +## +## Dictionary→Vector2/Vector3/Color cases REQUIRE all canonical keys; +## wrong-shape dicts flow through unchanged. See issue #123 — previous +## `dict.get(key, 0)` defaults silently zero-filled missing axes. +static func _coerce_value(value: Variant, target_type: int) -> Variant: + match target_type: + ## Vector2/Vector3/Color route through the canonical strict parser + ## (#714): same dict/array/string shapes as every other handler, and + ## non-numeric components fall through (returning the original + ## value) so _check_coerced flags them instead of crashing a typed + ## constructor or silently writing black/zeros. + TYPE_VECTOR2: + var v2 = McpJsonValues.parse_vector2(value) + if v2 != null: + return v2 + TYPE_VECTOR3: + var v3 = McpJsonValues.parse_vector3(value) + if v3 != null: + return v3 + TYPE_COLOR: + var col = McpJsonValues.parse_color(value) + if col != null: + return col + TYPE_BOOL: + if value is float or value is int: + return bool(value) + TYPE_INT: + if value is float: + return int(value) + TYPE_FLOAT: + if value is int: + return float(value) + TYPE_STRING_NAME: + if value is String: + return StringName(value) + TYPE_NODE_PATH: + if value is String: + return NodePath(value) + if value == null: + return NodePath() + TYPE_OBJECT: + # Resource loading is handled in set_property so we can return a + # typed error; here we only pass through cleared values. + if value == null: + return null + TYPE_ARRAY: + if value is Array: + return value + TYPE_DICTIONARY: + if value is Dictionary: + return value + TYPE_PACKED_VECTOR2_ARRAY: + if value is Array: + var out := PackedVector2Array() + for item in value: + if item is Vector2: + out.append(item) + elif item is Dictionary and item.has_all(VECTOR2_KEYS): + out.append(Vector2(item["x"], item["y"])) + else: + return value # leave for _check_coerced to flag + return out + TYPE_PACKED_VECTOR3_ARRAY: + if value is Array: + var out := PackedVector3Array() + for item in value: + if item is Vector3: + out.append(item) + elif item is Dictionary and item.has_all(VECTOR3_KEYS): + out.append(Vector3(item["x"], item["y"], item["z"])) + else: + return value + return out + TYPE_PACKED_VECTOR4_ARRAY: + if value is Array: + var out := PackedVector4Array() + for item in value: + if item is Vector4: + out.append(item) + elif item is Dictionary and item.has_all(VECTOR4_KEYS): + out.append(Vector4(item["x"], item["y"], item["z"], item["w"])) + else: + return value + return out + TYPE_PACKED_COLOR_ARRAY: + if value is Array: + var out := PackedColorArray() + for item in value: + if item is Color: + out.append(item) + elif item is Dictionary and item.has_all(COLOR_KEYS): + out.append(Color(item["r"], item["g"], item["b"], item.get("a", 1.0))) + elif item is String: + out.append(Color(item)) + else: + return value + return out + TYPE_PACKED_INT32_ARRAY, TYPE_PACKED_INT64_ARRAY: + if value is Array: + var out: Variant = PackedInt32Array() if target_type == TYPE_PACKED_INT32_ARRAY else PackedInt64Array() + for item in value: + if item is int or item is float: + out.append(int(item)) + else: + return value + return out + TYPE_PACKED_FLOAT32_ARRAY, TYPE_PACKED_FLOAT64_ARRAY: + if value is Array: + var out: Variant = PackedFloat32Array() if target_type == TYPE_PACKED_FLOAT32_ARRAY else PackedFloat64Array() + for item in value: + if item is float or item is int: + out.append(float(item)) + else: + return value + return out + TYPE_PACKED_STRING_ARRAY: + if value is Array: + var out := PackedStringArray() + for item in value: + if item is String: + out.append(item) + else: + return value + return out + TYPE_VECTOR2I: + if value is Dictionary and value.has_all(VECTOR2_KEYS): + return Vector2i(int(value["x"]), int(value["y"])) + TYPE_VECTOR3I: + if value is Dictionary and value.has_all(VECTOR3_KEYS): + return Vector3i(int(value["x"]), int(value["y"]), int(value["z"])) + TYPE_VECTOR4: + if value is Dictionary and value.has_all(VECTOR4_KEYS): + return Vector4(value["x"], value["y"], value["z"], value["w"]) + TYPE_VECTOR4I: + if value is Dictionary and value.has_all(VECTOR4_KEYS): + return Vector4i(int(value["x"]), int(value["y"]), int(value["z"]), int(value["w"])) + TYPE_QUATERNION: + if value is Dictionary and value.has_all(VECTOR4_KEYS): + return Quaternion(value["x"], value["y"], value["z"], value["w"]) + TYPE_RECT2: + if value is Dictionary and value.has("position") and value.has("size"): + var p: Variant = _coerce_value(value["position"], TYPE_VECTOR2) + var s: Variant = _coerce_value(value["size"], TYPE_VECTOR2) + if p is Vector2 and s is Vector2: + return Rect2(p, s) + TYPE_RECT2I: + if value is Dictionary and value.has("position") and value.has("size"): + var p: Variant = _coerce_value(value["position"], TYPE_VECTOR2I) + var s: Variant = _coerce_value(value["size"], TYPE_VECTOR2I) + if p is Vector2i and s is Vector2i: + return Rect2i(p, s) + TYPE_AABB: + if value is Dictionary and value.has("position") and value.has("size"): + var p: Variant = _coerce_value(value["position"], TYPE_VECTOR3) + var s: Variant = _coerce_value(value["size"], TYPE_VECTOR3) + if p is Vector3 and s is Vector3: + return AABB(p, s) + TYPE_PLANE: + if value is Dictionary and value.has("normal") and value.has("d"): + var n: Variant = _coerce_value(value["normal"], TYPE_VECTOR3) + if n is Vector3: + return Plane(n, float(value["d"])) + TYPE_BASIS: + if value is Dictionary and value.has_all(["x", "y", "z"]): + var bx: Variant = _coerce_value(value["x"], TYPE_VECTOR3) + var by: Variant = _coerce_value(value["y"], TYPE_VECTOR3) + var bz: Variant = _coerce_value(value["z"], TYPE_VECTOR3) + if bx is Vector3 and by is Vector3 and bz is Vector3: + return Basis(bx, by, bz) + TYPE_TRANSFORM2D: + if value is Dictionary and value.has_all(["x", "y", "origin"]): + var tx: Variant = _coerce_value(value["x"], TYPE_VECTOR2) + var ty: Variant = _coerce_value(value["y"], TYPE_VECTOR2) + var to_: Variant = _coerce_value(value["origin"], TYPE_VECTOR2) + if tx is Vector2 and ty is Vector2 and to_ is Vector2: + return Transform2D(tx, ty, to_) + TYPE_TRANSFORM3D: + if value is Dictionary and value.has("basis") and value.has("origin"): + var b: Variant = _coerce_value(value["basis"], TYPE_BASIS) + var o: Variant = _coerce_value(value["origin"], TYPE_VECTOR3) + if b is Basis and o is Vector3: + return Transform3D(b, o) + TYPE_PROJECTION: + if value is Dictionary and value.has_all(VECTOR4_KEYS): + var px: Variant = _coerce_value(value["x"], TYPE_VECTOR4) + var py: Variant = _coerce_value(value["y"], TYPE_VECTOR4) + var pz: Variant = _coerce_value(value["z"], TYPE_VECTOR4) + var pw: Variant = _coerce_value(value["w"], TYPE_VECTOR4) + if px is Vector4 and py is Vector4 and pz is Vector4 and pw is Vector4: + return Projection(px, py, pz, pw) + # PackedByteArray intentionally unhandled — needs design decision + # (base64 string vs. raw int list); JSON has no native byte type. + return value + + +## Fill a typed `Array[T]` slot from a JSON list (#612 stage 1: value-element +## types). `slot_value` is the property's current typed Array — Godot's getter +## returns the (possibly empty) typed container, which carries the element +## type, so no PROPERTY_HINT_TYPE_STRING parsing is needed. Elements coerce +## one at a time through the existing `_coerce_value` / `_check_coerced` +## pair, then bulk-move via `Array.assign()` with a post-assign size check, +## so a wrong element can never silently drop the write: it errors naming +## the element index. Returns the filled typed Array on success, or a +## `make(...)`-shaped error Dictionary (callers discriminate on +## `result is Dictionary` — a successful result is always an Array). +## +## Object elements (Array[Texture2D], Array[MyResource], ...) coerce per +## element through `_coerce_object_element` (#612 stage 2), mirroring the +## single-slot TYPE_OBJECT paths: res:// strings load, {"__class__": ...} +## instantiates, and each landed element is conformance-checked against the +## slot's element class/script so a wrong-class Resource errors naming the +## index instead of being rejected wholesale by `assign`. +static func _coerce_typed_array(value: Variant, slot_value: Array, prefix: String = "") -> Variant: + var elem_label := _typed_array_element_label(slot_value) + if not (value is Array): + var err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Cannot write %s to a typed Array[%s] property; expected a list" % [ + type_string(typeof(value)), elem_label, + ], + ) + return ErrorCodes.prefix_message(err, prefix) + var elem_type := slot_value.get_typed_builtin() + var staging: Array = [] + var in_list: Array = value + for i in in_list.size(): + var elem_prefix := ("element %d" % i) if prefix.is_empty() else "%s element %d" % [prefix, i] + var coerced: Variant + if elem_type == TYPE_OBJECT: + coerced = _coerce_object_element(in_list[i], elem_prefix) + if coerced is Dictionary: + ## Object elements are never legit Dictionaries (a dict input + ## is either {"__class__"} — consumed above — or an error), so + ## a Dictionary return is unambiguously the error envelope. + return coerced + if coerced != null and not _object_element_conforms(coerced, slot_value): + var conform_err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "element is %s, which is not a %s" % [ + (coerced as Object).get_class(), elem_label, + ], + ) + return ErrorCodes.prefix_message(conform_err, elem_prefix) + else: + coerced = _coerce_value(in_list[i], elem_type) + var elem_err := _check_coerced(coerced, elem_type, elem_prefix) + if elem_err != null: + return elem_err + if coerced == null: + ## Prefix with `elem_prefix` (which already folds in `prefix`), + ## not `prefix` again — the latter double-stamped the property + ## context (PR #682 review). Object arrays allow null entries + ## (Godot typed object arrays store null); value-type arrays + ## don't. + var null_err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "cannot store null in Array[%s]" % elem_label, + ) + return ErrorCodes.prefix_message(null_err, elem_prefix) + staging.append(coerced) + var out := slot_value.duplicate() + out.clear() + out.assign(staging) + if out.size() != staging.size(): + ## Backstop for element shapes `_check_coerced` waves through but the + ## typed container still rejects — `assign` loud-rejects and leaves a + ## short array, which without this check would be a partial write. + var assign_err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Array[%s] element conversion failed during assign (%d of %d elements landed)" % [ + elem_label, out.size(), staging.size(), + ], + ) + return ErrorCodes.prefix_message(assign_err, prefix) + return out + + +## "int" / "Vector3" / "Texture2D" / "MyItemData" — element-type name of a +## typed Array slot, for error messages. +static func _typed_array_element_label(slot_value: Array) -> String: + if slot_value.get_typed_builtin() == TYPE_OBJECT: + return _object_type_label(slot_value.get_typed_class_name(), slot_value.get_typed_script()) + return type_string(slot_value.get_typed_builtin()) + + +## Coerce one element of an object-typed Array (#612 stage 2). Mirrors the +## single-slot TYPE_OBJECT paths in set_property: a res:// path string loads +## the Resource; {"__class__": "X", ...} (including the #206 stringified +## form) instantiates via ResourceHandler and applies the remaining keys; +## "" / null store a null entry (typed object arrays allow them). Returns +## the Object (or null), or a make(...)-shaped error Dictionary with +## `elem_prefix` already folded in. +static func _coerce_object_element(elem: Variant, elem_prefix: String) -> Variant: + if elem == null: + return null + if elem is Object: + return elem + if elem is String and (elem as String).begins_with("{"): + var json := JSON.new() + if json.parse(elem) == OK and json.data is Dictionary and (json.data as Dictionary).has("__class__"): + elem = json.data + if elem is String: + if String(elem).is_empty(): + return null + var path_err = McpPathValidator.loadable_error(elem, "value") + if path_err != null: + return ErrorCodes.prefix_message(path_err, elem_prefix) + if not ResourceLoader.exists(elem): + return ErrorCodes.prefix_message( + ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % elem), + elem_prefix, + ) + var loaded := ResourceLoader.load(elem) + if loaded == null: + return ErrorCodes.prefix_message( + ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % elem), + elem_prefix, + ) + return loaded + if elem is Dictionary and (elem as Dictionary).has("__class__"): + var type_str: String = (elem as Dictionary).get("__class__", "") + var made := ResourceHandler._instantiate_resource(type_str) + if made is Dictionary: + return ErrorCodes.prefix_message(made, elem_prefix) + var res: Resource = made + var remaining: Dictionary = (elem as Dictionary).duplicate() + remaining.erase("__class__") + if not remaining.is_empty(): + var apply_err: Variant = ResourceHandler._apply_resource_properties(res, remaining) + if apply_err != null: + return ErrorCodes.prefix_message(apply_err, elem_prefix) + return res + return ErrorCodes.prefix_message( + ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + 'cannot convert %s to an Object element; pass a res:// path or {"__class__": ...}' + % type_string(typeof(elem)), + ), + elem_prefix, + ) + + +## True when `elem` satisfies the object-typed slot's element constraint — +## script type when the slot is Array[MyScriptClass], native class +## otherwise. Checked per element so a wrong-class Resource errors naming +## the index instead of being rejected wholesale by `Array.assign()`. +static func _object_element_conforms(elem: Object, slot_value: Array) -> bool: + return _object_conforms(elem, slot_value.get_typed_class_name(), slot_value.get_typed_script()) + + +## Shared class/script conformance predicate for typed Array elements and +## typed Dictionary values (#612 stages 2–3). +static func _object_conforms(elem: Object, cls_name: StringName, script: Variant) -> bool: + if script is Script: + return is_instance_of(elem, script) + var cls := String(cls_name) + return cls.is_empty() or elem.is_class(cls) + + +## Fill a typed `Dictionary[K, V]` slot from a JSON object (#612 stage 3). +## `slot_value` is the property's current typed Dictionary — the getter +## returns the (possibly empty) typed container carrying both constraint +## sides. Keys coerce via `_coerce_typed_dict_key` (JSON object keys are +## always Strings, so int/float/StringName key slots parse the string and +## fail closed on anything inexact); values mirror the typed-array element +## rules — object values through `_coerce_object_element` + conformance, +## everything else through `_coerce_value`/`_check_coerced`. Never partial: +## any bad key or value errors naming the key and nothing is written. +## +## Returns the filled TYPED Dictionary on success or an UNTYPED +## `make(...)`-shaped error Dictionary — callers discriminate on +## `is_typed()`, since a success result is always a duplicate of the typed +## slot and error envelopes are plain dicts. +static func _coerce_typed_dictionary( + value: Variant, slot_value: Dictionary, prefix: String = "" +) -> Dictionary: + var label := _typed_dictionary_label(slot_value) + if not (value is Dictionary): + var err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Cannot write %s to a typed %s property; expected an object" % [ + type_string(typeof(value)), label, + ], + ) + return ErrorCodes.prefix_message(err, prefix) + var key_type := slot_value.get_typed_key_builtin() if slot_value.is_typed_key() else TYPE_NIL + var value_type := ( + slot_value.get_typed_value_builtin() if slot_value.is_typed_value() else TYPE_NIL + ) + var out := slot_value.duplicate() + out.clear() + var in_dict: Dictionary = value + for raw_key in in_dict.keys(): + var key_prefix := ( + 'key "%s"' % str(raw_key) if prefix.is_empty() + else '%s key "%s"' % [prefix, str(raw_key)] + ) + var key: Variant = _coerce_typed_dict_key(raw_key, key_type, label, key_prefix) + if key is Dictionary: + ## Scalar-only key coercion never returns a legit Dictionary key, + ## so a Dictionary here is unambiguously the error envelope. + return key + var raw_value: Variant = in_dict[raw_key] + var coerced: Variant + if value_type == TYPE_NIL: + ## Untyped value side (e.g. Dictionary[String, Variant]). + coerced = raw_value + elif value_type == TYPE_OBJECT: + coerced = _coerce_object_element(raw_value, key_prefix) + if coerced is Dictionary: + return coerced + if coerced != null and not _object_conforms( + coerced, + slot_value.get_typed_value_class_name(), + slot_value.get_typed_value_script(), + ): + var conform_err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "value is %s, which is not a %s" % [ + (coerced as Object).get_class(), + _object_type_label( + slot_value.get_typed_value_class_name(), + slot_value.get_typed_value_script(), + ), + ], + ) + return ErrorCodes.prefix_message(conform_err, key_prefix) + else: + coerced = _coerce_value(raw_value, value_type) + var value_err := _check_coerced(coerced, value_type, key_prefix) + if value_err != null: + return value_err + if coerced == null: + var null_err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "cannot store null as a %s value in %s" % [type_string(value_type), label], + ) + return ErrorCodes.prefix_message(null_err, key_prefix) + out[key] = coerced + if out.size() != in_dict.size(): + ## Two input keys collapsing onto one coerced key ("1" and "01" both + ## parse to int 1) would silently lose an entry — refuse instead. + var collide_err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "%s keys collide after coercion (%d of %d entries landed)" % [ + label, out.size(), in_dict.size(), + ], + ) + return ErrorCodes.prefix_message(collide_err, prefix) + return out + + +## Coerce one JSON-object key onto a typed Dictionary's key slot. JSON keys +## are always Strings, so int/float/StringName key types accept exactly the +## strings that parse cleanly; everything else fails closed naming the key. +## Object/compound key types are unreachable from JSON and refuse loudly. +static func _coerce_typed_dict_key( + raw_key: Variant, key_type: int, label: String, key_prefix: String +) -> Variant: + if key_type == TYPE_NIL or typeof(raw_key) == key_type: + return raw_key + if raw_key is String: + var key_str := raw_key as String + match key_type: + TYPE_STRING_NAME: + return StringName(key_str) + TYPE_INT: + if key_str.is_valid_int(): + return int(key_str) + TYPE_FLOAT: + if key_str.is_valid_float(): + return float(key_str) + ## String key that didn't parse: JSON object keys are ALWAYS strings, + ## so blaming the String-ness would imply the caller could somehow + ## send a non-string key — name the expected key type instead. + var parse_err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "key does not parse as %s (the %s key type)" % [type_string(key_type), label], + ) + return ErrorCodes.prefix_message(parse_err, key_prefix) + if raw_key is float and key_type == TYPE_INT and is_equal_approx(raw_key, roundf(raw_key)): + ## Whole JSON numbers arrive as floats through some non-JSON callers. + return int(raw_key) + var err := ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "cannot use %s as a %s key" % [type_string(typeof(raw_key)), label], + ) + return ErrorCodes.prefix_message(err, key_prefix) + + +## "Dictionary[String, int]" / "Dictionary[int, Texture2D]" — for error +## messages. Untyped sides read as Variant. +static func _typed_dictionary_label(slot_value: Dictionary) -> String: + var key_label := "Variant" + if slot_value.is_typed_key(): + key_label = ( + _object_type_label( + slot_value.get_typed_key_class_name(), slot_value.get_typed_key_script() + ) + if slot_value.get_typed_key_builtin() == TYPE_OBJECT + else type_string(slot_value.get_typed_key_builtin()) + ) + var value_label := "Variant" + if slot_value.is_typed_value(): + value_label = ( + _object_type_label( + slot_value.get_typed_value_class_name(), slot_value.get_typed_value_script() + ) + if slot_value.get_typed_value_builtin() == TYPE_OBJECT + else type_string(slot_value.get_typed_value_builtin()) + ) + return "Dictionary[%s, %s]" % [key_label, value_label] + + +## Class/script display name for an object-typed constraint side. +static func _object_type_label(cls_name: StringName, script: Variant) -> String: + var cls := String(cls_name) + if script is Script and not String((script as Script).get_global_name()).is_empty(): + cls = String((script as Script).get_global_name()) + return cls if not cls.is_empty() else "Object" + + +func get_node_properties(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + # Optional token-reducing filter: `fields` restricts the response to a + # named subset. Defaults off (empty), so existing callers see the full + # dump unchanged. The MCP tool types this as a list, but batch_execute and + # raw callers bypass that, so validate the shape here before iterating. + var fields_param: Variant = params.get("fields", []) + if fields_param == null: + fields_param = [] + if not (fields_param is Array): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "'fields' must be an array of property names, got %s (%s)" % [ + type_string(typeof(fields_param)), str(fields_param), + ], + ) + var field_filter := {} + for f in fields_param: + ## Property names are strings on the wire; anything else is a + ## malformed filter (e.g. [123] or [["fov"]]) — reject rather than + ## silently stringify into a filter that matches nothing (#123/#126: + ## strict within the accepted shape). StringName is allowed for + ## editor-side callers. + if not (f is String or f is StringName): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "'fields' elements must be property-name strings, got %s in %s" % [ + type_string(typeof(f)), str(fields_param), + ], + ) + field_filter[str(f)] = true + var use_field_filter := not field_filter.is_empty() + + var properties: Array[Dictionary] = [] + var editor_property_count := 0 + var matched_fields := {} + for prop in node.get_property_list(): + var usage: int = prop.get("usage", 0) + if not (usage & PROPERTY_USAGE_EDITOR): + continue + editor_property_count += 1 + if use_field_filter: + if not field_filter.has(prop.name): + continue + matched_fields[prop.name] = true + # Null reads are values, not omissions: `script` on an unscripted node + # and unset Resource slots (mesh, material, …) read back null and must + # appear as "value": null with their declared type, so callers can tell + # "Object-typed, currently unset" from "doesn't exist" (#771). + properties.append({ + "name": prop.name, + "type": type_string(prop.type), + "value": _serialize_value(node.get(prop.name)), + }) + # Requested names that matched no editor-visible property — distinguishes + # "you asked for something that doesn't exist" from "exists and is null". + var unknown_fields: Array[String] = [] + for f in field_filter: + if not matched_fields.has(f): + unknown_fields.append(f) + return { + "data": { + "path": node_path, + "node_type": node.get_class(), + "properties": properties, + "count": properties.size(), + # Total editor-visible properties before field filtering, so a + # caller that passed `fields` knows how many were withheld. + # Invariant: an unfiltered call returns every editor-visible + # property, so count == total_count; only the `fields` filter + # can make count < total_count. + "total_count": editor_property_count, + "unknown_fields": unknown_fields, + } + } + + +func get_children(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var scene_root: Node = resolved.scene_root + + var children: Array[Dictionary] = [] + for child in node.get_children(): + children.append({ + "name": child.name, + "type": child.get_class(), + "path": McpScenePath.from_node(child, scene_root), + "children_count": child.get_child_count(), + }) + return { + "data": { + "parent_path": node_path, + "children": children, + "count": children.size(), + } + } + + +func get_groups(params: Dictionary) -> Dictionary: + var resolved := _resolve_node(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + + var groups: Array[String] = [] + for group in node.get_groups(): + # Skip internal groups (start with underscore) + if not str(group).begins_with("_"): + groups.append(str(group)) + return { + "data": { + "path": node_path, + "groups": groups, + "count": groups.size(), + } + } + + +## Validate path param, resolve to node. Returns dict with node/path/scene_root +## on success, or an error dict (has "error" key) on failure. Thin wrapper +## around the shared `McpNodeValidator.resolve_or_error` helper (audit-v2 #20). +func _resolve_node(params: Dictionary) -> Dictionary: + return McpNodeValidator.resolve_or_error( + params.get("path", ""), "path", params.get("scene_file", ""), + ) + + +## Reject operations targeting the scene root. Returns an INVALID_PARAMS error +## dict with "Cannot the scene root", or null if `node` is not the root. +static func _reject_if_scene_root(node: Node, scene_root: Node, op: String) -> Variant: + if node == scene_root: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Cannot %s the scene root" % op) + return null + + +## Convert a Godot Variant to a JSON-safe value. Compound geometry types +## (AABB, Rect2, Transforms, …) and packed arrays serialize as structured +## dicts/arrays so agents can inspect fields instead of parsing Godot's +## debug repr — see issue #214. +static func _serialize_value(value: Variant) -> Variant: + return VariantSerializer.serialize(value) diff --git a/addons/godot_ai/handlers/node_handler.gd.uid b/addons/godot_ai/handlers/node_handler.gd.uid new file mode 100644 index 0000000..86149b4 --- /dev/null +++ b/addons/godot_ai/handlers/node_handler.gd.uid @@ -0,0 +1 @@ +uid://qhhd5mm5awym diff --git a/addons/godot_ai/handlers/particle_handler.gd b/addons/godot_ai/handlers/particle_handler.gd new file mode 100644 index 0000000..5604355 --- /dev/null +++ b/addons/godot_ai/handlers/particle_handler.gd @@ -0,0 +1,860 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles particle emitter authoring (GPU + CPU, 2D + 3D). +## +## All write operations bundle node creation and sub-resource spawns +## (ParticleProcessMaterial, default QuadMesh) in a single create_action +## so Ctrl-Z rolls back the whole effect atomically. + +const ParticleValues := preload("res://addons/godot_ai/handlers/particle_values.gd") +const ParticlePresets := preload("res://addons/godot_ai/handlers/particle_presets.gd") + +const _VALID_TYPES := { + "gpu_3d": "GPUParticles3D", + "gpu_2d": "GPUParticles2D", + "cpu_3d": "CPUParticles3D", + "cpu_2d": "CPUParticles2D", +} + +const _MAIN_KEYS := [ + "amount", + "lifetime", + "one_shot", + "explosiveness", + "preprocess", + "speed_scale", + "randomness", + "fixed_fps", + "emitting", + "local_coords", + "interp_to_end", +] + + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +# ============================================================================ +# particle_create +# ============================================================================ + +func create_particle(params: Dictionary) -> Dictionary: + var parent_path: String = params.get("parent_path", "") + var node_name: String = params.get("name", "Particles") + var type_str: String = params.get("type", "gpu_3d") + + if not _VALID_TYPES.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid particle type '%s'. Valid: %s" % [type_str, ", ".join(_VALID_TYPES.keys())] + ) + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + var node := _instantiate_particle(type_str) + if node == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate particle node") + if not node_name.is_empty(): + node.name = node_name + + var process_mat: ParticleProcessMaterial = null + var process_material_created := false + var draw_mesh: Mesh = null + var draw_material: StandardMaterial3D = null + var draw_pass_mesh_created := false + var draw_material_created := false + + if type_str == "gpu_3d" or type_str == "gpu_2d": + process_mat = ParticleProcessMaterial.new() + process_material_created = true + if type_str == "gpu_3d": + draw_mesh = QuadMesh.new() + (draw_mesh as QuadMesh).size = Vector2(0.25, 0.25) + # Without a material, the mesh renders flat white — ignoring + # ParticleProcessMaterial.color_ramp entirely. Give it the standard + # billboard + vertex-color-as-albedo setup so color_ramp works. + draw_material = ParticleValues.build_draw_material({}).material + (draw_mesh as QuadMesh).material = draw_material + draw_pass_mesh_created = true + draw_material_created = true + + _undo_redo.create_action("MCP: Create %s '%s'" % [_VALID_TYPES[type_str], node.name]) + _undo_redo.add_do_method(parent, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + if process_mat != null: + _undo_redo.add_do_property(node, "process_material", process_mat) + _undo_redo.add_do_reference(process_mat) + if draw_mesh != null: + _undo_redo.add_do_property(node, "draw_pass_1", draw_mesh) + _undo_redo.add_do_reference(draw_mesh) + if draw_material != null: + _undo_redo.add_do_reference(draw_material) + _undo_redo.add_do_reference(node) + _undo_redo.add_undo_method(parent, "remove_child", node) + _undo_redo.commit_action() + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "parent_path": McpScenePath.from_node(parent, scene_root), + "name": String(node.name), + "type": type_str, + "class": _VALID_TYPES[type_str], + "process_material_created": process_material_created, + "draw_pass_mesh_created": draw_pass_mesh_created, + "draw_material_created": draw_material_created, + "undoable": true, + } + } + + +# ============================================================================ +# particle_set_main +# ============================================================================ + +func set_main(params: Dictionary) -> Dictionary: + var resolved := _resolve_particle(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + + var properties: Dictionary = params.get("properties", {}) + if properties.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "properties dict is empty") + + var coerced: Dictionary = {} + var old_values: Dictionary = {} + for property in properties: + var prop_name: String = String(property) + if not (prop_name in _MAIN_KEYS): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Unknown main property '%s'. Valid: %s" % [prop_name, ", ".join(_MAIN_KEYS)] + ) + var prop_type := _node_property_type(node, prop_name) + if prop_type == TYPE_NIL: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Property '%s' not present on %s" % [prop_name, node.get_class()] + ) + var coerce_result := ParticleValues.coerce(prop_name, properties[prop_name], prop_type) + if not coerce_result.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerce_result.error)) + coerced[prop_name] = coerce_result.value + old_values[prop_name] = node.get(prop_name) + + _undo_redo.create_action("MCP: Set particle main on %s" % node.name) + for prop_name in coerced: + _undo_redo.add_do_property(node, prop_name, coerced[prop_name]) + _undo_redo.add_undo_property(node, prop_name, old_values[prop_name]) + _undo_redo.commit_action() + + var applied: Array[String] = [] + var serialized_values: Dictionary = {} + for prop_name in coerced: + applied.append(prop_name) + serialized_values[prop_name] = ParticleValues.serialize(coerced[prop_name]) + + return { + "data": { + "path": node_path, + "applied": applied, + "values": serialized_values, + "undoable": true, + } + } + + +# ============================================================================ +# particle_set_process +# ============================================================================ + +func set_process(params: Dictionary) -> Dictionary: + var resolved := _resolve_particle(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + + var properties: Dictionary = params.get("properties", {}) + if properties.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "properties dict is empty") + + # GPU: work through process_material; CPU: properties live on node directly. + if node is GPUParticles3D or node is GPUParticles2D: + return _set_process_gpu(node, node_path, properties) + return _set_process_cpu(node, node_path, properties) + + +func _set_process_gpu(node: Node, node_path: String, properties: Dictionary) -> Dictionary: + var existing_mat: ParticleProcessMaterial = node.process_material as ParticleProcessMaterial + var process_material_created := false + var mat: ParticleProcessMaterial = existing_mat + if mat == null: + mat = ParticleProcessMaterial.new() + process_material_created = true + + var coerced: Dictionary = {} + for property in properties: + var prop_name: String = String(property) + var prop_type := _object_property_type(mat, prop_name) + if prop_type == TYPE_NIL: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Property '%s' not present on ParticleProcessMaterial" % prop_name + ) + var coerce_result := ParticleValues.coerce(prop_name, properties[prop_name], prop_type) + if not coerce_result.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerce_result.error)) + coerced[prop_name] = coerce_result.value + + _undo_redo.create_action("MCP: Set particle process on %s" % node.name) + if process_material_created: + _undo_redo.add_do_property(node, "process_material", mat) + _undo_redo.add_undo_property(node, "process_material", null) + _undo_redo.add_do_reference(mat) + # Apply new values directly on the (newly created) material. No old values to restore. + for prop_name in coerced: + mat.set(prop_name, coerced[prop_name]) + else: + # Use the reusable apply/restore pattern for existing material. + var old_values: Dictionary = {} + for prop_name in coerced: + old_values[prop_name] = mat.get(prop_name) + for prop_name in coerced: + _undo_redo.add_do_property(mat, prop_name, coerced[prop_name]) + _undo_redo.add_undo_property(mat, prop_name, old_values[prop_name]) + _undo_redo.commit_action() + + var applied: Array[String] = [] + var serialized: Dictionary = {} + for prop_name in coerced: + applied.append(prop_name) + serialized[prop_name] = ParticleValues.serialize(mat.get(prop_name)) + + return { + "data": { + "path": node_path, + "applied": applied, + "values": serialized, + "process_material_created": process_material_created, + "undoable": true, + } + } + + +func _set_process_cpu(node: Node, node_path: String, properties: Dictionary) -> Dictionary: + # CPU particles expose the same property vocabulary directly on the node, + # so property names pass through unchanged. + var coerced: Dictionary = {} + var old_values: Dictionary = {} + + for property in properties: + var prop_name: String = String(property) + var prop_type := _node_property_type(node, prop_name) + if prop_type == TYPE_NIL: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Property '%s' not present on %s" % [prop_name, node.get_class()] + ) + var coerce_result := ParticleValues.coerce(prop_name, properties[property], prop_type) + if not coerce_result.ok: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerce_result.error)) + coerced[prop_name] = coerce_result.value + old_values[prop_name] = node.get(prop_name) + + _undo_redo.create_action("MCP: Set particle process on %s" % node.name) + for prop_name in coerced: + _undo_redo.add_do_property(node, prop_name, coerced[prop_name]) + _undo_redo.add_undo_property(node, prop_name, old_values[prop_name]) + _undo_redo.commit_action() + + var applied: Array[String] = [] + var serialized: Dictionary = {} + for prop_name in coerced: + applied.append(prop_name) + serialized[prop_name] = ParticleValues.serialize(coerced[prop_name]) + + return { + "data": { + "path": node_path, + "applied": applied, + "values": serialized, + "process_material_created": false, + "undoable": true, + } + } + + +# ============================================================================ +# particle_set_draw_pass +# ============================================================================ + +func set_draw_pass(params: Dictionary) -> Dictionary: + var resolved := _resolve_particle(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + + var pass_idx: int = int(params.get("pass", 1)) + var mesh_path: String = params.get("mesh", "") + var texture_path: String = params.get("texture", "") + var material_path: String = params.get("material", "") + + if node is GPUParticles3D: + return _set_draw_pass_gpu_3d(node, node_path, pass_idx, mesh_path, material_path) + if node is CPUParticles3D: + return _set_draw_pass_cpu_3d(node, node_path, mesh_path, material_path) + if node is GPUParticles2D or node is CPUParticles2D: + return _set_draw_pass_2d(node, node_path, texture_path) + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Node %s is not a particle node" % node.get_class()) + + +func _set_draw_pass_gpu_3d(node: GPUParticles3D, node_path: String, pass_idx: int, mesh_path: String, material_path: String) -> Dictionary: + if pass_idx < 1 or pass_idx > 4: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "pass must be 1..4 (got %d)" % pass_idx) + + var mesh: Mesh = null + var mesh_created := false + var property_name := "draw_pass_%d" % pass_idx + # draw_pass_N is only a live property when draw_passes >= N. Probe via + # get_property_list so we don't read a ghost value. + var existing_mesh: Mesh = null + if int(node.draw_passes) >= pass_idx: + existing_mesh = node.get(property_name) as Mesh + if not mesh_path.is_empty(): + var mesh_path_err = McpPathValidator.loadable_error(mesh_path, "mesh_path") + if mesh_path_err != null: + return mesh_path_err + if not ResourceLoader.exists(mesh_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Mesh not found: %s" % mesh_path) + var loaded := ResourceLoader.load(mesh_path) + if not (loaded is Mesh): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Mesh" % mesh_path) + mesh = loaded + else: + if existing_mesh == null: + mesh = QuadMesh.new() + (mesh as QuadMesh).size = Vector2(0.25, 0.25) + mesh_created = true + else: + mesh = existing_mesh + + var material: Material = null + if not material_path.is_empty(): + var material_path_err = McpPathValidator.loadable_error(material_path, "material_path") + if material_path_err != null: + return material_path_err + if not ResourceLoader.exists(material_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Material not found: %s" % material_path) + var loaded_mat := ResourceLoader.load(material_path) + if not (loaded_mat is Material): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Material" % material_path) + material = loaded_mat + + var old_draw_passes: int = int(node.draw_passes) + var new_draw_passes: int = max(old_draw_passes, pass_idx) + var old_value = existing_mesh # Null if draw_passes < pass_idx + var old_material: Material = null + if material != null: + old_material = node.material_override + + _undo_redo.create_action("MCP: Set %s.draw_pass_%d" % [node.name, pass_idx]) + # Grow draw_passes first so draw_pass_N property exists before we set it. + if new_draw_passes != old_draw_passes: + _undo_redo.add_do_property(node, "draw_passes", new_draw_passes) + _undo_redo.add_undo_property(node, "draw_passes", old_draw_passes) + if not mesh_path.is_empty() or mesh_created: + _undo_redo.add_do_property(node, property_name, mesh) + _undo_redo.add_undo_property(node, property_name, old_value) + if mesh_created: + _undo_redo.add_do_reference(mesh) + if material != null: + _undo_redo.add_do_property(node, "material_override", material) + _undo_redo.add_undo_property(node, "material_override", old_material) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "pass": pass_idx, + "mesh_path": mesh_path, + "mesh_class": mesh.get_class() if mesh else "", + "material_path": material_path, + "draw_pass_mesh_created": mesh_created, + "draw_passes_grown": new_draw_passes != old_draw_passes, + "undoable": true, + } + } + + +func _set_draw_pass_cpu_3d(node: CPUParticles3D, node_path: String, mesh_path: String, material_path: String) -> Dictionary: + if mesh_path.is_empty() and material_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "CPUParticles3D requires mesh or material param") + + var mesh: Mesh = node.mesh + var old_mesh: Mesh = mesh + if not mesh_path.is_empty(): + var mesh_path_err = McpPathValidator.loadable_error(mesh_path, "mesh_path") + if mesh_path_err != null: + return mesh_path_err + if not ResourceLoader.exists(mesh_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Mesh not found: %s" % mesh_path) + var loaded := ResourceLoader.load(mesh_path) + if not (loaded is Mesh): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Mesh" % mesh_path) + mesh = loaded + + var material: Material = null + var old_material: Material = node.material_override + if not material_path.is_empty(): + var material_path_err = McpPathValidator.loadable_error(material_path, "material_path") + if material_path_err != null: + return material_path_err + if not ResourceLoader.exists(material_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Material not found: %s" % material_path) + var loaded_mat := ResourceLoader.load(material_path) + if not (loaded_mat is Material): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Material" % material_path) + material = loaded_mat + + _undo_redo.create_action("MCP: Set CPU particle draw on %s" % node.name) + if not mesh_path.is_empty(): + _undo_redo.add_do_property(node, "mesh", mesh) + _undo_redo.add_undo_property(node, "mesh", old_mesh) + if material != null: + _undo_redo.add_do_property(node, "material_override", material) + _undo_redo.add_undo_property(node, "material_override", old_material) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "mesh_path": mesh_path, + "material_path": material_path, + "draw_pass_mesh_created": false, + "undoable": true, + } + } + + +func _set_draw_pass_2d(node: Node, node_path: String, texture_path: String) -> Dictionary: + if texture_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "2D particles require texture param") + var texture_path_err = McpPathValidator.loadable_error(texture_path, "texture_path") + if texture_path_err != null: + return texture_path_err + if not ResourceLoader.exists(texture_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Texture not found: %s" % texture_path) + var tex := ResourceLoader.load(texture_path) + if not (tex is Texture2D): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Texture2D" % texture_path) + + var old_texture: Texture2D = node.get("texture") + + _undo_redo.create_action("MCP: Set 2D particle texture on %s" % node.name) + _undo_redo.add_do_property(node, "texture", tex) + _undo_redo.add_undo_property(node, "texture", old_texture) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "texture_path": texture_path, + "undoable": true, + } + } + + +# ============================================================================ +# particle_restart +# ============================================================================ + +func restart_particle(params: Dictionary) -> Dictionary: + var resolved := _resolve_particle(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + if node.has_method("restart"): + node.restart() + return { + "data": { + "path": node_path, + "undoable": false, + "reason": "Restart is a runtime operation, not tracked in undo history", + } + } + + +# ============================================================================ +# particle_get +# ============================================================================ + +func get_particle(params: Dictionary) -> Dictionary: + var resolved := _resolve_particle(params) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + + var type_str := "" + for key in _VALID_TYPES: + if node.get_class() == _VALID_TYPES[key]: + type_str = key + break + + var main_values: Dictionary = {} + var node_prop_names := _property_names(node) + for key in _MAIN_KEYS: + if node_prop_names.has(key): + main_values[key] = ParticleValues.serialize(node.get(key)) + + var process_data: Dictionary = {} + if node is GPUParticles3D or node is GPUParticles2D: + var mat: ParticleProcessMaterial = node.process_material as ParticleProcessMaterial + if mat != null: + var process_props: Dictionary = {} + for prop in mat.get_property_list(): + var usage: int = prop.get("usage", 0) + if not (usage & PROPERTY_USAGE_EDITOR): + continue + var v = mat.get(prop.name) + if v == null: + continue + process_props[prop.name] = ParticleValues.serialize(v) + process_data = { + "class": "ParticleProcessMaterial", + "properties": process_props, + } + + var draw_passes: Array[Dictionary] = [] + if node is GPUParticles3D: + var active_draw_pass_count: int = min(int(node.draw_passes), 4) + for i in range(1, active_draw_pass_count + 1): + var prop_name := "draw_pass_%d" % i + var m: Mesh = node.get(prop_name) as Mesh + draw_passes.append({ + "pass": i, + "mesh_class": m.get_class() if m != null else "", + }) + + var texture_path := "" + if node is GPUParticles2D or node is CPUParticles2D: + var t: Texture2D = node.get("texture") + if t != null: + texture_path = t.resource_path + + return { + "data": { + "path": node_path, + "type": type_str, + "class": node.get_class(), + "main": main_values, + "process": process_data, + "draw_passes": draw_passes, + "texture_path": texture_path, + } + } + + +# ============================================================================ +# particle_apply_preset +# ============================================================================ + +func apply_preset(params: Dictionary) -> Dictionary: + var preset_name: String = params.get("preset", "") + if preset_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: preset") + + var overrides: Dictionary = params.get("overrides", {}) + var blueprint = ParticlePresets.build(preset_name, overrides) + if blueprint == null: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown preset '%s'. Valid: %s" % [preset_name, ", ".join(ParticlePresets.list())] + ) + + var parent_path: String = params.get("parent_path", "") + var node_name: String = params.get("name", "") + var type_str: String = params.get("type", "gpu_3d") + if node_name.is_empty(): + node_name = preset_name.capitalize() + if not _VALID_TYPES.has(type_str): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid particle type '%s'. Valid: %s" % [type_str, ", ".join(_VALID_TYPES.keys())] + ) + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var parent: Node = scene_root + if not parent_path.is_empty(): + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + var node := _instantiate_particle(type_str) + node.name = node_name + + var is_gpu := type_str == "gpu_3d" or type_str == "gpu_2d" + var is_3d := type_str == "gpu_3d" or type_str == "cpu_3d" + + var process_mat: ParticleProcessMaterial = null + var process_material_created := false + if is_gpu: + process_mat = ParticleProcessMaterial.new() + process_material_created = true + + # User-supplied override keys per group. Preset-blueprint keys may skip + # silently on types they don't apply to (presets are cross-type by + # design); user-requested overrides must apply or error (#770). + var user_keys: Dictionary = blueprint.get("user_keys", {}) + var user_main: Dictionary = user_keys.get("main", {}) + var user_process: Dictionary = user_keys.get("process", {}) + var user_draw: Dictionary = user_keys.get("draw", {}) + + var draw_mesh: Mesh = null + var draw_material: StandardMaterial3D = null + var draw_pass_mesh_created := false + var draw_material_created := false + var applied_draw: Array[String] = [] + var draw_config: Dictionary = blueprint.get("draw", {}) + if type_str == "gpu_3d": + var draw_result := ParticleValues.build_draw_material(draw_config) + if not draw_result.ok: + node.free() + var msg := String(draw_result.error) + if draw_result.get("unknown_key", false): + msg = _draw_key_unsupported_message(String(draw_result.key), type_str) + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, msg) + draw_mesh = QuadMesh.new() + (draw_mesh as QuadMesh).size = Vector2(0.25, 0.25) + draw_material = draw_result.material + (draw_mesh as QuadMesh).material = draw_material + draw_pass_mesh_created = true + draw_material_created = true + for applied_key in draw_result.applied: + applied_draw.append(String(applied_key)) + elif type_str == "gpu_2d": + # GPUParticles2D has no draw-pass material; the one draw override it + # supports is draw.texture → the node's texture property. + for key in user_draw: + if String(key) != "texture": + node.free() + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + _draw_key_unsupported_message(String(key), type_str) + ) + if user_draw.has("texture"): + var tex_result := _load_draw_texture(draw_config.get("texture")) + if tex_result.has("error"): + node.free() + return tex_result + node.set("texture", tex_result.texture) + applied_draw.append("texture") + else: + # cpu_3d / cpu_2d: no draw support — reject user draw overrides + # instead of dropping them. + for key in user_draw: + node.free() + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + _draw_key_unsupported_message(String(key), type_str) + ) + + # Pre-apply preset values to in-memory targets (no undo needed; nodes not in tree yet). + var main_values: Dictionary = blueprint.get("main", {}) + var process_values: Dictionary = blueprint.get("process", {}) + var applied_main: Array[String] = [] + var applied_process: Array[String] = [] + + for prop in main_values: + var prop_name := String(prop) + var prop_type := _object_property_type(node, prop_name) + if prop_type == TYPE_NIL: + if user_main.has(prop_name): + var node_class := node.get_class() + node.free() + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Override main.%s does not apply to type '%s' (no such property on %s)" % [ + prop_name, type_str, node_class + ] + ) + continue # Blueprint key: not all main keys apply to all types. + var coerce_result := ParticleValues.coerce(prop_name, main_values[prop_name], prop_type) + if not coerce_result.ok: + node.free() + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerce_result.error)) + node.set(prop_name, coerce_result.value) + applied_main.append(prop_name) + + # Apply process: GPU targets the ParticleProcessMaterial; CPU targets the node. + var process_target: Object = process_mat if is_gpu else node + for prop in process_values: + var prop_name := String(prop) + var prop_type := _object_property_type(process_target, prop_name) + if prop_type == TYPE_NIL: + if user_process.has(prop_name): + var target_class := process_target.get_class() + node.free() + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Override process.%s does not apply to type '%s' (no such property on %s)" % [ + prop_name, type_str, target_class + ] + ) + continue # Blueprint key: preset property doesn't apply to this variant. + var coerce_result := ParticleValues.coerce(prop_name, process_values[prop_name], prop_type) + if not coerce_result.ok: + node.free() + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, String(coerce_result.error)) + process_target.set(prop_name, coerce_result.value) + applied_process.append(prop_name) + + _undo_redo.create_action("MCP: Apply preset %s" % preset_name) + _undo_redo.add_do_method(parent, "add_child", node, true) + _undo_redo.add_do_method(node, "set_owner", scene_root) + _undo_redo.add_do_reference(node) + if process_mat != null: + _undo_redo.add_do_property(node, "process_material", process_mat) + _undo_redo.add_do_reference(process_mat) + if draw_mesh != null: + _undo_redo.add_do_property(node, "draw_pass_1", draw_mesh) + _undo_redo.add_do_reference(draw_mesh) + if draw_material != null: + _undo_redo.add_do_reference(draw_material) + _undo_redo.add_undo_method(parent, "remove_child", node) + _undo_redo.commit_action() + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "parent_path": McpScenePath.from_node(parent, scene_root), + "name": node_name, + "preset": preset_name, + "type": type_str, + "class": _VALID_TYPES[type_str], + "applied_main": applied_main, + "applied_process": applied_process, + "applied_draw": applied_draw, + "process_material_created": process_material_created, + "draw_pass_mesh_created": draw_pass_mesh_created, + "draw_material_created": draw_material_created, + "is_3d": is_3d, + "undoable": true, + } + } + + +# ============================================================================ +# Helpers +# ============================================================================ + +## Actionable rejection for a user draw override that can't apply to the +## selected particle type: name the key and where it IS supported. +static func _draw_key_unsupported_message(key: String, type_str: String) -> String: + if key == "texture": + return "draw.texture is only supported for gpu_2d (got type '%s')" % type_str + var probe := StandardMaterial3D.new() + if _object_property_type(probe, key) != TYPE_NIL: + return "draw.%s is only supported for gpu_3d (got type '%s')" % [key, type_str] + return ( + "Unknown draw key '%s' (draw overrides configure the gpu_3d " + + "draw-pass StandardMaterial3D; gpu_2d supports only draw.texture)" + ) % key + + +## Load a Texture2D for the gpu_2d draw.texture override. Returns +## {texture: Texture2D} or an error dict (same validation as set_draw_pass). +static func _load_draw_texture(value: Variant) -> Dictionary: + if not (value is String) or String(value).is_empty(): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "draw.texture must be a non-empty res:// path string (got %s)" % type_string(typeof(value)) + ) + var texture_path := String(value) + var texture_path_err = McpPathValidator.loadable_error(texture_path, "draw.texture") + if texture_path_err != null: + return texture_path_err + if not ResourceLoader.exists(texture_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Texture not found: %s" % texture_path) + var tex := ResourceLoader.load(texture_path) + if not (tex is Texture2D): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Texture2D" % texture_path) + return {"texture": tex} + + +static func _instantiate_particle(type_str: String) -> Node: + match type_str: + "gpu_3d": + return GPUParticles3D.new() + "gpu_2d": + return GPUParticles2D.new() + "cpu_3d": + return CPUParticles3D.new() + "cpu_2d": + return CPUParticles2D.new() + return null + + +func _resolve_particle(params: Dictionary) -> Dictionary: + var resolved := McpNodeValidator.resolve_or_error( + params.get("node_path", ""), "node_path", + ) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + var node_path: String = resolved.path + var is_particle := node is GPUParticles3D or node is GPUParticles2D \ + or node is CPUParticles3D or node is CPUParticles2D + if not is_particle: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node %s is not a particle node (got %s)" % [node_path, node.get_class()] + ) + return {"node": node, "path": node_path} + + +static func _node_property_type(node: Object, name: String) -> int: + return _object_property_type(node, name) + + +static func _object_property_type(obj: Object, name: String) -> int: + if obj == null: + return TYPE_NIL + for prop in obj.get_property_list(): + if prop.name == name: + return int(prop.get("type", TYPE_NIL)) + return TYPE_NIL + + +static func _property_names(obj: Object) -> Dictionary: + var out: Dictionary = {} + if obj == null: + return out + for prop in obj.get_property_list(): + out[prop.name] = true + return out diff --git a/addons/godot_ai/handlers/particle_handler.gd.uid b/addons/godot_ai/handlers/particle_handler.gd.uid new file mode 100644 index 0000000..ead3722 --- /dev/null +++ b/addons/godot_ai/handlers/particle_handler.gd.uid @@ -0,0 +1 @@ +uid://byfc0pnyb5qww diff --git a/addons/godot_ai/handlers/particle_presets.gd b/addons/godot_ai/handlers/particle_presets.gd new file mode 100644 index 0000000..3bbf1f4 --- /dev/null +++ b/addons/godot_ai/handlers/particle_presets.gd @@ -0,0 +1,293 @@ +@tool +extends RefCounted + +## Curated particle effect blueprints. +## +## Each preset returns {main, process, draw}. The handler applies them +## through the normal write path (one undo action wraps all spawns). + + +## Each preset has {main, process, draw}. `draw` configures the StandardMaterial3D +## attached to the auto-created QuadMesh in draw_pass_1 (GPU 3D only); if +## omitted, the handler falls back to a sensible billboard-particles default. +## `blend_mode: "add"` is what makes fire/magic/explosion glow — without +## additive blending, additively-layered particles just stack to gray. +const _PRESETS := { + "fire": { + "main": { + "amount": 80, + "lifetime": 1.2, + "one_shot": false, + "explosiveness": 0.0, + "preprocess": 0.5, + "local_coords": false, + }, + "process": { + "emission_shape": "sphere", + "emission_sphere_radius": 0.3, + "direction": {"x": 0.0, "y": 1.0, "z": 0.0}, + "spread": 15.0, + "initial_velocity_min": 2.0, + "initial_velocity_max": 4.0, + "gravity": {"x": 0.0, "y": 1.0, "z": 0.0}, # buoyancy + "scale_min": 0.4, + "scale_max": 0.8, + "color_ramp": { + "stops": [ + {"time": 0.0, "color": [1.0, 1.0, 0.9, 1.0]}, + {"time": 0.3, "color": [1.0, 0.6, 0.1, 1.0]}, + {"time": 0.7, "color": [0.8, 0.1, 0.05, 0.7]}, + {"time": 1.0, "color": [0.2, 0.05, 0.05, 0.0]}, + ] + }, + }, + "draw": {"blend_mode": "add"}, + }, + "smoke": { + "main": { + "amount": 40, + "lifetime": 3.0, + "one_shot": false, + "explosiveness": 0.0, + "local_coords": false, + }, + "process": { + "emission_shape": "sphere", + "emission_sphere_radius": 0.4, + "direction": {"x": 0.0, "y": 1.0, "z": 0.0}, + "spread": 20.0, + "initial_velocity_min": 0.5, + "initial_velocity_max": 1.5, + "gravity": {"x": 0.0, "y": 0.2, "z": 0.0}, + "scale_min": 0.6, + "scale_max": 1.4, + "color_ramp": { + "stops": [ + {"time": 0.0, "color": [0.3, 0.3, 0.3, 0.0]}, + {"time": 0.25, "color": [0.35, 0.35, 0.35, 0.7]}, + {"time": 0.75, "color": [0.2, 0.2, 0.2, 0.5]}, + {"time": 1.0, "color": [0.1, 0.1, 0.1, 0.0]}, + ] + }, + }, + # Smoke uses regular alpha blending so it darkens the background. + "draw": {"blend_mode": "mix"}, + }, + "spark_burst": { + "main": { + "amount": 60, + "lifetime": 0.8, + "one_shot": true, + "explosiveness": 1.0, + "local_coords": false, + }, + "process": { + "emission_shape": "point", + "direction": {"x": 0.0, "y": 1.0, "z": 0.0}, + "spread": 180.0, + "initial_velocity_min": 5.0, + "initial_velocity_max": 12.0, + "gravity": {"x": 0.0, "y": -9.8, "z": 0.0}, + "scale_min": 0.05, + "scale_max": 0.12, + "color": {"r": 1.0, "g": 0.9, "b": 0.2, "a": 1.0}, + }, + "draw": { + "blend_mode": "add", + "emission_enabled": true, + "emission": {"r": 1.0, "g": 0.8, "b": 0.2, "a": 1.0}, + "emission_energy_multiplier": 2.0, + }, + }, + "magic_swirl": { + "main": { + "amount": 120, + "lifetime": 2.0, + "one_shot": false, + "explosiveness": 0.0, + "local_coords": false, + }, + "process": { + "emission_shape": "ring", + "emission_ring_radius": 0.8, + "emission_ring_inner_radius": 0.6, + "emission_ring_height": 0.0, + "direction": {"x": 0.0, "y": 1.0, "z": 0.0}, + "spread": 30.0, + "initial_velocity_min": 1.0, + "initial_velocity_max": 2.0, + "gravity": {"x": 0.0, "y": 0.0, "z": 0.0}, + "angular_velocity_min": 90.0, + "angular_velocity_max": 180.0, + "scale_min": 0.1, + "scale_max": 0.2, + "color_ramp": { + "stops": [ + {"time": 0.0, "color": [0.4, 0.9, 1.0, 0.0]}, + {"time": 0.3, "color": [0.5, 0.7, 1.0, 1.0]}, + {"time": 0.7, "color": [1.0, 0.4, 0.9, 1.0]}, + {"time": 1.0, "color": [0.8, 0.2, 0.7, 0.0]}, + ] + }, + }, + "draw": {"blend_mode": "add"}, + }, + "rain": { + "main": { + "amount": 500, + "lifetime": 1.5, + "one_shot": false, + "explosiveness": 0.0, + "local_coords": false, + }, + "process": { + "emission_shape": "box", + "emission_box_extents": {"x": 10.0, "y": 0.1, "z": 10.0}, + "direction": {"x": 0.0, "y": -1.0, "z": 0.0}, + "spread": 2.0, + "initial_velocity_min": 15.0, + "initial_velocity_max": 18.0, + "gravity": {"x": 0.0, "y": -2.0, "z": 0.0}, + "scale_min": 0.02, + "scale_max": 0.04, + "color": {"r": 0.7, "g": 0.85, "b": 1.0, "a": 0.5}, + }, + # Rain drops render as streaks; fixed_y aligns them vertically. + "draw": {"billboard_mode": "fixed_y", "blend_mode": "mix"}, + }, + "explosion": { + "main": { + "amount": 200, + "lifetime": 1.5, + "one_shot": true, + "explosiveness": 1.0, + "local_coords": false, + }, + "process": { + "emission_shape": "sphere", + "emission_sphere_radius": 0.1, + "direction": {"x": 0.0, "y": 1.0, "z": 0.0}, + "spread": 180.0, + "initial_velocity_min": 6.0, + "initial_velocity_max": 10.0, + "gravity": {"x": 0.0, "y": -4.0, "z": 0.0}, + "scale_min": 0.3, + "scale_max": 0.7, + "color_ramp": { + "stops": [ + {"time": 0.0, "color": [1.0, 0.95, 0.5, 1.0]}, + {"time": 0.2, "color": [1.0, 0.4, 0.1, 1.0]}, + {"time": 0.7, "color": [0.3, 0.15, 0.1, 0.7]}, + {"time": 1.0, "color": [0.1, 0.1, 0.1, 0.0]}, + ] + }, + }, + "draw": { + "blend_mode": "add", + "emission_enabled": true, + "emission": {"r": 1.0, "g": 0.5, "b": 0.1, "a": 1.0}, + "emission_energy_multiplier": 1.5, + }, + }, + "lightning": { + # Short, bright, electric-blue spark burst. One-shot — call + # particle_restart to re-trigger. Pairs well with a scene-wide flash. + "main": { + "amount": 40, + "lifetime": 0.35, + "one_shot": true, + "explosiveness": 1.0, + "local_coords": false, + }, + "process": { + "emission_shape": "box", + "emission_box_extents": {"x": 0.1, "y": 1.5, "z": 0.1}, + "direction": {"x": 0.0, "y": -1.0, "z": 0.0}, + "spread": 8.0, + "initial_velocity_min": 18.0, + "initial_velocity_max": 28.0, + "gravity": {"x": 0.0, "y": 0.0, "z": 0.0}, + "scale_min": 0.08, + "scale_max": 0.18, + "color_ramp": { + "stops": [ + {"time": 0.0, "color": [1.0, 1.0, 1.0, 1.0]}, + {"time": 0.2, "color": [0.6, 0.85, 1.0, 1.0]}, + {"time": 0.6, "color": [0.3, 0.5, 1.0, 0.9]}, + {"time": 1.0, "color": [0.1, 0.2, 0.7, 0.0]}, + ] + }, + }, + "draw": { + "blend_mode": "add", + "emission_enabled": true, + "emission": {"r": 0.5, "g": 0.8, "b": 1.0, "a": 1.0}, + "emission_energy_multiplier": 4.0, + }, + }, +} + + +static func list() -> Array: + return _PRESETS.keys() + + +static func has(preset_name: String) -> bool: + return _PRESETS.has(preset_name) + + +## Return deep-copied {main, process, draw} blueprint with overrides merged in, +## plus "user_keys" ({main/process/draw: {key: true}}) recording which keys the +## caller supplied. The handler needs that distinction: preset-blueprint keys +## may skip silently on types they don't apply to (presets are cross-type by +## design), but user-requested overrides must apply or error (#770). +## Overrides may include top-level "main" / "process" / "draw" dicts, or bare +## keys routed to main (_MAIN_KEYS) or process — draw keys must be nested. +static func build(preset_name: String, overrides: Dictionary) -> Variant: + if not _PRESETS.has(preset_name): + return null + var entry: Dictionary = _PRESETS[preset_name].duplicate(true) + var main: Dictionary = entry.get("main", {}) + var process: Dictionary = entry.get("process", {}) + var draw: Dictionary = entry.get("draw", {}) + var user_keys := {"main": {}, "process": {}, "draw": {}} + for key in overrides: + var val = overrides[key] + if key == "main" and val is Dictionary: + for k in val: + main[k] = val[k] + user_keys.main[String(k)] = true + elif key == "process" and val is Dictionary: + for k in val: + process[k] = val[k] + user_keys.process[String(k)] = true + elif key == "draw" and val is Dictionary: + for k in val: + draw[k] = val[k] + user_keys.draw[String(k)] = true + elif _MAIN_KEYS.has(key): + main[key] = val + user_keys.main[String(key)] = true + else: + process[key] = val + user_keys.process[String(key)] = true + entry["main"] = main + entry["process"] = process + entry["draw"] = draw + entry["user_keys"] = user_keys + return entry + + +const _MAIN_KEYS := { + "amount": true, + "lifetime": true, + "one_shot": true, + "explosiveness": true, + "preprocess": true, + "speed_scale": true, + "randomness": true, + "fixed_fps": true, + "emitting": true, + "local_coords": true, + "interp_to_end": true, +} diff --git a/addons/godot_ai/handlers/particle_presets.gd.uid b/addons/godot_ai/handlers/particle_presets.gd.uid new file mode 100644 index 0000000..7c1aac9 --- /dev/null +++ b/addons/godot_ai/handlers/particle_presets.gd.uid @@ -0,0 +1 @@ +uid://bss2ccpmsxo4p diff --git a/addons/godot_ai/handlers/particle_values.gd b/addons/godot_ai/handlers/particle_values.gd new file mode 100644 index 0000000..66782f6 --- /dev/null +++ b/addons/godot_ai/handlers/particle_values.gd @@ -0,0 +1,246 @@ +@tool +extends RefCounted + +## Value coercion + gradient/curve builders for particle properties. + +const MaterialValues := preload("res://addons/godot_ai/handlers/material_values.gd") + +const _EMISSION_SHAPES := { + "point": ParticleProcessMaterial.EMISSION_SHAPE_POINT, + "sphere": ParticleProcessMaterial.EMISSION_SHAPE_SPHERE, + "sphere_surface": ParticleProcessMaterial.EMISSION_SHAPE_SPHERE_SURFACE, + "box": ParticleProcessMaterial.EMISSION_SHAPE_BOX, + "points": ParticleProcessMaterial.EMISSION_SHAPE_POINTS, + "directed_points": ParticleProcessMaterial.EMISSION_SHAPE_DIRECTED_POINTS, + "ring": ParticleProcessMaterial.EMISSION_SHAPE_RING, +} + + +## Resolve a shape name to the int enum, or return null. +static func resolve_emission_shape(value: Variant) -> Variant: + if value is int: + return value + if value is float: + return int(value) + if value is String: + var key := String(value).to_lower() + if _EMISSION_SHAPES.has(key): + return _EMISSION_SHAPES[key] + return null + + +static func emission_shape_names() -> Array: + return _EMISSION_SHAPES.keys() + + +## Build a Gradient from {stops: [{time, color}]} dict. +static func build_gradient(value: Variant) -> Variant: + if value is Gradient: + return value + if value is GradientTexture1D: + return (value as GradientTexture1D).gradient + if not (value is Dictionary): + return null + var d: Dictionary = value + if not d.has("stops"): + return null + var stops_array = d.get("stops") + if not (stops_array is Array): + return null + var offsets := PackedFloat32Array() + var colors := PackedColorArray() + for stop in stops_array: + if not (stop is Dictionary): + return null + offsets.append(float(stop.get("time", 0.0))) + var c = MaterialValues.parse_color(stop.get("color")) + if c == null: + return null + colors.append(c) + var grad := Gradient.new() + grad.offsets = offsets + grad.colors = colors + return grad + + +## Build a GradientTexture1D wrapping a Gradient (what ParticleProcessMaterial.color_ramp wants). +static func build_gradient_texture(value: Variant) -> Variant: + if value is GradientTexture1D: + return value + var grad = build_gradient(value) + if grad == null: + return null + var tex := GradientTexture1D.new() + tex.gradient = grad + return tex + + +## Build a Curve from [{time, value}] or {points: [...]} (float-over-time). +static func build_curve(value: Variant) -> Variant: + if value is Curve: + return value + if value is CurveTexture: + return (value as CurveTexture).curve + var points_array: Variant = null + if value is Array: + points_array = value + elif value is Dictionary and value.has("points"): + points_array = value["points"] + if not (points_array is Array): + return null + var curve := Curve.new() + for pt in points_array: + if not (pt is Dictionary): + return null + var t := float(pt.get("time", 0.0)) + var v := float(pt.get("value", 0.0)) + curve.add_point(Vector2(t, v)) + return curve + + +static func build_curve_texture(value: Variant) -> Variant: + if value is CurveTexture: + return value + var curve = build_curve(value) + if curve == null: + return null + var tex := CurveTexture.new() + tex.curve = curve + return tex + + +## Coerce a particle property value to the appropriate type. +## Handles: Vector3/gravity/direction, Color, float, int, bool, enum strings. +## For color_ramp returns a GradientTexture1D; for *_curve returns CurveTexture. +static func coerce(property: String, value: Variant, target_type: int) -> Dictionary: + # Special-cased properties. + if property == "emission_shape": + var shape = resolve_emission_shape(value) + if shape == null: + return { + "ok": false, + "error": "Invalid emission_shape '%s'. Valid: %s" % [ + value, ", ".join(emission_shape_names()) + ], + } + return {"ok": true, "value": int(shape)} + + if property == "color_ramp" or property == "color_initial_ramp": + var tex = build_gradient_texture(value) + if tex == null: + return {"ok": false, "error": "Invalid gradient for %s (expected {stops: [{time, color}]})" % property} + return {"ok": true, "value": tex} + + if property == "color" and value is Dictionary and not (value as Dictionary).has("stops"): + # color is a single Color, not a ramp. + var c = MaterialValues.parse_color(value) + if c == null: + return {"ok": false, "error": "Invalid color"} + return {"ok": true, "value": c} + + if property.ends_with("_curve"): + var tex = build_curve_texture(value) + if tex == null: + return {"ok": false, "error": "Invalid curve for %s (expected [{time, value}])" % property} + return {"ok": true, "value": tex} + + # Fall through to the material coercer (handles Color/Vec3/Vec2/float/int/bool/enum). + return MaterialValues.coerce_material_value(property, value, target_type) + + +## Build a StandardMaterial3D suitable for GPUParticles3D draw-pass rendering. +## +## Godot's default Mesh has no material, which means ParticleProcessMaterial's +## color_ramp (which drives the COLOR varying) gets ignored and particles +## render as flat white squares that don't face the camera. A correct default +## must have vertex_color_use_as_albedo=true, billboard=particles, unshaded, +## and alpha transparency so the gradient actually modulates the pixels. +## +## Config is an optional dict that overrides individual properties. Supported +## keys match BaseMaterial3D properties (plus enum-by-name via MaterialValues): +## blend_mode: "mix" | "add" | "sub" | "mul" +## transparency: "disabled" | "alpha" | "alpha_scissor" | "alpha_hash" | "alpha_depth_pre_pass" +## shading_mode: "unshaded" | "per_pixel" | "per_vertex" +## billboard_mode: "disabled" | "enabled" | "fixed_y" | "particles" +## vertex_color_use_as_albedo: bool +## emission_enabled: bool +## emission: Color +## emission_energy_multiplier: float +## albedo_color: Color +## albedo_texture: res:// path +## (anything else accepted by BaseMaterial3D.set()) +## +## Returns {ok: true, material: StandardMaterial3D, applied: Array[String]}, +## or {ok: false, key, error, unknown_key} when a config key is not a +## StandardMaterial3D property or its value fails coercion — draw config must +## not disappear silently (#770). +static func build_draw_material(config: Dictionary) -> Dictionary: + var mat := StandardMaterial3D.new() + # Sensible defaults for particle draw-pass rendering. + mat.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED + mat.vertex_color_use_as_albedo = true + mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA + mat.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES + mat.billboard_keep_scale = true + # Configure from dict overrides. + var applied: Array[String] = [] + for key in config: + var prop_name := String(key) + var prop_type := _object_property_type(mat, prop_name) + if prop_type == TYPE_NIL: + return { + "ok": false, + "key": prop_name, + "unknown_key": true, + "error": "Unknown draw key '%s' (not a StandardMaterial3D property)" % prop_name, + } + var coerce_result := MaterialValues.coerce_material_value( + prop_name, config[prop_name], prop_type + ) + if not coerce_result.ok: + return { + "ok": false, + "key": prop_name, + "unknown_key": false, + "error": "draw.%s: %s" % [prop_name, coerce_result.error], + } + mat.set(prop_name, coerce_result.value) + applied.append(prop_name) + return {"ok": true, "material": mat, "applied": applied} + + +static func _object_property_type(obj: Object, name: String) -> int: + if obj == null: + return TYPE_NIL + for prop in obj.get_property_list(): + if prop.name == name: + return int(prop.get("type", TYPE_NIL)) + return TYPE_NIL + + +## Serialize for response. +static func serialize(value: Variant) -> Variant: + if value == null: + return null + if value is GradientTexture1D: + var grad := (value as GradientTexture1D).gradient + if grad == null: + return {"type": "GradientTexture1D", "stops": []} + var stops: Array = [] + for i in grad.offsets.size(): + var c: Color = grad.colors[i] + stops.append({ + "time": grad.offsets[i], + "color": {"r": c.r, "g": c.g, "b": c.b, "a": c.a}, + }) + return {"type": "GradientTexture1D", "stops": stops} + if value is CurveTexture: + var curve := (value as CurveTexture).curve + if curve == null: + return {"type": "CurveTexture", "points": []} + var points: Array = [] + for i in curve.get_point_count(): + var p := curve.get_point_position(i) + points.append({"time": p.x, "value": p.y}) + return {"type": "CurveTexture", "points": points} + return MaterialValues.serialize_value(value) diff --git a/addons/godot_ai/handlers/particle_values.gd.uid b/addons/godot_ai/handlers/particle_values.gd.uid new file mode 100644 index 0000000..71f6adc --- /dev/null +++ b/addons/godot_ai/handlers/particle_values.gd.uid @@ -0,0 +1 @@ +uid://bnnnjq06dmclc diff --git a/addons/godot_ai/handlers/physics_shape_handler.gd b/addons/godot_ai/handlers/physics_shape_handler.gd new file mode 100644 index 0000000..dc5156c --- /dev/null +++ b/addons/godot_ai/handlers/physics_shape_handler.gd @@ -0,0 +1,338 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Sizes a CollisionShape2D/CollisionShape3D to match a visual sibling's +## bounds. Auto-creates the concrete Shape subclass when the slot is empty +## or the requested type differs — bundling creation and sizing in a single +## undo action. +## +## Shape type defaults: Box for 3D, Rectangle for 2D. + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +const _SHAPE_3D_CLASSES := { + "box": "BoxShape3D", + "sphere": "SphereShape3D", + "capsule": "CapsuleShape3D", + "cylinder": "CylinderShape3D", +} + +const _SHAPE_2D_CLASSES := { + "rectangle": "RectangleShape2D", + "circle": "CircleShape2D", + "capsule": "CapsuleShape2D", +} + + +func autofit(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var scene_root: Node = _resolved.scene_root + + var is_3d := node is CollisionShape3D + var is_2d := node is CollisionShape2D + if not (is_3d or is_2d): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node at %s is %s — must be CollisionShape3D or CollisionShape2D" % [node_path, node.get_class()] + ) + + var source_path: String = params.get("source_path", "") + var source: Node = null + if source_path.is_empty(): + var search := _find_bounds_visual(node, is_3d, scene_root) + if search.has("error"): + return search.error + source = search.source + else: + source = McpScenePath.resolve(source_path, scene_root) + if source == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, + "source_path: %s" % McpScenePath.format_node_error(source_path, scene_root)) + + var shape_type: String = params.get("shape_type", "box" if is_3d else "rectangle") + var type_map := _SHAPE_3D_CLASSES if is_3d else _SHAPE_2D_CLASSES + # Accept either the short form ("box") or the matching Godot class name + # ("BoxShape3D") — every other tool in the server takes class names, and + # resource_get_info(type="Shape3D") surfaces concrete_subclasses by class. + if not type_map.has(shape_type): + for short_form in type_map: + if type_map[short_form] == shape_type: + shape_type = short_form + break + if not type_map.has(shape_type): + var valid_pairs: Array[String] = [] + for short_form in type_map: + valid_pairs.append("%s (%s)" % [short_form, type_map[short_form]]) + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid shape_type '%s' for %s. Valid: %s" % [shape_type, node.get_class(), ", ".join(valid_pairs)] + ) + var shape_class: String = type_map[shape_type] + + # Measure the visual. + var bounds := _measure_bounds(source, is_3d) + if bounds.has("error"): + return bounds.error + + # Reuse the existing shape if it already matches the requested class; + # otherwise create a fresh one of the right type in the same undo action. + var existing_shape: Shape3D = null + var existing_shape_2d: Shape2D = null + if is_3d: + existing_shape = node.shape + else: + existing_shape_2d = node.shape + + var needs_new_shape := false + if is_3d: + needs_new_shape = existing_shape == null or existing_shape.get_class() != shape_class + else: + needs_new_shape = existing_shape_2d == null or existing_shape_2d.get_class() != shape_class + + var target_shape: Resource + if needs_new_shape: + var instance := ClassDB.instantiate(shape_class) + if instance == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s" % shape_class) + target_shape = instance + else: + target_shape = existing_shape if is_3d else existing_shape_2d + + # Compute and apply size. + var size_info := _apply_shape_size(target_shape, shape_type, bounds, is_3d) + var old_shape = existing_shape if is_3d else existing_shape_2d + + _undo_redo.create_action("MCP: Autofit %s on %s" % [shape_class, node.name]) + if needs_new_shape: + _undo_redo.add_do_property(node, "shape", target_shape) + _undo_redo.add_undo_property(node, "shape", old_shape) + _undo_redo.add_do_reference(target_shape) + else: + # Existing shape stays, but its size changes — snapshot size for undo. + for key in size_info.applied: + var new_val = target_shape.get(key) + var old_val = size_info.previous.get(key) + _undo_redo.add_do_property(target_shape, key, new_val) + _undo_redo.add_undo_property(target_shape, key, old_val) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "source_path": McpScenePath.from_node(source, scene_root) if source_path.is_empty() else source_path, + "shape_type": shape_type, + "shape_class": shape_class, + "shape_created": needs_new_shape, + "size": size_info.size_response, + "undoable": true, + } + } + + +## Returns `{source: Node}` on success, `{error: }` on failure. +## Ambiguous tier-2 matches put candidate scene paths in +## `error.data.candidates` so callers can pick one explicitly. +static func _find_bounds_visual(collision_node: Node, is_3d: bool, scene_root: Node) -> Dictionary: + var parent := collision_node.get_parent() + if parent == null: + return {"error": _no_visual_error(is_3d)} + + # Tier 1: direct siblings of the collision shape. Uses the broad + # VisualInstance3D filter for backwards compatibility — callers who put + # the visual directly next to the collision picked it on purpose. + var siblings := _measurable_visuals(parent.get_children(), collision_node, is_3d, false) + if not siblings.is_empty(): + return {"source": siblings[0]} + + # Tier 2: parent siblings (uncles). Tighten the filter to + # GeometryInstance3D so we don't auto-pick a Light3D / DirectionalLight3D + # as a collision source. Auto-pick only when unambiguous; surface + # multiple candidates so the agent chooses. + var grandparent := parent.get_parent() + if grandparent == null: + return {"error": _no_visual_error(is_3d)} + var uncles := _measurable_visuals(grandparent.get_children(), parent, is_3d, true) + if uncles.size() == 1: + return {"source": uncles[0]} + if uncles.size() > 1: + var paths: Array[String] = [] + for n in uncles: + paths.append(McpScenePath.from_node(n, scene_root)) + var msg := "Multiple visual candidates near %s — pass source_path explicitly. Candidates: %s" % [ + McpScenePath.from_node(collision_node, scene_root), + ", ".join(paths), + ] + var err := ErrorCodes.make(ErrorCodes.INVALID_PARAMS, msg) + err["error"]["data"] = {"candidates": paths} + return {"error": err} + return {"error": _no_visual_error(is_3d)} + + +## Filter `nodes` for ones we can measure as a collision source. When +## `strict` is true (tier 2 / uncles) only GeometryInstance3D counts in 3D — +## avoids picking up lights as accidental sources. 2D filter is already +## narrow enough that strictness doesn't change behavior. +static func _measurable_visuals(nodes: Array, exclude: Node, is_3d: bool, strict: bool) -> Array[Node]: + var out: Array[Node] = [] + for n in nodes: + if n == exclude: + continue + if is_3d: + if strict: + if n is GeometryInstance3D: + out.append(n) + elif n is VisualInstance3D: + out.append(n) + elif n is Sprite2D or n is TextureRect: + out.append(n) + return out + + +static func _no_visual_error(is_3d: bool) -> Dictionary: + var hint := "MeshInstance3D" if is_3d else "Sprite2D" + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "No visual found near collision shape — searched siblings and parent-siblings. Pass source_path explicitly (e.g. a %s)" % hint, + ) + + +## Measure the visual bounds of `source`. Returns {aabb: AABB} for 3D or +## {rect: Rect2} for 2D on success, or {error: ...} on failure. +## Bounds are returned in world-ish size (local extents scaled by the source +## node's own transform scale) so a MeshInstance3D at scale=(2,2,2) gives an +## 8× volume collider, not a unit collider. +static func _measure_bounds(source: Node, is_3d: bool) -> Dictionary: + if is_3d: + if source is VisualInstance3D: + var aabb: AABB = (source as VisualInstance3D).get_aabb() + # get_aabb() is local-space; pre-multiply by the source's scale + # so the collider tracks what you actually see in the viewport. + var scale_3d: Vector3 = (source as Node3D).transform.basis.get_scale() + aabb.position = aabb.position * scale_3d + aabb.size = aabb.size * scale_3d + return {"aabb": aabb} + return {"error": ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Source %s has no measurable 3D bounds (must be VisualInstance3D subclass)" % source.get_class() + )} + # 2D + if source is Sprite2D: + var s: Sprite2D = source + var srect: Rect2 = s.get_rect() + # get_rect() reports the local texture rect and ignores scale. + srect.position = srect.position * s.scale + srect.size = srect.size * s.scale + return {"rect": srect} + if source is TextureRect: + var tr: TextureRect = source + # tr.size is the Control's laid-out size, which is Vector2.ZERO + # before the first layout pass (e.g. just after the node was created + # via MCP). Fall back to the texture's own size when that happens, + # so autofit doesn't silently produce a zero-sized shape. + var tr_size: Vector2 = tr.size + if tr_size.is_zero_approx(): + if tr.texture != null: + tr_size = tr.texture.get_size() * tr.scale + else: + return {"error": ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "TextureRect at %s has zero layout size and no texture to fall back to — autofit would produce a zero-sized shape" % source.name + )} + return {"rect": Rect2(Vector2.ZERO, tr_size)} + return {"error": ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Source %s has no measurable 2D bounds (must be Sprite2D or TextureRect)" % source.get_class() + )} + + +## Apply size to `shape` based on `bounds` and the requested shape_type. +## Returns {applied: [property_names], previous: {name: old_value}, size_response: dict}. +static func _apply_shape_size(shape: Resource, shape_type: String, bounds: Dictionary, is_3d: bool) -> Dictionary: + var applied: Array[String] = [] + var previous := {} + var size_response := {} + + if is_3d: + var aabb: AABB = bounds.aabb + var size_v: Vector3 = aabb.size + match shape_type: + "box": + previous["size"] = shape.get("size") + (shape as BoxShape3D).size = size_v + applied.append("size") + size_response = {"x": size_v.x, "y": size_v.y, "z": size_v.z} + "sphere": + var r := maxf(maxf(size_v.x, size_v.y), size_v.z) * 0.5 + previous["radius"] = shape.get("radius") + (shape as SphereShape3D).radius = r + applied.append("radius") + size_response = {"radius": r} + "capsule": + var cap := shape as CapsuleShape3D + var r2 := maxf(size_v.x, size_v.z) * 0.5 + var h := size_v.y + previous["radius"] = cap.radius + previous["height"] = cap.height + # CapsuleShape3D enforces height >= 2*radius and silently + # clamps setters that would violate it. Read back the + # stored values so the response reflects reality. + cap.radius = r2 + cap.height = h + applied.append("radius") + applied.append("height") + size_response = {"radius": cap.radius, "height": cap.height} + "cylinder": + var cyl := shape as CylinderShape3D + var r3 := maxf(size_v.x, size_v.z) * 0.5 + var ch := size_v.y + previous["radius"] = cyl.radius + previous["height"] = cyl.height + cyl.radius = r3 + cyl.height = ch + applied.append("radius") + applied.append("height") + size_response = {"radius": cyl.radius, "height": cyl.height} + else: + var rect: Rect2 = bounds.rect + var sz: Vector2 = rect.size + match shape_type: + "rectangle": + previous["size"] = shape.get("size") + (shape as RectangleShape2D).size = sz + applied.append("size") + size_response = {"x": sz.x, "y": sz.y} + "circle": + var cr := maxf(sz.x, sz.y) * 0.5 + previous["radius"] = shape.get("radius") + (shape as CircleShape2D).radius = cr + applied.append("radius") + size_response = {"radius": cr} + "capsule": + var cap2 := shape as CapsuleShape2D + var cr2 := sz.x * 0.5 + var ch2 := sz.y + previous["radius"] = cap2.radius + previous["height"] = cap2.height + # CapsuleShape2D has the same height >= 2*radius invariant + # as its 3D counterpart; read back what Godot actually kept. + cap2.radius = cr2 + cap2.height = ch2 + applied.append("radius") + applied.append("height") + size_response = {"radius": cap2.radius, "height": cap2.height} + + return {"applied": applied, "previous": previous, "size_response": size_response} diff --git a/addons/godot_ai/handlers/physics_shape_handler.gd.uid b/addons/godot_ai/handlers/physics_shape_handler.gd.uid new file mode 100644 index 0000000..09acb4a --- /dev/null +++ b/addons/godot_ai/handlers/physics_shape_handler.gd.uid @@ -0,0 +1 @@ +uid://cdg8kthqla1cj diff --git a/addons/godot_ai/handlers/project_handler.gd b/addons/godot_ai/handlers/project_handler.gd new file mode 100644 index 0000000..eb7d36f --- /dev/null +++ b/addons/godot_ai/handlers/project_handler.gd @@ -0,0 +1,572 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles project settings and filesystem search commands. + +const NodeHandler := preload("res://addons/godot_ai/handlers/node_handler.gd") +const RUN_READY_WAIT_SEC := 3.0 + +## ProjectSettings keys that decide what the engine EXECUTES at project +## startup. `McpPathValidator._reject_sensitive_write` already refuses direct +## writes to `res://project.godot`, `res://override.cfg` and `res://.godot/` +## for exactly this reason — but `set_project_setting` writes that same +## manifest through the settings API, so without this list the guard is +## trivially side-steppable: +## +## settings_set key="autoload/Boot" value="*res://../../evil.gd" +## +## would land arbitrary code on the next project open, and a `project.godot` +## diff is easy to miss in review. Autoloads have a validated route of their +## own (`autoload_handler.add_autoload`, which runs the path through +## `McpPathValidator`); the rest are refused outright because there is no +## legitimate agent workflow for repointing the engine's startup execution. +## +## Deliberately NARROW. A denylist that over-blocks turns settings_set into a +## tool agents can't use, so only keys that actually carry code (or a command +## line) are listed — not their whole section. `application/run/` is an exact +## entry for `main_scene` precisely because its siblings (`max_fps`, +## `low_processor_mode`, …) are inert and must stay writable; likewise +## `application/boot_splash/image` is data, not code, and is NOT blocked. +## +## Prefix entries match the key and anything beneath it, and are used only +## where every key under the prefix is code-bearing. Exact entries match only +## themselves. Comparison is case-folded — ProjectSettings keys are +## case-sensitive, but a case variant that Godot would reject is still a +## clearer error coming from here than from a half-applied save. +const STARTUP_EXECUTION_KEY_PREFIXES: Array[String] = [ + "autoload/", ## every key under it is a script path + "editor_plugins/", ## enabled-plugin list; each entry is loaded as code +] +const STARTUP_EXECUTION_KEYS_EXACT: Array[String] = [ + "application/run/main_scene", ## the scene the game boots into + "editor/script/templates_search_path", ## where the editor loads templates from + "editor/run/main_run_args", ## command line for the run +] + + +## Returns "" when `key` may be written via set_project_setting, or a +## human-readable refusal reason otherwise. Static so it is unit-testable +## without instancing the handler. +static func startup_execution_key_refusal(key: String) -> String: + var lowered := key.strip_edges().to_lower() + for prefix in STARTUP_EXECUTION_KEY_PREFIXES: + if lowered.begins_with(prefix): + if prefix == "autoload/": + return ( + "Refusing to set '%s' — autoloads run code at project startup. " % key + + "Use autoload_manage(op='add'), which validates the script path." + ) + return ( + "Refusing to set '%s' — keys under '%s' are loaded as code " % [key, prefix] + + "at project startup." + ) + for exact in STARTUP_EXECUTION_KEYS_EXACT: + if lowered == exact: + return ( + "Refusing to set '%s' — this key controls what the engine loads " % key + + "or executes at project startup." + ) + return "" + +var _connection: McpConnection +var _debugger_plugin +var _editor_log_buffer + + +func _init(connection: McpConnection = null, debugger_plugin = null, editor_log_buffer = null) -> void: + _connection = connection + _debugger_plugin = debugger_plugin + _editor_log_buffer = editor_log_buffer + + +func get_project_setting(params: Dictionary) -> Dictionary: + var key: String = params.get("key", "") + if key.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: key") + + if not ProjectSettings.has_setting(key): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Setting not found: %s" % key) + + var value = ProjectSettings.get_setting(key) + return { + "data": { + "key": key, + "value": NodeHandler._serialize_value(value), + "type": type_string(typeof(value)), + } + } + + +func set_project_setting(params: Dictionary) -> Dictionary: + var key: String = params.get("key", "") + if key.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: key") + + if not params.has("value"): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: value") + + ## Refuse the startup-execution surface before touching ProjectSettings — + ## see STARTUP_EXECUTION_KEY_PREFIXES for why this guard exists here and + ## not only in McpPathValidator. + var refusal := startup_execution_key_refusal(key) + if not refusal.is_empty(): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, refusal) + + var value = params.get("value") + var had_setting := ProjectSettings.has_setting(key) + var old_value = ProjectSettings.get_setting(key) if had_setting else null + # JSON has no distinct int type: Godot parses `1920` as float. If the + # existing setting is TYPE_INT, coerce whole-number floats back to int so + # we don't silently flip typed-int settings (viewport_width, etc.) to + # floats on disk. See issue #31. + if had_setting and typeof(old_value) == TYPE_INT and typeof(value) == TYPE_FLOAT and float(int(value)) == value: + value = int(value) + ProjectSettings.set_setting(key, value) + var err := ProjectSettings.save() + if err != OK: + if had_setting: + ProjectSettings.set_setting(key, old_value) + else: + ProjectSettings.clear(key) + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to save project settings (error %d)" % err) + + return { + "data": { + "key": key, + "value": NodeHandler._serialize_value(value), + "old_value": NodeHandler._serialize_value(old_value), + "type": type_string(typeof(value)), + "undoable": false, + "reason": "ProjectSettings changes are saved to disk", + } + } + + +func run_project(params: Dictionary) -> Dictionary: + var mode: String = params.get("mode", "main") + var autosave: bool = params.get("autosave", true) + # Idempotent: a project that's already running satisfies the caller's intent. + # Returning INVALID_PARAMS here punished agents that legitimately called run + # to ensure the project is playing (87+ installs/day hit the matching + # stop-not-running case in telemetry). Surface state via was_already_running + # so a caller wanting a *different* scene can detect and stop+restart. + if EditorInterface.is_playing_scene(): + return _run_project_current_liveness_response( + _run_project_base_data( + mode, + str(params.get("scene", "")), + autosave, + true, + "Project was already running; no action taken" + ) + ) + + var validation_error: Variant = null + if mode == "custom": + var custom_scene: String = params.get("scene", "") + if custom_scene.is_empty(): + validation_error = ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: scene (required when mode='custom')") + else: + ## play_custom_scene() was the last path-taking op in the plugin + ## with no containment check; every sibling that accepts a scene + ## path validates it (scene_handler.open_scene, + ## node_handler.create_node's scene_path). + validation_error = McpPathValidator.loadable_error(custom_scene, "scene") + elif mode != "main" and mode != "current": + validation_error = ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Invalid mode '%s' — use 'main', 'current', or 'custom'" % mode) + if validation_error != null: + return validation_error + + # play_*_scene internally triggers try_autosave() → _save_scene_with_preview() + # which renders a preview thumbnail and calls frame processing. If our + # WebSocket connection's _process() re-enters during that render, the + # engine crashes (SIGABRT in _save_scene_with_preview). Pause processing + # around the play call — same pattern as SceneHandler.save_scene. + if _connection: + _connection.pause_processing = true + + # try_autosave() reads run/auto_save/save_before_running every call, so + # toggling it off around the play call suppresses the save without + # touching the user's persisted preference. Issue #81. + var autosave_key := "run/auto_save/save_before_running" + var editor_settings: EditorSettings = null + if not autosave: + editor_settings = EditorInterface.get_editor_settings() + var prior_autosave: bool = true + var restore_setting := false + if editor_settings != null and editor_settings.has_setting(autosave_key): + prior_autosave = bool(editor_settings.get_setting(autosave_key)) + editor_settings.set_setting(autosave_key, false) + restore_setting = true + + if _debugger_plugin != null: + _debugger_plugin.begin_game_run(_editor_log_cursor(), _game_helper_autoload_expected()) + + match mode: + "main": + EditorInterface.play_main_scene() + "current": + EditorInterface.play_current_scene() + "custom": + var scene_path: String = params.get("scene", "") + EditorInterface.play_custom_scene(scene_path) + + if restore_setting: + editor_settings.set_setting(autosave_key, prior_autosave) + + if _connection: + _connection.pause_processing = false + + var base_data := _run_project_base_data( + mode, + str(params.get("scene", "")), + autosave, + false, + "Play/stop is a runtime action" + ) + var request_id: String = params.get("_request_id", "") + if _connection != null and _debugger_plugin != null and not request_id.is_empty(): + _finish_run_project_deferred(request_id, base_data, _connection, _debugger_plugin) + return McpDispatcher.DEFERRED_RESPONSE + + return _run_project_current_liveness_response(base_data) + + +func _editor_log_cursor() -> int: + return _editor_log_buffer.appended_total() if _editor_log_buffer != null else 0 + + +func _game_helper_autoload_expected() -> bool: + return ProjectSettings.has_setting("autoload/_mcp_game_helper") + + +static func _run_project_base_data( + mode: String, + scene: String, + autosave: bool, + was_already_running: bool, + reason: String +) -> Dictionary: + return { + "mode": mode, + "scene": scene, + "autosave": autosave, + "was_already_running": was_already_running, + "undoable": false, + "reason": reason, + } + + +func _run_project_current_liveness_response(base_data: Dictionary) -> Dictionary: + if _debugger_plugin == null: + return {"data": base_data} + var status: Dictionary = _debugger_plugin.get_game_status(-1, RUN_READY_WAIT_SEC) + ## One-shot read — force a Debugger-tab scan so boot errors that landed + ## after the last gated scan are in this response (#641). + var errors_info: Dictionary = _debugger_plugin.recent_editor_errors_since(int(status.get("editor_log_cursor", 0)), true) + return _run_project_response(base_data, _run_project_liveness_decision(status, errors_info)) + + +## `static` is load-bearing (#712, same rationale as the script/filesystem +## handlers and editor_handler._do_reload_plugin): this coroutine awaits +## across frames, and a plugin reload frees this RefCounted handler +## mid-await — resuming an instance coroutine on a freed object errors. +## `connection` and `debugger_plugin` are parameterized explicitly and +## re-validated after every await; the response is dropped silently when +## either died (the server's command timeout surfaces the failure). +static func _finish_run_project_deferred( + request_id: String, base_data: Dictionary, connection, debugger_plugin +) -> void: + var tree: SceneTree = connection.get_tree() + while true: + await tree.process_frame + if not is_instance_valid(connection) or not is_instance_valid(debugger_plugin): + return + var pre_status: Dictionary = debugger_plugin.get_game_status(-1, RUN_READY_WAIT_SEC) + if ( + not EditorInterface.is_playing_scene() + and int(pre_status.get("elapsed_msec", 0)) > 100 + and str(pre_status.get("status", "stopped")) == "launching" + ): + debugger_plugin.end_game_run() + var status: Dictionary = debugger_plugin.get_game_status(-1, RUN_READY_WAIT_SEC) + var errors_info: Dictionary = debugger_plugin.recent_editor_errors_since(int(status.get("editor_log_cursor", 0))) + var decision := _run_project_liveness_decision(status, errors_info) + if not bool(decision.get("resolve", false)): + continue + ## #641: the loop above polls with gated (cheap) scans; boot parse + ## errors can land in the Errors tab in the same frames the run goes + ## live. Re-gather once with a forced scan before replying so the + ## response reports them instead of leaving them to a later + ## logs_read. Rebuilding the decision with strictly-more errors can + ## only keep it resolved (errors never un-resolve a decision). + errors_info = debugger_plugin.recent_editor_errors_since(int(status.get("editor_log_cursor", 0)), true) + decision = _run_project_liveness_decision(status, errors_info) + connection.send_deferred_response(request_id, _run_project_response(base_data, decision)) + return + + +static func _run_project_response(base_data: Dictionary, decision: Dictionary) -> Dictionary: + var data := base_data.duplicate(true) + var game_status: Dictionary = decision.get("game_status", {}) + data["game_status"] = game_status + data["helper_live"] = bool(game_status.get("helper_live", false)) + data["session_active"] = bool(game_status.get("session_active", false)) + if bool(data.get("was_already_running", false)): + data["reason"] = _run_project_already_running_message(decision) + else: + data["reason"] = decision.get("message", data.get("reason", "Play/stop is a runtime action")) + data["recent_errors"] = decision.get("recent_errors", []) + data["recent_errors_scope"] = decision.get("recent_errors_scope", "none") + data["recent_errors_may_predate_run"] = decision.get("recent_errors_may_predate_run", false) + data["recent_errors_truncated"] = decision.get("recent_errors_truncated", false) + data.merge(McpDebuggerPlugin.split_errors_by_scope(data["recent_errors"], data["recent_errors_scope"]), true) + return {"data": data} + + +static func _run_project_already_running_message(decision: Dictionary) -> String: + var state := str(decision.get("liveness_status", "unknown")) + match state: + "live": + var live_errors: Array = decision.get("recent_errors", []) + if not live_errors.is_empty() and str(decision.get("recent_errors_scope", "none")) == "run": + return ( + "Project was already running; the Godot AI game helper is live, but %d editor error%s surfaced during this run (first: %s). Check logs_read(source='editor', include_details=true)." + % [live_errors.size(), "s" if live_errors.size() != 1 else "", _format_editor_error_summary(live_errors[0])] + ) + return "Project was already running; the Godot AI game helper is live." + "not_live": + var errors: Array = decision.get("recent_errors", []) + var scope := str(decision.get("recent_errors_scope", "none")) + if not errors.is_empty() and scope == "run": + return "Project was already running but failed to load before the Godot AI game helper registered: %s. Check logs_read(source='editor', include_details=true)." % _format_editor_error_summary(errors[0]) + if not errors.is_empty(): + return "Project was already running but is not responding. A recent editor error may be related, but may predate this run: %s. Check logs_read(source='editor', include_details=true)." % _format_editor_error_summary(errors[0]) + return "Project was already running but did not become live before the helper-ready window elapsed. Check logs_read(source='editor', include_details=true) and poll editor_state." + "break": + var break_errors: Array = decision.get("recent_errors", []) + if not break_errors.is_empty() and str(decision.get("recent_errors_scope", "none")) == "run": + return "Project was already running but the game is parked at a debugger break: %s. Call project_manage(op='stop') to end the run, fix the error, and relaunch." % _format_editor_error_summary(break_errors[0]) + if not break_errors.is_empty(): + return "Project was already running but the game is parked at a debugger break. A recent editor error may be related, but may predate this run: %s. Call project_manage(op='stop') to end the run." % _format_editor_error_summary(break_errors[0]) + return "Project was already running but the game is parked at a debugger break. Call project_manage(op='stop') to end the run; the break reason is in the editor's Debugger panel." + "no_helper": + return "Project was already running, but no _mcp_game_helper autoload is expected. Headless or custom-main-loop projects cannot confirm helper liveness." + "launching": + return "Project was already running and is still waiting for the Godot AI game helper to register. Poll editor_state shortly." + "stopped": + return "Project was already marked playing by the editor, but no active game liveness run exists." + _: + return "Project was already running; current liveness status is %s." % state + + +## Static (with the rest of the deferred-finisher chain) so the #712 +## load-bearing-static coroutines above can call it after their owner +## handler was freed. Uses no instance state. +static func _run_project_liveness_decision(status: Dictionary, errors_info: Dictionary = {}) -> Dictionary: + var enriched_status := McpDebuggerPlugin.with_liveness_flags(status) + var state := str(status.get("status", "stopped")) + var recent_errors: Array = errors_info.get("errors", []) + var errors_scope := str(errors_info.get("scope", "none")) + var truncated := bool(errors_info.get("truncated", false)) + ## Clear errors that predate this run's window — they don't belong in + ## a successful launch response and only add noise. They remain + ## reachable via logs_read(source='editor') and the retained buffer so + ## failed-run debugging is unaffected. + ## #635 tradeoff: a genuine in-run error whose Errors-tab row carries + ## an empty or byte-identical time text can be misclassified as + ## retained_recent and will be dropped here. Still reachable via + ## logs_read. + if state == "live" and errors_scope == "retained_recent": + recent_errors = [] + errors_scope = "none" + var correlated_error := not recent_errors.is_empty() and errors_scope == "run" + var elapsed_msec := int(status.get("elapsed_msec", 0)) + var ready_wait_msec := int(status.get("ready_wait_msec", int(RUN_READY_WAIT_SEC * 1000.0))) + var decision := { + "resolve": false, + "game_status": enriched_status, + "liveness_status": state, + "recent_errors": recent_errors, + "recent_errors_scope": errors_scope, + "recent_errors_may_predate_run": errors_scope == "retained_recent", + "recent_errors_truncated": truncated, + "message": "", + } + if state == "live": + decision["resolve"] = true + if correlated_error: + ## #641: "live" only means the helper autoload registered — scripts + ## can still have failed to parse or load during boot (a broken + ## node script does not stop the game from running). Surface those + ## errors in the success message so agents don't read a clean + ## launch into a run that silently lost scripts. + decision["message"] = ( + "Game launched and the Godot AI game helper is live, but %d editor error%s surfaced during startup (first: %s) — likely a script that failed to parse or load. Check logs_read(source='editor', include_details=true)." + % [recent_errors.size(), "s" if recent_errors.size() != 1 else "", _format_editor_error_summary(recent_errors[0])] + ) + if truncated: + decision["message"] += " Editor logs since this run may be truncated; showing retained errors." + else: + decision["message"] = "Game launched and the Godot AI game helper is live." + elif state == "break": + ## #645: the game process is parked in a remote-debugger break. A + ## boot-time parse error (GDScriptLanguage::debug_break_parse) produces + ## no Errors-tab row, no Logger entry, and no game-log line — the + ## synthesized break record is the only evidence, and it lands a + ## moment after the break signal (stack frames arrive async). Wait for + ## it (correlated_error) before resolving; the ready window is the + ## fallback if synthesis never lands. + var break_info: Dictionary = status.get("break", {}) + var break_reason := str(break_info.get("reason", "")) + if bool(break_info.get("pre_live", true)): + decision["resolve"] = correlated_error or elapsed_msec >= ready_wait_msec + var summary := break_reason + if correlated_error: + summary = _format_editor_error_summary(recent_errors[0]) + if summary.is_empty(): + summary = "script parse/load error (reason not captured)" + decision["message"] = "Game hit a script error during startup and is frozen at a debugger break before the Godot AI game helper registered: %s. The run cannot continue; call project_manage(op='stop'), fix the error, and relaunch. Check logs_read(source='editor', include_details=true)." % summary + else: + var reason_suffix := (": %s" % break_reason) if not break_reason.is_empty() else "" + decision["resolve"] = true + decision["message"] = "Game is paused at a debugger break%s. Resume it from the editor's Debugger panel or call project_manage(op='stop')." % reason_suffix + elif correlated_error: + decision["resolve"] = true + decision["liveness_status"] = "not_live" + decision["message"] = "Game launched but failed to load before the Godot AI game helper registered: %s. Check logs_read(source='editor', include_details=true)." % _format_editor_error_summary(recent_errors[0]) + if truncated: + decision["message"] += " Editor logs since this run may be truncated; showing retained errors." + elif state == "not_live": + decision["resolve"] = true + if not recent_errors.is_empty(): + decision["message"] = "Game launched but is not responding. A recent editor error may be related, but may predate this run: %s. Check logs_read(source='editor', include_details=true)." % _format_editor_error_summary(recent_errors[0]) + else: + decision["message"] = "Game launched but did not become live before the helper-ready window elapsed. It may still be booting or may have failed silently; check logs_read(source='editor', include_details=true) and poll editor_state." + elif state == "no_helper": + decision["resolve"] = true + decision["message"] = "Game launched, but no _mcp_game_helper autoload is expected. Headless or custom-main-loop projects cannot confirm helper liveness; use editor_state and viewport/editor tools where applicable." + elif state == "stopped": + decision["resolve"] = true + decision["message"] = "The play session stopped, or no active game liveness run exists, before the Godot AI game helper became live." + elif state == "launching" and elapsed_msec >= ready_wait_msec: + decision["resolve"] = true + decision["message"] = "Game launched but is not yet live after %.1fs; it may still be booting. Poll editor_state and check logs_read(source='editor', include_details=true)." % (float(elapsed_msec) / 1000.0) + return decision + + +static func _format_editor_error_summary(entry: Dictionary) -> String: + return McpSurfacedErrorTracker.format_editor_error_summary(entry) + + +func stop_project(params: Dictionary) -> Dictionary: + # Idempotent: a project that's already stopped satisfies the caller's intent. + # Returning INVALID_PARAMS here was the largest single source of fleet-wide + # project_manage failures (87 installs/24h). was_running=false lets callers + # distinguish a no-op stop from one that actually halted a running session. + if not EditorInterface.is_playing_scene(): + return { + "data": { + "stopped": true, + "was_running": false, + "undoable": false, + "reason": "Project was not running; no action taken", + } + } + + if _debugger_plugin != null: + _debugger_plugin.end_game_run() + EditorInterface.stop_playing_scene() + + # stop_playing_scene() is async — is_playing_scene() only flips to false on + # the next frame, and readiness_changed follows in _process. Defer the + # response so we can reply with authoritative readiness instead of letting + # the server poll for the event. Issue #29. + var request_id: String = params.get("_request_id", "") + if _connection != null and not request_id.is_empty(): + _finish_stop_project_deferred(request_id, _connection) + return McpDispatcher.DEFERRED_RESPONSE + + # Fallback for contexts without a connection (e.g. batch_execute via + # dispatch_direct, or unit tests that instantiate the handler with null). + return { + "data": { + "stopped": true, + "was_running": true, + "undoable": false, + "reason": "Play/stop is a runtime action", + } + } + + +# Wait two frames so Godot can tick the stop-play state change. After this +# is_playing_scene() reflects truth and get_readiness() is authoritative. +# If the plugin tears down (_exit_tree frees _connection) during the await, +# is_instance_valid() goes false and we drop the response silently — the +# server's 5s request timeout will surface the failure to the caller. +# `static` is load-bearing (#712): see _finish_run_project_deferred. +static func _finish_stop_project_deferred(request_id: String, connection) -> void: + var tree: SceneTree = connection.get_tree() + await tree.process_frame + await tree.process_frame + if not is_instance_valid(connection): + return + connection.send_deferred_response(request_id, { + "data": { + "stopped": true, + "was_running": true, + "undoable": false, + "reason": "Play/stop is a runtime action", + "readiness_after": McpConnection.get_readiness(), + } + }) + + +func search_filesystem(params: Dictionary) -> Dictionary: + var name_filter: String = params.get("name", "") + var type_filter: String = params.get("type", "") + var path_filter: String = params.get("path", "") + + if name_filter.is_empty() and type_filter.is_empty() and path_filter.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "At least one filter (name, type, path) is required") + + var efs := EditorInterface.get_resource_filesystem() + if efs == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "EditorFileSystem not available", false) + + var results: Array[Dictionary] = [] + _scan_directory(efs.get_filesystem(), name_filter, type_filter, path_filter, results) + return {"data": {"files": results, "count": results.size()}} + + +func _scan_directory(dir: EditorFileSystemDirectory, name_filter: String, type_filter: String, path_filter: String, out: Array[Dictionary]) -> void: + for i in dir.get_file_count(): + var file_path := dir.get_file_path(i) + var file_type := dir.get_file_type(i) + + var matches := true + + if not name_filter.is_empty(): + if file_path.get_file().to_lower().find(name_filter.to_lower()) == -1: + matches = false + + if matches and not type_filter.is_empty(): + if file_type != type_filter: + matches = false + + if matches and not path_filter.is_empty(): + if file_path.to_lower().find(path_filter.to_lower()) == -1: + matches = false + + if matches: + out.append({ + "path": file_path, + "type": file_type, + }) + + for i in dir.get_subdir_count(): + _scan_directory(dir.get_subdir(i), name_filter, type_filter, path_filter, out) diff --git a/addons/godot_ai/handlers/project_handler.gd.uid b/addons/godot_ai/handlers/project_handler.gd.uid new file mode 100644 index 0000000..ec2b5d7 --- /dev/null +++ b/addons/godot_ai/handlers/project_handler.gd.uid @@ -0,0 +1 @@ +uid://brf8u32hvha68 diff --git a/addons/godot_ai/handlers/resource_handler.gd b/addons/godot_ai/handlers/resource_handler.gd new file mode 100644 index 0000000..553ed9b --- /dev/null +++ b/addons/godot_ai/handlers/resource_handler.gd @@ -0,0 +1,591 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const ClassIntrospection := preload("res://addons/godot_ai/utils/class_introspection.gd") + +## Handles resource search, inspection, and assignment to nodes. + +const NodeHandler := preload("res://addons/godot_ai/handlers/node_handler.gd") + +var _undo_redo: EditorUndoRedoManager +var _connection: McpConnection + + +func _init(undo_redo: EditorUndoRedoManager, connection: McpConnection = null) -> void: + _undo_redo = undo_redo + _connection = connection + + +func search_resources(params: Dictionary) -> Dictionary: + var type_filter: String = params.get("type", "") + var path_filter: String = params.get("path", "") + + if type_filter.is_empty() and path_filter.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "At least one filter (type, path) is required") + + var efs := EditorInterface.get_resource_filesystem() + if efs == null: + return ErrorCodes.make_not_ready( + ErrorCodes.SUB_EDITOR_UNAVAILABLE, + "EditorFileSystem not available", false) + + var results: Array[Dictionary] = [] + _scan_resources(efs.get_filesystem(), type_filter, path_filter, results) + return {"data": {"resources": results, "count": results.size()}} + + +func _scan_resources(dir: EditorFileSystemDirectory, type_filter: String, path_filter: String, out: Array[Dictionary]) -> void: + for i in dir.get_file_count(): + var file_path := dir.get_file_path(i) + var file_type := dir.get_file_type(i) + + var matches := true + + if not type_filter.is_empty(): + # Check if the file type matches or is a subclass of the requested type + if file_type != type_filter and not ClassDB.is_parent_class(file_type, type_filter): + matches = false + + if matches and not path_filter.is_empty(): + if file_path.to_lower().find(path_filter.to_lower()) == -1: + matches = false + + if matches: + out.append({ + "path": file_path, + "type": file_type, + }) + + for i in dir.get_subdir_count(): + _scan_resources(dir.get_subdir(i), type_filter, path_filter, out) + + +func load_resource(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var path_err = McpPathValidator.loadable_error(path, "path") + if path_err != null: + return path_err + + if not ResourceLoader.exists(path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % path) + + var res: Resource = load(path) + if res == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to load resource: %s" % path) + + var properties: Array[Dictionary] = [] + for prop in res.get_property_list(): + var usage: int = prop.get("usage", 0) + if not (usage & PROPERTY_USAGE_EDITOR): + continue + var value = res.get(prop.name) + if value == null and prop.type != TYPE_NIL: + continue + properties.append({ + "name": prop.name, + "type": type_string(prop.type), + "value": NodeHandler._serialize_value(value), + }) + + return { + "data": { + "path": path, + "type": res.get_class(), + "properties": properties, + "property_count": properties.size(), + } + } + + +func assign_resource(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + var property: String = params.get("property", "") + var resource_path: String = params.get("resource_path", "") + + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + if property.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: property") + + if resource_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: resource_path") + + var rpath_err = McpPathValidator.loadable_error(resource_path, "resource_path") + if rpath_err != null: + return rpath_err + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + + # Verify property exists + var found := false + for prop in node.get_property_list(): + if prop.name == property: + found = true + break + if not found: + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, McpPropertyErrors.build_message(node, property)) + + if not ResourceLoader.exists(resource_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Resource not found: %s" % resource_path) + + var res: Resource = load(resource_path) + if res == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to load resource: %s" % resource_path) + + var old_value = node.get(property) + + _undo_redo.create_action("MCP: Assign %s to %s.%s" % [resource_path.get_file(), node.name, property]) + _undo_redo.add_do_property(node, property, res) + _undo_redo.add_undo_property(node, property, old_value) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "property": property, + "resource_path": resource_path, + "resource_type": res.get_class(), + "undoable": true, + } + } + + +## Instantiate a built-in Resource subclass, optionally apply `properties`, +## and either assign it to a node slot (undoable) or save it to a .tres file +## (not undoable — mirrors material_create). Exactly one home is required; +## a resource with no home would be GC'd after the handler returns. +func create_resource(params: Dictionary) -> Dictionary: + var type_str: String = params.get("type", "") + if type_str.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: type") + + var properties: Dictionary = params.get("properties", {}) + var node_path: String = params.get("path", "") + var property: String = params.get("property", "") + var resource_path: String = params.get("resource_path", "") + var overwrite: bool = params.get("overwrite", false) + + var home_err := McpResourceIO.validate_home(params) + if home_err != null: + return home_err + var has_file_target := not resource_path.is_empty() + + var made := _instantiate_resource(type_str) + if made is Dictionary: + return made + var res: Resource = made + + if not properties.is_empty(): + var apply_err := _apply_resource_properties(res, properties) + if apply_err != null: + return apply_err + + if has_file_target: + return _save_created_resource(res, type_str, resource_path, overwrite, properties.size()) + return _assign_created_resource(res, type_str, node_path, property, properties.size()) + + +## Validate that `type_str` names a concrete Resource subclass that we can +## instantiate. Returns an error dict on failure, or null on success. +static func _validate_resource_class(type_str: String) -> Variant: + if not ClassDB.class_exists(type_str): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unknown resource type: %s" % type_str) + if ClassDB.is_parent_class(type_str, "Node"): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "%s is a Node type, not a Resource — use node_create instead" % type_str + ) + if not ClassDB.is_parent_class(type_str, "Resource"): + var parent := ClassDB.get_parent_class(type_str) + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "%s is not a Resource type (extends %s)" % [type_str, parent] + ) + if not ClassDB.can_instantiate(type_str): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "%s is abstract and cannot be instantiated — use a concrete subclass (e.g. BoxMesh, BoxShape3D, StyleBoxFlat)" % type_str + ) + return null + + +## Build the "Unknown resource type" error with a steer toward op="scan". A type +## that reaches here is neither an engine built-in (ClassDB) nor a registered +## project class (the global script-class registry). In an agent-driven workflow +## the most common cause is a `class_name` script just made via script_create +## that isn't registered yet — the global class table only rebuilds on a +## filesystem scan (normally an editor-focus event). Point the caller at the one +## cheap call that fixes that, so it doesn't fall back to a full plugin reload. +## See #614 for the headless scan op. +static func _unknown_resource_type_error(type_str: String) -> Dictionary: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + ( + "Unknown resource type: %s — not an engine built-in or a registered project class. " + + "If you just created it with script_create, the global class table is stale until a " + + "scan: call filesystem_manage(op=\"scan\"), then retry. Otherwise check the spelling." + ) % type_str + ) + + +## Resolve a resource type name to a fresh instance. Handles engine built-ins +## (ClassDB) and project `class_name` Resources (the global script-class +## registry). Returns a Resource on success, or an error dict on failure. +static func _instantiate_resource(type_str: String) -> Variant: + if ClassDB.class_exists(type_str): + var class_err: Variant = _validate_resource_class(type_str) + if class_err != null: + return class_err + var built_in := ClassDB.instantiate(type_str) + if built_in == null or not (built_in is Resource): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s as a Resource" % type_str) + return built_in + for entry in ProjectSettings.get_global_class_list(): + if entry.get("class", "") == type_str: + var script_path: String = entry.get("path", "") + var scr: Variant = load(script_path) + # Reject non-Resource script classes BEFORE constructing them: + # scr.new() runs _init(), and an @tool class_name extending a + # non-RefCounted type (e.g. Node) would otherwise build — and leak — + # an orphan instance this path never frees. get_instance_base_type() + # resolves to the native base, so multi-level custom Resource + # hierarchies (B extends A extends Resource) still pass. + var base_or_err: Variant = _script_base_type_or_error(scr, type_str, script_path) + if base_or_err is Dictionary: + return base_or_err + var base_type: StringName = base_or_err + if not ClassDB.is_parent_class(base_type, "Resource"): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "%s is not a Resource type (extends %s)" % [type_str, base_type]) + if not scr.can_instantiate(): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "%s cannot be instantiated in the editor (abstract, or a non-@tool script — add @tool to instantiate it here)" % type_str) + # Reject scripts whose _init() requires arguments BEFORE scr.new(): + # scr.new() passes no args, so a required-arg _init raises and aborts + # this handler mid-call, null-cascading into a generic "malformed + # result" error instead of a clean rejection. get_script_method_list() + # reports the effective (incl. inherited) _init; required args = + # args - default_args. Statically detectable only — a _init that runs + # but throws still falls through to scr.new() and the dispatcher catch. + for method in scr.get_script_method_list(): + if method.get("name", "") == "_init": + var required_args: int = (method.get("args", []) as Array).size() - (method.get("default_args", []) as Array).size() + if required_args > 0: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "%s cannot be instantiated: its _init() requires arguments" % type_str) + break + var made: Variant = scr.new() + if made == null or not (made is Resource): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s as a Resource" % type_str) + return made + return _unknown_resource_type_error(type_str) + + +## Maximum nesting depth for the {"__class__": ...} sub-resource shortcut. +## Caller-supplied dicts recurse through _apply_resource_properties; without a +## cap a deeply nested payload overflows the GDScript call stack and crashes +## the editor (#536). 32 is far beyond any legitimate sub-resource chain. +const MAX_NESTED_RESOURCE_DEPTH := 32 + + +## Apply a dict of property values to a freshly-instantiated Resource, +## reusing NodeHandler's coercion so Vector3/Color/etc. dicts land typed. +## Returns null on success or an error dict on failure. +## `depth` is internal recursion bookkeeping for the nested {"__class__": ...} +## shortcut — external callers use the default of 0. +static func _apply_resource_properties(res: Resource, properties: Dictionary, depth: int = 0) -> Variant: + if depth > MAX_NESTED_RESOURCE_DEPTH: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Nested resource properties exceed the maximum depth of %d — flatten the {\"__class__\": ...} nesting or create the deep sub-resources in separate calls" % MAX_NESTED_RESOURCE_DEPTH + ) + var prop_types := {} + for prop in res.get_property_list(): + prop_types[prop.name] = prop.get("type", TYPE_NIL) + for key in properties.keys(): + if not prop_types.has(key): + var valid: Array[String] = [] + for prop in res.get_property_list(): + if prop.get("usage", 0) & PROPERTY_USAGE_EDITOR: + valid.append(prop.name) + valid.sort() + # Name the script's class_name (e.g. MyTestResource) rather than the + # native base (Resource) so the hint names the type the agent created, + # and point at the real MCP verb — resource_manage(op="get_info") now + # answers for project class_name Resources too. + var type_label := res.get_class() + var res_script: Variant = res.get_script() + if res_script is Script and not String(res_script.get_global_name()).is_empty(): + type_label = String(res_script.get_global_name()) + var err := ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Property '%s' not found on %s. Call resource_manage(op=\"get_info\", params={\"type\": \"%s\"}) to list available properties." % [key, type_label, type_label] + ) + err["error"]["data"] = {"valid_properties": valid} + return err + var target_type: int = prop_types[key] + if target_type == TYPE_NIL: + target_type = typeof(res.get(key)) + var v = properties[key] + if target_type == TYPE_OBJECT and v is String: + if v == "": + v = null + else: + var vpath_err = McpPathValidator.loadable_error(v, "property '%s'" % key) + if vpath_err != null: + return vpath_err + var loaded := ResourceLoader.load(v) + if loaded == null: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Resource not found at path '%s' for property '%s'" % [v, key] + ) + v = loaded + elif target_type == TYPE_OBJECT and v is Dictionary and v.has("__class__"): + # Nested shortcut: the same {"__class__": "X", ...} form that + # node_handler.set_property accepts, now also supported here so + # resource_create/environment_create callers can populate + # sub-resource slots (ShaderMaterial.shader, etc.) in one shot. + var sub_type: String = v.get("__class__", "") + # Resolve via the shared helper so the nested shortcut accepts both + # engine built-ins (ClassDB) and project `class_name` Resources, + # exactly like the top-level resource_create path. + var sub_made := _instantiate_resource(sub_type) + if sub_made is Dictionary: + # Preserve the property-slot context the inline path used to add. + sub_made["error"]["message"] = "%s (for property '%s')" % [sub_made["error"]["message"], key] + return sub_made + var sub_res: Resource = sub_made + var remaining: Dictionary = (v as Dictionary).duplicate() + remaining.erase("__class__") + if not remaining.is_empty(): + var nested_err := _apply_resource_properties(sub_res, remaining, depth + 1) + if nested_err != null: + return nested_err + v = sub_res + else: + var slot_value: Variant = res.get(key) + if target_type == TYPE_ARRAY and slot_value is Array and (slot_value as Array).is_typed(): + ## Typed Array[T] slot (#612): mirror set_property's dispatch — + ## the generic passthrough would hand an untyped Array to the + ## typed setter, which drops it silently while we report success. + var typed_out: Variant = NodeHandler._coerce_typed_array( + v, slot_value, "Property '%s'" % key + ) + if typed_out is Dictionary: + return typed_out + v = typed_out + elif ( + target_type == TYPE_DICTIONARY + and slot_value is Dictionary + and (slot_value as Dictionary).is_typed() + ): + ## Typed Dictionary[K, V] slot (#612 stage 3): success is a + ## typed duplicate of the slot; the error envelope is untyped. + var typed_dict_out: Dictionary = NodeHandler._coerce_typed_dictionary( + v, slot_value, "Property '%s'" % key + ) + if not typed_dict_out.is_typed(): + return typed_dict_out + v = typed_dict_out + else: + v = NodeHandler._coerce_value(v, target_type) + ## Mirror set_property's coerce check: wrong-shape dicts (#123) and + ## non-dict inputs that don't land as the target compound Variant + ## (#191) both error here instead of writing zero-filled Variants. + var coerce_err := NodeHandler._check_coerced(v, target_type, "Property '%s'" % key) + if coerce_err != null: + return coerce_err + res.set(key, v) + return null + + +func _assign_created_resource(res: Resource, type_str: String, node_path: String, property: String, applied_count: int) -> Dictionary: + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + + var found := false + var prop_type: int = TYPE_NIL + for prop in node.get_property_list(): + if prop.name == property: + found = true + prop_type = prop.get("type", TYPE_NIL) + break + if not found: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + McpPropertyErrors.build_message(node, property) + ) + if prop_type != TYPE_NIL and prop_type != TYPE_OBJECT: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Property '%s' on %s is not an Object slot (type %s)" % [property, node.get_class(), type_string(prop_type)] + ) + + var old_value = node.get(property) + + _undo_redo.create_action("MCP: Create %s for %s.%s" % [type_str, node.name, property]) + _undo_redo.add_do_property(node, property, res) + _undo_redo.add_undo_property(node, property, old_value) + _undo_redo.add_do_reference(res) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "property": property, + "type": type_str, + "resource_class": res.get_class(), + "properties_applied": applied_count, + "undoable": true, + } + } + + +func _save_created_resource(res: Resource, type_str: String, resource_path: String, overwrite: bool, applied_count: int) -> Dictionary: + return McpResourceIO.save_to_disk(res, resource_path, overwrite, "Resource", { + "type": type_str, + "resource_class": res.get_class(), + "properties_applied": applied_count, + }, _connection) + + +## Introspect a Resource class — return its editor-visible properties, parent, +## whether it's abstract, and (for abstract bases) the list of concrete +## subclasses that resource_create can instantiate. Read-only. +func get_resource_info(params: Dictionary) -> Dictionary: + var type_str: String = params.get("type", "") + if type_str.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: type") + + if not ClassDB.class_exists(type_str): + # Project class_name Resources aren't in ClassDB; resolve them through the + # global script-class registry so get_info answers for the same custom + # types resource_create can make. Read-only — never instantiates. + var custom_info: Variant = _custom_resource_info(type_str) + if custom_info != null: + return custom_info + return _unknown_resource_type_error(type_str) + if ClassDB.is_parent_class(type_str, "Node"): + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "%s is a Node type, not a Resource — use node_* tools for node introspection" % type_str + ) + if not ClassDB.is_parent_class(type_str, "Resource") and type_str != "Resource": + var parent := ClassDB.get_parent_class(type_str) + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "%s is not a Resource type (extends %s)" % [type_str, parent] + ) + + var can_instantiate: bool = ClassDB.can_instantiate(type_str) + var class_info := ClassIntrospection.build(type_str, { + "sections": ["properties"], + "include_inherited": true, + "include_inheritors": not can_instantiate, + "limit": 0, + }) + var data: Dictionary = { + "type": type_str, + "parent_class": class_info.parent_class, + "can_instantiate": can_instantiate, + "is_abstract": not can_instantiate, + "properties": class_info.properties, + "property_count": class_info.property_count, + } + + # For abstract bases (Shape3D, Material, Texture, StyleBox, ...) surface + # the concrete Resource subclasses an agent could try next. + if not can_instantiate: + data["concrete_subclasses"] = class_info.concrete_inheritors + + return {"data": data} + + +## Resolve a loaded global-class script to its native base type, or an error if +## the script failed to load (not a Script) or to compile (empty base type). +## Shared by the create and get_info custom-Resource paths so both report a +## compile failure rather than a misleading "is not a Resource type (extends )". +static func _script_base_type_or_error(scr: Variant, type_str: String, script_path: String) -> Variant: + if not (scr is Script): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to load script class %s from %s" % [type_str, script_path]) + var base_type: StringName = scr.get_instance_base_type() + if String(base_type).is_empty(): + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "%s failed to compile or parse (script %s)" % [type_str, script_path]) + return base_type + + +## get_info for a project `class_name` Resource (not in ClassDB). Returns an info +## dict, an error dict (for a class_name whose native base is not a Resource), or +## null if `type_str` is not a registered global class. Read-only: resolves +## properties from the script + its native base WITHOUT instantiating (no _init()). +static func _custom_resource_info(type_str: String) -> Variant: + for entry in ProjectSettings.get_global_class_list(): + if entry.get("class", "") != type_str: + continue + var script_path: String = entry.get("path", "") + var scr: Variant = load(script_path) + var base_or_err: Variant = _script_base_type_or_error(scr, type_str, script_path) + if base_or_err is Dictionary: + return base_or_err + var base_type: StringName = base_or_err + if not ClassDB.is_parent_class(base_type, "Resource"): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "%s is not a Resource type (extends %s)" % [type_str, base_type]) + var can_instantiate: bool = scr.can_instantiate() + # Inherited (native) properties come from the engine base via ClassDB... + var class_info := ClassIntrospection.build(String(base_type), { + "sections": ["properties"], + "include_inherited": true, + "limit": 0, + }) + var props: Array = [] + for native_prop in class_info.properties: + props.append(native_prop) + # ...and the script's own (and inherited script) exported properties come + # from the Script itself, so we never construct the resource. A real + # default isn't available without instantiating, so script props carry an + # explicit null — keeping one uniform key set across the array (native + # props carry their real default). + for raw_prop in scr.get_script_property_list(): + var prop: Dictionary = raw_prop + var usage := int(prop.get("usage", 0)) + if not (usage & PROPERTY_USAGE_EDITOR): + continue + props.append({ + "name": str(prop.get("name", "")), + "type": type_string(int(prop.get("type", TYPE_NIL))), + "class_name": str(prop.get("class_name", "")), + "hint": int(prop.get("hint", PROPERTY_HINT_NONE)), + "hint_string": str(prop.get("hint_string", "")), + "usage": usage, + "default": null, + }) + props.sort_custom(func(a, b): return a.name < b.name) + # parent_class is the immediate script parent when there is one (so a + # multi-level chain B -> A -> Resource reports A), else the native base. + var parent_name := String(base_type) + var base_script: Variant = scr.get_base_script() + if base_script is Script and not String(base_script.get_global_name()).is_empty(): + parent_name = String(base_script.get_global_name()) + return {"data": { + "type": type_str, + "parent_class": parent_name, + "can_instantiate": can_instantiate, + # is_abstract reflects real abstractness (the @abstract annotation), + # NOT editor-instantiability — a non-@tool concrete Resource has + # can_instantiate()==false in-editor but is not abstract. + "is_abstract": scr.is_abstract(), + "properties": props, + "property_count": props.size(), + }} + return null diff --git a/addons/godot_ai/handlers/resource_handler.gd.uid b/addons/godot_ai/handlers/resource_handler.gd.uid new file mode 100644 index 0000000..d79d3cf --- /dev/null +++ b/addons/godot_ai/handlers/resource_handler.gd.uid @@ -0,0 +1 @@ +uid://dwwd0n3c56ir diff --git a/addons/godot_ai/handlers/scene_handler.gd b/addons/godot_ai/handlers/scene_handler.gd new file mode 100644 index 0000000..1c1f2b4 --- /dev/null +++ b/addons/godot_ai/handlers/scene_handler.gd @@ -0,0 +1,420 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles scene tree reading and node search. + +var _connection: McpConnection +var _save_scene_callable: Callable = Callable() +var _save_scene_as_callable: Callable = Callable() + + +func _init(connection: McpConnection = null) -> void: + _connection = connection + + +func get_scene_tree(params: Dictionary) -> Dictionary: + var max_depth: int = params.get("depth", 10) + var offset: int = maxi(0, int(params.get("offset", 0))) + # limit <= 0 means "no limit" (the hierarchy resource reads the whole tree); + # the scene_get_hierarchy tool passes an explicit positive limit. Paginating + # here — rather than walking + serializing the full tree and slicing on the + # Python side — means only the requested window builds node dicts and clean + # scene paths, and only the window crosses the WebSocket. + var limit: int = int(params.get("limit", 0)) + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root == null: + return {"data": { + "nodes": [], + "total_count": 0, + "offset": offset, + "limit": limit, + "has_more": false, + "message": "No scene open", + }} + + var nodes: Array[Dictionary] = [] + # index_ref[0] is the running DFS index shared across the recursion (Arrays + # pass by reference in GDScript). The walk still visits every node to get an + # accurate total_count, but only materializes those inside the window. + var index_ref: Array[int] = [0] + # _walk_tree self-seeds the root's path for full reads; pass "" explicitly. + _walk_tree(scene_root, nodes, 0, max_depth, scene_root, offset, limit, index_ref, "") + var total: int = index_ref[0] + return {"data": { + "nodes": nodes, + "total_count": total, + "offset": offset, + "limit": limit, + "has_more": limit > 0 and offset + limit < total, + }} + + +func get_open_scenes(_params: Dictionary) -> Dictionary: + var scene_paths := EditorInterface.get_open_scenes() + var scene_root := EditorInterface.get_edited_scene_root() + var current := scene_root.scene_file_path if scene_root else "" + return { + "data": { + "scenes": scene_paths, + "current_scene": current, + "count": scene_paths.size(), + } + } + + +func find_nodes(params: Dictionary) -> Dictionary: + var name_filter: String = params.get("name", "") + var type_filter: String = params.get("type", "") + var group_filter: String = params.get("group", "") + + if name_filter.is_empty() and type_filter.is_empty() and group_filter.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "At least one filter (name, type, group) is required") + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var results: Array[Dictionary] = [] + _find_recursive(scene_root, scene_root, name_filter, type_filter, group_filter, results) + return {"data": {"nodes": results, "count": results.size()}} + + +func _find_recursive(node: Node, scene_root: Node, name_filter: String, type_filter: String, group_filter: String, out: Array[Dictionary]) -> void: + var matches := true + + if not name_filter.is_empty(): + if node.name.to_lower().find(name_filter.to_lower()) == -1: + matches = false + + if matches and not type_filter.is_empty(): + if node.get_class() != type_filter: + matches = false + + if matches and not group_filter.is_empty(): + if not node.is_in_group(group_filter): + matches = false + + if matches: + out.append({ + "name": node.name, + "type": node.get_class(), + "path": McpScenePath.from_node(node, scene_root), + }) + + for child in node.get_children(): + _find_recursive(child, scene_root, name_filter, type_filter, group_filter, out) + + +## Create a new scene with the given root node type, save to disk, and open it. +func create_scene(params: Dictionary) -> Dictionary: + var root_type: String = params.get("root_type", "Node3D") + var path: String = params.get("path", "") + + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var path_err = McpPathValidator.path_error(path, "path", true) + if path_err != null: + return path_err + + if not path.ends_with(".tscn") and not path.ends_with(".scn"): + path += ".tscn" + + if not ClassDB.class_exists(root_type): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unknown node type: %s" % root_type) + if not ClassDB.is_parent_class(root_type, "Node"): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "%s is not a Node type" % root_type) + + # Ensure parent directory exists + var dir_path := path.get_base_dir() + if not DirAccess.dir_exists_absolute(dir_path): + var err := DirAccess.make_dir_recursive_absolute(dir_path) + if err != OK: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to create directory: %s" % dir_path) + + var root: Node = ClassDB.instantiate(root_type) + if root == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s" % root_type) + + var root_name: String = params.get("root_name", "") + if root_name.is_empty(): + root_name = path.get_file().get_basename() + root.name = root_name + + if _connection: + _connection.pause_processing = true + var err := _pack_and_save_with_uid(root, path) + if err == OK: + EditorInterface.open_scene_from_path(path) + if _connection: + _connection.pause_processing = false + + if err != OK: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to save scene: %s" % error_string(err)) + + return { + "data": { + "path": path, + "root_type": root_type, + "root_name": root_name, + "undoable": false, + "reason": "Scene creation involves file system operations", + } + } + + +## Pack `root` and save it to `path`, embedding a fresh uid or preserving the +## one `path` already had — the exact save sequence `create_scene` runs, +## minus the `pause_processing` guard (the caller owns that, since it also +## needs to bracket `open_scene_from_path`) and minus opening the scene +## (switching the editor's active scene isn't safe inside the shared test +## runner, so tests call this directly instead of going through +## `create_scene` end-to-end). Frees `root`. Returns `OK`, or the first +## `Error` encountered. +func _pack_and_save_with_uid(root: Node, path: String) -> Error: + var packed := PackedScene.new() + packed.pack(root) + root.free() + + # Captured BEFORE the save below overwrites the file — see + # McpResourceIO.ensure_uid's doc comment. + var prior_uid := ResourceLoader.get_resource_uid(path) if FileAccess.file_exists(path) else ResourceUID.INVALID_ID + + var err := ResourceSaver.save(packed, path) + if err == OK: + err = McpResourceIO.ensure_uid(path, prior_uid) + return err + + +## How long open_scene waits for the editor to actually switch to the +## requested scene before replying switched=false. Tab switches normally land +## within a few frames; keep this under the dispatcher's 4500 ms deferred +## default so the coroutine always answers before DEFERRED_TIMEOUT fires. +const _OPEN_SETTLE_MAX_MSEC := 3000 + + +## Open an existing scene by file path. +func open_scene(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var force_reload: bool = params.get("force_reload", false) + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var path_err = McpPathValidator.loadable_error(path, "path") + if path_err != null: + return path_err + + if not ResourceLoader.exists(path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Scene not found: %s" % path) + + var scene_root := EditorInterface.get_edited_scene_root() + var current_path := scene_root.scene_file_path if scene_root else "" + ## Instance id of the root at call time. A completed open OR reload always + ## replaces the edited-scene root with a NEW instance, so this is the + ## reliable completion signal — unlike scene_file_path, which is unchanged + ## across a force_reload of the already-open scene (#633 review). + var prev_root_id := scene_root.get_instance_id() if scene_root else 0 + var payload := { + "path": path, + "force_reload": force_reload, + "reloaded_from_disk": false, + "previous_scene_path": current_path, + "undoable": false, + "reason": "Scene navigation cannot be undone via editor undo", + } + + if current_path == path and not force_reload: + ## Already the edited scene — nothing switches, reply immediately. + payload["switched"] = true + payload["settle"] = "already_current" + return {"data": payload} + + if force_reload and current_path == path: + EditorInterface.reload_scene_from_path(path) + payload["reloaded_from_disk"] = true + else: + EditorInterface.open_scene_from_path(path) + + ## The tab switch completes asynchronously; replying now lets an immediate + ## follow-up write land on the PREVIOUS scene (#633 — a scene_save issued + ## right after open_scene saved the old scene). Defer the reply until the + ## edited scene actually is `path` AND its root is a fresh instance, so + ## success means "the editor is now editing the (re)loaded scene". + var request_id: String = params.get("_request_id", "") + if _connection != null and not request_id.is_empty(): + _finish_open_scene_deferred(_connection, request_id, path, prev_root_id, payload) + return McpDispatcher.DEFERRED_RESPONSE + + ## Synchronous fallback (batch_execute and unit-test contexts can't await): + ## preserve the old reply-immediately behavior, flagged as not waited on. + payload["switched"] = false + payload["settle"] = "not_waited" + return {"data": payload} + + +## `static` is load-bearing (same reason as FilesystemHandler's deferred scan +## finish): the coroutine must outlive this RefCounted handler, which can be +## freed mid-await by an editor_reload_plugin. Parameterise everything; +## reference no instance state. +static func _finish_open_scene_deferred( + connection: McpConnection, + request_id: String, + path: String, + prev_root_id: int, + payload: Dictionary, +) -> void: + if not is_instance_valid(connection): + return + var tree := connection.get_tree() + if tree == null: + return + # Hand back a frame so _dispatch() registers this request as deferred + # before the coroutine can push a reply. + await tree.process_frame + var deadline_ms := Time.get_ticks_msec() + _OPEN_SETTLE_MAX_MSEC + while Time.get_ticks_msec() < deadline_ms: + var root := EditorInterface.get_edited_scene_root() + # Require BOTH the target path AND a fresh root instance: a + # force_reload keeps scene_file_path == path across the reload, so the + # instance swap is what proves the (re)load actually completed rather + # than the coroutine settling on the stale pre-reload root. + if root != null and root.scene_file_path == path and root.get_instance_id() != prev_root_id: + if not is_instance_valid(connection): + return + payload["switched"] = true + payload["settle"] = "settled" + connection.send_deferred_response(request_id, {"data": payload}) + return + await tree.process_frame + if not is_instance_valid(connection): + return + payload["switched"] = false + payload["settle"] = "timeout" + connection.send_deferred_response(request_id, {"data": payload}) + + +## Save the currently edited scene. +## Pauses WebSocket processing during save to prevent re-entrant _process() +## calls during EditorNode::_save_scene_with_preview's thumbnail render. +func save_scene(_params: Dictionary) -> Dictionary: + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var path := scene_root.scene_file_path + if path.is_empty(): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Current scene has never been saved; call scene_manage(op='save_as') with a res://... path ending in .tscn or .scn." + ) + + if _connection: + _connection.pause_processing = true + var err := _save_current_scene() + if _connection: + _connection.pause_processing = false + + if err != OK: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to save scene: %s" % error_string(err)) + + return { + "data": { + "path": path, + "undoable": false, + "reason": "File save cannot be undone via editor undo", + } + } + + +## Save the currently edited scene to a new file path. +func save_scene_as(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var path_err = McpPathValidator.path_error(path, "path", true) + if path_err != null: + return path_err + + if not path.ends_with(".tscn") and not path.ends_with(".scn"): + path += ".tscn" + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + # Ensure parent directory exists + var dir_path := path.get_base_dir() + if not DirAccess.dir_exists_absolute(dir_path): + var err := DirAccess.make_dir_recursive_absolute(dir_path) + if err != OK: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to create directory: %s" % dir_path) + + if _connection: + _connection.pause_processing = true + _save_current_scene_as(path) + if _connection: + _connection.pause_processing = false + + return { + "data": { + "path": path, + "undoable": false, + "reason": "File save cannot be undone via editor undo", + } + } + + +func _save_current_scene() -> int: + if _save_scene_callable.is_valid(): + return int(_save_scene_callable.call()) + return EditorInterface.save_scene() + + +func _save_current_scene_as(path: String) -> void: + if _save_scene_as_callable.is_valid(): + _save_scene_as_callable.call(path) + return + EditorInterface.save_scene_as(path) + + +func _walk_tree(node: Node, out: Array[Dictionary], depth: int, max_depth: int, scene_root: Node, offset: int, limit: int, index_ref: Array[int], node_path: String) -> void: + if depth > max_depth: + return + var idx: int = index_ref[0] + index_ref[0] = idx + 1 + # Materialize only nodes inside the [offset, offset+limit) window. Outside + # it we still recurse (to count total_count) but skip the per-node dict. + # + # Path build strategy depends on the read shape (identical output either way): + # * A whole-tree read (offset == 0 and limit <= 0 — the resource-style read + # backing godot://scene/hierarchy) threads the parent's clean path down the + # DFS: each node's path is one O(1) concat reusing the descent, instead of + # McpScenePath.from_node's two native walks back up (is_ancestor_of + + # get_path_to). Benchmarked ~1.8x faster on a ~1.5k-node tree, up to ~5x on + # deep chains. + # * Any windowed read (limit > 0, or an offset > 0 skip) keeps from_node for + # just the emitted nodes: threading would concatenate a path for every node + # visited for total_count, which benchmarks ~20% slower for a small window. + # + # `node_path` is self-seeded at the scene root below, so a caller cannot leave + # a full read unseeded (it has no default — pass "" for windowed reads). + var incremental := limit <= 0 and offset == 0 + if incremental and node == scene_root: + node_path = "/" + String(scene_root.name) + var in_window := idx >= offset and (limit <= 0 or idx < offset + limit) + if in_window: + out.append({ + "name": node.name, + "type": node.get_class(), + "path": node_path if incremental else McpScenePath.from_node(node, scene_root), + "children_count": node.get_child_count(), + }) + for child in node.get_children(): + var child_path := (node_path + "/" + String(child.name)) if incremental else "" + _walk_tree(child, out, depth + 1, max_depth, scene_root, offset, limit, index_ref, child_path) diff --git a/addons/godot_ai/handlers/scene_handler.gd.uid b/addons/godot_ai/handlers/scene_handler.gd.uid new file mode 100644 index 0000000..af3711f --- /dev/null +++ b/addons/godot_ai/handlers/scene_handler.gd.uid @@ -0,0 +1 @@ +uid://7ms40gm6t2r4 diff --git a/addons/godot_ai/handlers/script_handler.gd b/addons/godot_ai/handlers/script_handler.gd new file mode 100644 index 0000000..698b462 --- /dev/null +++ b/addons/godot_ai/handlers/script_handler.gd @@ -0,0 +1,501 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const DiagnosticsCapture := preload("res://addons/godot_ai/utils/diagnostics_capture.gd") +const ValidationLogger := preload("res://addons/godot_ai/runtime/validation_logger.gd") + +## Handles script creation, reading, attaching, detaching, and symbol inspection. + +var _undo_redo: EditorUndoRedoManager +var _connection: McpConnection + +# The bounded import-settle window and the deferred completion coroutine +# live on McpResourceIO since #714 — write_file's fresh-`.gd` path shares +# them, so create_script and write_file can't drift apart again (#261). + +func _init(undo_redo: EditorUndoRedoManager, connection: McpConnection = null) -> void: + _undo_redo = undo_redo + _connection = connection + + +func create_script(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var content: String = params.get("content", "") + + var path_err = McpPathValidator.path_error(path, "path", true) + if path_err != null: + return path_err + + if not path.ends_with(".gd"): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Path must end with .gd") + + var existed_before := FileAccess.file_exists(path) + + # Shared write path (#714): parent mkdir + write/flush + explicit error + # check live on McpResourceIO so write_file can't drift from this again. + var write_failure: Variant = McpResourceIO.write_text_to_disk(path, content) + if write_failure != null: + return write_failure + + var data := { + "path": path, + "size": content.length(), + "committed": true, + "import_settled": existed_before, + "import_settle": "already_known" if existed_before else "not_waited", + "undoable": false, + "reason": "File system operations cannot be undone via editor undo", + } + _attach_gdscript_diagnostics(data, path, content) + + # A freshly-declared `class_name` is NOT in the global class table until a + # filesystem scan runs — update_file() below registers the file with the + # resource pipeline but not the class registry (see the scan() comment). + # Surface that precisely (only when the class isn't already registered) so a + # headless caller knows to follow up with filesystem_manage(op="scan") + # instead of hitting a confusing "Unknown type" / "Unknown resource type" on + # the very next call. We don't scan here — a scan() per create is the exact + # SIGABRT race documented below; the explicit op is single-flight. + # Skip the hint when the script failed to parse: a scan won't register a + # class from a broken script, so pointing at op="scan" would steer the caller + # away from the real fix (the parse error already attached above). + var declared_class := _extract_class_name(content) + if ( + not declared_class.is_empty() + and not _script_has_error_diagnostics(data) + and not _class_name_registered(declared_class) + ): + data["class_name"] = declared_class + data["class_registration"] = "scan_required" + data["class_registration_hint"] = ( + "New class_name '%s' isn't in the global class table yet. " % declared_class + + "Call filesystem_manage(op=\"scan\") if it won't resolve on the next " + + "call (e.g. resource_manage op=\"create\", or used as a type in another " + + "script). The editor also registers it on its next filesystem scan or " + + "when its window regains focus." + ) + + # Register just this file with the editor instead of a full recursive + # scan(). A scan() per write stacks `update_scripts_classes` / + # `update_script_paths_documentation` WorkerThreadPool tasks under concurrent + # script creation ("Task ... already exists" / "!tasks.has(p_task)"), which + # races the global-class registry and can SIGABRT in + # ScriptServer::remove_global_class_by_path (see dsarno/godot#6). + # update_file() is the single-file path the rest of the plugin already uses. + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(path) + + # `.gd.uid` is the sidecar Godot generates on scan; list both so the caller + # can rm the full set in one go. + McpResourceIO.attach_cleanup_hint(data, existed_before, [path, path + ".uid"]) + + # scan() is async — ResourceLoader.exists(path) returns false until Godot's + # filesystem pipeline finishes. If we reply now, an immediate attach_script + # races and 404s (#261). Defer the response until the resource is visible + # (or a bounded timeout elapses). For freshly-created files we wait; on + # overwrite the resource was already known to ResourceLoader, so reply now. + var request_id: String = params.get("_request_id", "") + if not existed_before and _connection != null and not request_id.is_empty(): + McpResourceIO.finish_text_write_deferred(_connection, request_id, path, data) + return McpDispatcher.DEFERRED_RESPONSE + + # Synchronous fallback: batch_execute (no request_id) and unit-test contexts + # (no connection) get the immediate reply that the previous behaviour gave. + return {"data": data} + + +## Extract the `class_name` a script declares, or "" if none. A cheap line scan +## (no full parse) for create_script's "scan_required" hint. Stops at the first +## space/tab or comma so all three valid forms yield just the name: +## `class_name Foo`, `class_name Foo extends Bar`, and the icon form +## `class_name Foo, "res://icon.svg"`. +static func _extract_class_name(content: String) -> String: + for raw_line in content.split("\n"): + var line := raw_line.strip_edges() + if line.begins_with("class_name "): + var rest := line.substr(11).strip_edges() + var cut := rest.length() + for i in rest.length(): + var ch := rest[i] + if ch == " " or ch == "\t" or ch == ",": + cut = i + break + return rest.substr(0, cut) + return "" + + +## True if create_script's diagnostics captured a parse error for this script. +## Used to suppress the "scan_required" hint when the class can't register +## anyway — see create_script. +static func _script_has_error_diagnostics(data: Dictionary) -> bool: + for diag in data.get("diagnostics", []): + if diag is Dictionary and diag.get("level", "") == "error": + return true + return false + + +## True if `cn` is already usable as a type — an engine built-in (ClassDB) or an +## already-registered project global class. A brand-new class_name returns false +## until a filesystem scan registers it. +static func _class_name_registered(cn: String) -> bool: + if ClassDB.class_exists(cn): + return true + for entry in ProjectSettings.get_global_class_list(): + if entry.get("class", "") == cn: + return true + return false + + +func read_script(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + + var path_err = McpPathValidator.path_error(path, "path") + if path_err != null: + return path_err + + if not FileAccess.file_exists(path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "File not found: %s" % path) + + var file := FileAccess.open(path, FileAccess.READ) + if file == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to open file: %s" % path) + + var content := file.get_as_text() + file.close() + + return { + "data": { + "path": path, + "content": content, + "size": content.length(), + "line_count": content.count("\n") + (1 if not content.is_empty() else 0), + } + } + + +## Instance (not static) despite using no instance state: tests stub +## `_capture_gdscript_load_diagnostics` via subclass override, and static +## calls bind lexically — see test_script.gd. filesystem_handler shares +## this by instantiating a bare ScriptHandler (#714). +func _attach_gdscript_diagnostics(data: Dictionary, path: String, content: String) -> void: + var validation := _validate_gdscript_source(content) + var diagnostics: Array = [] + var diagnostics_detail := "none" + var diagnostics_status := "checked" + + if not validation.get("ok", true): + var capture := _capture_gdscript_load_diagnostics(path) + diagnostics = capture.get("diagnostics", []) + diagnostics_detail = capture.get("diagnostics_detail", "none") + diagnostics_status = capture.get("diagnostics_status", "checked") + if not validation.get("ok", true) and diagnostics.is_empty(): + diagnostics.append(_fallback_gdscript_diagnostic(path, validation.get("error_code", FAILED), content)) + diagnostics_detail = "fallback" + data["diagnostics"] = diagnostics + data["diagnostics_detail"] = diagnostics_detail + data["diagnostics_scope"] = "this_file" + data["diagnostics_status"] = diagnostics_status + + +static func _validate_gdscript_source(content: String) -> Dictionary: + var script := GDScript.new() + script.source_code = content + ## Keep validation off the live cached resource: assigning resource_path to + ## this ephemeral Script can collide with loaded instances. reload() still + ## performs normal GDScript analysis, including static initializer work, so + ## this check is intentionally scoped to `.gd` writes where the editor would + ## compile the file on scan anyway. + var err := script.reload() + return { + "ok": err == OK, + "error_code": err, + } + + +func _capture_gdscript_load_diagnostics(path: String) -> Dictionary: + var buffer := McpEditorLogBuffer.new() + var logger := ValidationLogger.new(buffer) + var capture := DiagnosticsCapture.capture_this_file(buffer, path, func() -> Dictionary: + OS.add_logger(logger) + # ResourceLoader.load() reports parse failure instead of throwing, and + # a failed GDScript parse does not execute user code; remove immediately + # after the synchronous load to keep the private capture window tiny. + ResourceLoader.load(path, "", ResourceLoader.CACHE_MODE_IGNORE) + OS.remove_logger(logger) + return {} + ) + return capture + + +static func _fallback_gdscript_diagnostic(path: String, error_code: int, content: String) -> Dictionary: + var line := _fallback_gdscript_error_line(content) + return { + "source": "editor", + "level": "error", + "text": "GDScript reload failed with error code %d." % error_code, + "path": path, + "line": line, + "function": "GDScript::reload", + "details": { + "code": "gdscript_reload_failed", + "error_code": error_code, + "fallback_line": true, + "source": { + "path": path, + "line": line, + }, + }, + } + + +static func _fallback_gdscript_error_line(content: String) -> int: + var lines := content.split("\n") + for i in range(lines.size() - 1, -1, -1): + if not str(lines[i]).strip_edges().is_empty(): + return i + 1 + return 1 + + +func patch_script(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var old_text: String = params.get("old_text", "") + var new_text: String = params.get("new_text", "") + var replace_all: bool = params.get("replace_all", false) + + var path_err = McpPathValidator.path_error(path, "path", true) + if path_err != null: + return path_err + if not "old_text" in params: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: old_text") + if not "new_text" in params: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: new_text") + if not path.ends_with(".gd"): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Path must end with .gd (use filesystem_write_text for other text files)") + if old_text.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "old_text must not be empty") + + var read := FileAccess.open(path, FileAccess.READ) + if read == null: + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "File not found or unreadable: %s" % path) + var content := read.get_as_text() + read.close() + + var match_count := content.count(old_text) + if match_count == 0: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "old_text not found in %s" % path) + if match_count > 1 and not replace_all: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "old_text matches %d times; pass replace_all=true or provide a more specific snippet" % match_count, + ) + + var new_content: String + var replacements: int + if replace_all: + new_content = content.replace(old_text, new_text) + replacements = match_count + else: + var idx := content.find(old_text) + new_content = content.substr(0, idx) + new_text + content.substr(idx + old_text.length()) + replacements = 1 + + # Shared write path (#714). No import-settle deferral here: the file + # already exists, so ResourceLoader knows it and there is no scan to wait + # for — same rationale as create_script's overwrite arm. + var write_failure: Variant = McpResourceIO.write_text_to_disk(path, new_content) + if write_failure != null: + return write_failure + + var data := { + "path": path, + "replacements": replacements, + "size": new_content.length(), + "old_size": content.length(), + "undoable": false, + "reason": "File system operations cannot be undone via editor undo", + } + _attach_gdscript_diagnostics(data, path, new_content) + + # Single-file register, not a full scan() — see create_script (dsarno/godot#6). + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(path) + + return {"data": data} + + +func attach_script(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + var script_path: String = params.get("script_path", "") + + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + if script_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: script_path") + + var spath_err = McpPathValidator.loadable_error(script_path, "script_path") + if spath_err != null: + return spath_err + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + + if not ResourceLoader.exists(script_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Script not found: %s" % script_path) + + var script: Script = load(script_path) + if script == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to load script: %s" % script_path) + + var old_script: Script = node.get_script() + + _undo_redo.create_action("MCP: Attach script to %s" % node.name) + _undo_redo.add_do_method(node, "set_script", script) + _undo_redo.add_undo_method(node, "set_script", old_script) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "script_path": script_path, + "had_previous_script": old_script != null, + "undoable": true, + } + } + + +func detach_script(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + + var old_script: Script = node.get_script() + if old_script == null: + return {"data": {"path": node_path, "had_script": false, "undoable": false, "reason": "No script attached"}} + + _undo_redo.create_action("MCP: Detach script from %s" % node.name) + _undo_redo.add_do_method(node, "set_script", null) + _undo_redo.add_undo_method(node, "set_script", old_script) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "removed_script": old_script.resource_path if old_script.resource_path else "(inline)", + "undoable": true, + } + } + + +func find_symbols(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + + var path_err = McpPathValidator.path_error(path, "path") + if path_err != null: + return path_err + + if not FileAccess.file_exists(path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "File not found: %s" % path) + + var file := FileAccess.open(path, FileAccess.READ) + if file == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to open file: %s" % path) + + var content := file.get_as_text() + file.close() + + var functions: Array[Dictionary] = [] + var signals_list: Array[String] = [] + var exports: Array[Dictionary] = [] + var class_name_str := "" + var extends_str := "" + + var lines := content.split("\n") + for i in lines.size(): + var line := lines[i].strip_edges() + + # class_name — same cut logic as _extract_class_name so the + # `extends Bar` / icon-form tails don't leak into the symbol name. + if line.begins_with("class_name "): + var cn_rest := line.substr(11).strip_edges() + var cn_cut := cn_rest.length() + for ci in cn_rest.length(): + var cn_ch := cn_rest[ci] + if cn_ch == " " or cn_ch == "\t" or cn_ch == ",": + cn_cut = ci + break + class_name_str = cn_rest.substr(0, cn_cut) + + # extends + if line.begins_with("extends "): + extends_str = line.substr(8).strip_edges() + + # signal + if line.begins_with("signal "): + var sig_text := line.substr(7).strip_edges() + # Strip any parameters for the name + var paren_idx := sig_text.find("(") + if paren_idx >= 0: + signals_list.append(sig_text.substr(0, paren_idx).strip_edges()) + else: + signals_list.append(sig_text) + + # func (including `static func` — strip the leading `static ` first) + var func_line := line.substr(7).strip_edges() if line.begins_with("static func ") else line + if func_line.begins_with("func "): + var func_text := func_line.substr(5).strip_edges() + var paren_idx := func_text.find("(") + if paren_idx >= 0: + functions.append({ + "name": func_text.substr(0, paren_idx).strip_edges(), + "line": i + 1, + }) + + # @export + if line.begins_with("@export"): + # Next non-empty line should have the var declaration + # But often export and var are on the same logical flow + # Try to find "var" on the same line or the next line + var var_line := line + if var_line.find("var ") == -1 and i + 1 < lines.size(): + var_line = lines[i + 1].strip_edges() + var var_idx := var_line.find("var ") + if var_idx >= 0: + var rest := var_line.substr(var_idx + 4).strip_edges() + # Extract variable name (up to : or = or end) + var end_idx := rest.length() + for ch_idx in rest.length(): + if rest[ch_idx] == ":" or rest[ch_idx] == "=" or rest[ch_idx] == " ": + end_idx = ch_idx + break + exports.append({ + "name": rest.substr(0, end_idx), + "line": i + 1, + }) + + return { + "data": { + "path": path, + "class_name": class_name_str, + "extends": extends_str, + "functions": functions, + "signals": signals_list, + "exports": exports, + "function_count": functions.size(), + "signal_count": signals_list.size(), + "export_count": exports.size(), + } + } diff --git a/addons/godot_ai/handlers/script_handler.gd.uid b/addons/godot_ai/handlers/script_handler.gd.uid new file mode 100644 index 0000000..6be1ac4 --- /dev/null +++ b/addons/godot_ai/handlers/script_handler.gd.uid @@ -0,0 +1 @@ +uid://dhub87454jxb3 diff --git a/addons/godot_ai/handlers/signal_handler.gd b/addons/godot_ai/handlers/signal_handler.gd new file mode 100644 index 0000000..ad85c7d --- /dev/null +++ b/addons/godot_ai/handlers/signal_handler.gd @@ -0,0 +1,274 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles signal listing, connecting, and disconnecting on scene nodes. + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +func list_signals(params: Dictionary) -> Dictionary: + var path_value: Variant = params.get("path", "") + var path_type_err = McpParamValidators.require_string("path", path_value) + if path_type_err != null: + return path_type_err + ## String(...) conversion: require_string accepts StringName too, and + ## a bare typed assignment from StringName would defeat the guard. + var path: String = String(path_value) + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var _resolved := McpNodeValidator.resolve_or_error(path, "path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var scene_root: Node = _resolved.scene_root + + ## Default: hide editor-internal connections (SceneTreeEditor observers + ## live on every scene node and would otherwise dominate the response). + ## Pass include_editor=true to see them. See #213. + var include_editor: bool = params.get("include_editor", false) + + var signals: Array[Dictionary] = [] + for sig in node.get_signal_list(): + var args: Array[Dictionary] = [] + for arg in sig.get("args", []): + args.append({"name": arg.get("name", ""), "type": type_string(arg.get("type", 0))}) + signals.append({ + "name": sig.get("name", ""), + "args": args, + }) + + var connections: Array[Dictionary] = [] + var editor_connection_count := 0 + for sig in signals: + for conn in node.get_signal_connection_list(sig.name): + var callable: Callable = conn.get("callable", Callable()) + var target := callable.get_object() + if target == null: + continue # skip connections to freed objects + if not include_editor and _is_editor_internal_target(target, scene_root): + editor_connection_count += 1 + continue + connections.append({ + "signal": sig.name, + "target": _format_target_path(target, scene_root), + "method": callable.get_method(), + }) + + return { + "data": { + "path": McpScenePath.from_node(node, scene_root), + "signals": signals, + "signal_count": signals.size(), + "connections": connections, + "connection_count": connections.size(), + "editor_connection_count": editor_connection_count, + } + } + + +## A target is "editor-internal" when it's a Node sitting outside the edited +## scene tree AND not anywhere under a declared autoload — typical case is +## the SceneTreeEditor dock listening for visibility/script/state changes on +## every scene node. Connections to autoloads (declared under ``autoload/*`` +## in ProjectSettings) are user-authored even though they live under +## ``/root/`` rather than under the edited scene root, so the autoload +## root *and* any descendant of it stay visible. Non-Node targets +## (anonymous Callables, RefCounted listeners etc.) also stay visible — we +## can't reliably classify them. +func _is_editor_internal_target(target: Object, scene_root: Node) -> bool: + if not (target is Node): + return false + var node_target: Node = target + if node_target == scene_root: + return false + if scene_root.is_ancestor_of(node_target): + return false + if _is_under_autoload(node_target): + return false + return true + + +## True if `node` is a declared autoload root or sits anywhere under one. +## When the node is in the SceneTree we read its absolute path +## (``/root//...``) and check the first segment after ``/root/``; +## this covers connections to deep descendants of editor-instanced +## autoloads (e.g. ``/root/MyAutoload/Foo/Bar``). When the node isn't in +## the tree (test fixtures often construct nodes in isolation), we walk +## the parent chain and match each ancestor's ``name`` against the +## autoload key as a best-effort fallback. +static func _is_under_autoload(node: Node) -> bool: + if node.is_inside_tree(): + var path := str(node.get_path()) + if not path.begins_with("/root/"): + return false + var first_segment := path.substr(6).split("/", true, 1)[0] + return ProjectSettings.has_setting("autoload/" + first_segment) + var cursor: Node = node + while cursor != null: + if ProjectSettings.has_setting("autoload/" + str(cursor.name)): + return true + cursor = cursor.get_parent() + return false + + +## Serialize a connection's target path. Descendants of (or equal to) the +## edited scene root render as the usual scene-relative form +## (``/Main/Camera3D``). Non-descendants — autoload subtrees in particular +## — render as their canonical absolute SceneTree path +## (``/root/MyAutoload/Child``) instead of a scene-relative path full of +## ``..`` segments, which agents can't navigate back to. Non-Node targets +## (anonymous Callables, etc.) fall back to their string representation. +static func _format_target_path(target: Object, scene_root: Node) -> String: + if not (target is Node): + return str(target) + var node_target: Node = target + if node_target == scene_root or scene_root.is_ancestor_of(node_target): + return McpScenePath.from_node(node_target, scene_root) + if node_target.is_inside_tree(): + return str(node_target.get_path()) + return McpScenePath.from_node(node_target, scene_root) + + +func connect_signal(params: Dictionary) -> Dictionary: + var resolved := _resolve_signal_params(params) + if resolved.has("error"): + return resolved + + var source: Node = resolved.source + var target: Node = resolved.target + var signal_name: String = resolved.signal_name + var method: String = resolved.method + var scene_root: Node = resolved.scene_root + + if not source.has_signal(signal_name): + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, "Signal '%s' not found on %s" % [signal_name, params.path]) + + if not target.has_method(method): + return ErrorCodes.make(ErrorCodes.PROPERTY_NOT_ON_CLASS, "Method '%s' not found on %s" % [method, params.target]) + + var callable := Callable(target, method) + if source.is_connected(signal_name, callable): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Signal '%s' already connected to %s.%s" % [signal_name, params.target, method]) + + _undo_redo.create_action("MCP: Connect signal %s" % signal_name) + _undo_redo.add_do_method(source, "connect", signal_name, callable, Object.CONNECT_PERSIST) + _undo_redo.add_undo_method(source, "disconnect", signal_name, callable) + _undo_redo.commit_action() + + return {"data": _signal_response(source, signal_name, target, method, scene_root)} + + +func disconnect_signal(params: Dictionary) -> Dictionary: + var resolved := _resolve_signal_params(params) + if resolved.has("error"): + return resolved + + var source: Node = resolved.source + var target: Node = resolved.target + var signal_name: String = resolved.signal_name + var method: String = resolved.method + var scene_root: Node = resolved.scene_root + + var callable := Callable(target, method) + if not source.is_connected(signal_name, callable): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Signal '%s' is not connected to %s.%s" % [signal_name, params.target, method]) + + # Capture the connection's current flags so undo restores it exactly as it + # was, not unconditionally as CONNECT_PERSIST. Hardcoding PERSIST here would + # silently promote a runtime-only connection into one that serializes on the + # next save. (The connection still exists at this point — checked above.) + var reconnect_flags := 0 + for conn in source.get_signal_connection_list(signal_name): + if conn.get("callable", Callable()) == callable: + reconnect_flags = int(conn.get("flags", 0)) + break + + _undo_redo.create_action("MCP: Disconnect signal %s" % signal_name) + _undo_redo.add_do_method(source, "disconnect", signal_name, callable) + _undo_redo.add_undo_method(source, "connect", signal_name, callable, reconnect_flags) + _undo_redo.commit_action() + + return {"data": _signal_response(source, signal_name, target, method, scene_root)} + + +func _resolve_signal_params(params: Dictionary) -> Dictionary: + for key in ["path", "signal", "target", "method"]: + ## Type-check before calling .is_empty(): a non-string value (e.g. an + ## int or dict) has no is_empty() and would crash the handler, which + ## the dispatcher only reports as an opaque "malformed result" (#210). + var value = params.get(key, "") + var type_err = McpParamValidators.require_string(key, value) + if type_err != null: + return type_err + if value.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: %s" % key) + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var source_result := _resolve_node_or_autoload(params.path, scene_root, "Source") + if source_result.has("error"): + return source_result + var source: Node = source_result.node + + var target_result := _resolve_node_or_autoload(params.target, scene_root, "Target") + if target_result.has("error"): + return target_result + var target: Node = target_result.node + + return { + "source": source, + "target": target, + "signal_name": params.signal, + "method": params.method, + "scene_root": scene_root, + } + + +## Resolve a path to a Node, with three distinct outcomes: +## 1. Found in the edited scene tree → returns {node} +## 2. Declared as an autoload AND instantiated at edit time → returns {node} +## 3. Declared as an autoload but NOT instantiated at edit time → returns +## INVALID_PARAMS with guidance. Most autoloads are runtime-only, so a +## silent "not found" hides the real reason the connection can't be made. +## 4. Not in scene and not a declared autoload → returns INVALID_PARAMS. +func _resolve_node_or_autoload(path: String, scene_root: Node, role: String) -> Dictionary: + var node := McpScenePath.resolve(path, scene_root) + if node != null: + return {"node": node} + + var name := path.trim_prefix("/") + if ProjectSettings.has_setting("autoload/" + name): + # Autoload is declared — see if the editor has it instanced. + var tree := Engine.get_main_loop() + if tree is SceneTree: + var live := (tree as SceneTree).root.get_node_or_null(name) + if live != null: + return {"node": live} + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "%s '%s' is a declared autoload but isn't instantiated in the editor. " % [role, name] + + "Most autoloads are runtime-only; edit-time signal connection isn't supported for them. " + + "Connect it from a script attached to the scene using @onready + connect(), " + + "or enable editor-instancing for this autoload in Project Settings > Autoload.") + + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, + "%s node not found: %s (not in scene tree or autoloads)" % [role, path]) + + +func _signal_response(source: Node, signal_name: String, target: Node, method: String, scene_root: Node) -> Dictionary: + return { + "source": McpScenePath.from_node(source, scene_root), + "signal": signal_name, + "target": McpScenePath.from_node(target, scene_root), + "method": method, + "undoable": true, + } diff --git a/addons/godot_ai/handlers/signal_handler.gd.uid b/addons/godot_ai/handlers/signal_handler.gd.uid new file mode 100644 index 0000000..d95e1d3 --- /dev/null +++ b/addons/godot_ai/handlers/signal_handler.gd.uid @@ -0,0 +1 @@ +uid://b4n8byjeqeddm diff --git a/addons/godot_ai/handlers/test_handler.gd b/addons/godot_ai/handlers/test_handler.gd new file mode 100644 index 0000000..2c0f4ea --- /dev/null +++ b/addons/godot_ai/handlers/test_handler.gd @@ -0,0 +1,349 @@ +@tool +extends RefCounted + +## Discovers and runs McpTestSuite scripts from res://tests/. +## Exposes run_tests and get_test_results as MCP commands. +## +## Live MCP runs service the WebSocket transport between tests +## (McpConnection.service_transport_during_exclusive_run) so a long suite +## can no longer starve the server's keepalive, and abort at a per-call +## ceiling derived from the server-provided time budget. Direct callers, +## unit-test fixtures, and batch contexts (no request id / no connection) +## keep the legacy fully-synchronous behavior with no ceiling. +## See docs/test-run-transport-starvation-plan.md. + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Clamp bounds for the server-provided ``timeout_budget_sec`` param. The +## floor is purely defensive (a malformed or buggy server value must not +## abort every run instantly); the param is not user-facing. +const BUDGET_MIN_SEC := 30.0 +const BUDGET_MAX_SEC := 3600.0 +## Conservative default when the server sent no (or an invalid) budget: an +## old server's own test_run timeout is 120s, and the plugin must abort +## and reply before that future expires. +const BUDGET_DEFAULT_SEC := 110.0 +## Abort this long before the server would time the call out, so the +## partial-results reply beats the server-side timeout. +const CEILING_MARGIN_SEC := 10.0 + +var _runner: McpTestRunner +var _undo_redo: EditorUndoRedoManager +var _log_buffer: McpLogBuffer +## Live plugin dispatcher, exposed to suites via ctx so tests can prove the +## lazy handler registrations (#736) materialize with their real ctor args. +## Optional third arg keeps old two-arg fixtures working; untyped because +## the dispatcher constructs this handler (avoids a load-time type cycle). +var _dispatcher +## Live connection for exclusive-run transport servicing. Null in unit-test +## fixtures and batch contexts, which keep the legacy synchronous path. +var _connection: McpConnection + + +func _init( + undo_redo: EditorUndoRedoManager, + log_buffer: McpLogBuffer, + dispatcher = null, + connection: McpConnection = null, +) -> void: + _runner = McpTestRunner.new() + _undo_redo = undo_redo + _log_buffer = log_buffer + _dispatcher = dispatcher + _connection = connection + + +func run_tests(params: Dictionary) -> Dictionary: + var suite_filter: String = params.get("suite", "") + var test_filter: String = params.get("test_name", "") + var exclude_test_filter: String = params.get("exclude_test_name", "") + var verbose: bool = params.get("verbose", false) + + var request_id: String = params.get("_request_id", "") + var live := _connection != null and not request_id.is_empty() + var service_cb := Callable() + var deadline_ticks_ms := 0 + var budget_sec := 0.0 + var started_ms := Time.get_ticks_msec() + var run_state := {} + if live: + budget_sec = _validated_budget_sec(params) + service_cb = Callable(_connection, "service_transport_during_exclusive_run") + deadline_ticks_ms = started_ms + int((budget_sec - CEILING_MARGIN_SEC) * 1000.0) + + ## Clear the previous run's results BEFORE discovery so an abort at any + ## later point can never expose a stale prior run via get_test_results. + _runner.clear() + + var discovery := _discover_suites(service_cb, deadline_ticks_ms, run_state) + var discovery_outcome: String = discovery.get("outcome", "") + if not discovery_outcome.is_empty(): + ## Aborted during discovery: no suite has begun, so there is no + ## suite teardown to run. Same outcome mapping as the run itself. + var empty_results: Dictionary = _runner.get_results(verbose) + if not discovery.errors.is_empty(): + empty_results["load_errors"] = discovery.errors + return _map_outcome( + discovery_outcome, "discovery", empty_results, 0, started_ms, budget_sec + ) + + var suites: Array = discovery.suites + ## #882: an explicit `suite` filter that matches nothing must say so, not + ## return {"total": 0} — a caller cannot otherwise distinguish "suite has + ## no tests" from "suite was never registered" (truncated discovery). + ## Checked BEFORE the no-suites branch so an empty discovery still names + ## the unmatched filter (with suites_available: []). + var unknown := unknown_suite_error(suite_filter, suites) + if not unknown.is_empty(): + if not discovery.errors.is_empty(): + unknown["error"]["data"]["load_errors"] = discovery.errors + return unknown + + if suites.is_empty(): + var msg := "No test suites found in res://tests/" + if not discovery.errors.is_empty(): + msg += " (%d script(s) failed to load: %s)" % [ + discovery.errors.size(), + ", ".join(discovery.errors), + ] + var no_suites := {"error": msg, "total": 0, "load_errors": discovery.errors} + ## Keep the edited_scene annotation on the no-suites error payload too, + ## so the response contract is consistent across every return path. + _annotate_edited_scene(no_suites) + return {"data": no_suites} + + var ctx := { + "undo_redo": _undo_redo, + "log_buffer": _log_buffer, + "dispatcher": _dispatcher, + } + + var run: Dictionary = _runner.run_suites_serviced( + suites, suite_filter, test_filter, ctx, verbose, exclude_test_filter, + service_cb, deadline_ticks_ms, run_state + ) + var results: Dictionary = run["results"] + if not discovery.errors.is_empty(): + results["load_errors"] = discovery.errors + return _map_outcome( + run["outcome"], "run", results, run["tests_not_run"], started_ms, budget_sec + ) + + +## Empty when `suite_filter` is empty or names a discovered suite; otherwise +## the INVALID_PARAMS protocol error run_tests returns (same ErrorCodes.make +## shape as the paused/timeout aborts — never an error inside a success +## envelope). Static + pure so the suite can pin it without calling +## run_tests() end-to-end (which would recursively re-run the whole corpus +## from inside itself — see test_serviced_test_run.gd). +static func unknown_suite_error(suite_filter: String, suites: Array) -> Dictionary: + if suite_filter.is_empty(): + return {} + var names := PackedStringArray() + for suite: McpTestSuite in suites: + names.append(suite.suite_name()) + if names.has(suite_filter): + return {} + var err := ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + ( + "No suite named '%s' is registered (%d discovered)." + + " If it should exist, discovery may be truncated —" + + " re-import and restart the editor (#882)." + ) % [suite_filter, names.size()], + ) + err["error"]["data"] = { + "suite": suite_filter, + "suites_available": Array(names), + } + return err + + +## Map a runner/discovery outcome onto the response envelope. Ownership is +## deliberately here, not in the runner: the runner reports WHAT happened, +## the handler decides how it goes over the wire (plan D2). +func _map_outcome( + outcome: String, + phase: String, + results: Dictionary, + tests_not_run: int, + started_ms: int, + budget_sec: float, +) -> Dictionary: + var elapsed_ms := Time.get_ticks_msec() - started_ms + match outcome: + "completed": + _annotate_edited_scene(results) + return {"data": results} + "transport_lost": + ## The peer is gone (or flood-closed); the send will fail against + ## the dead socket regardless, but a sync handler must return an + ## envelope. Partials stay retrievable via get_test_results after + ## the plugin reconnects. + results["aborted"] = "transport_lost" + results["tests_not_run"] = tests_not_run + _annotate_edited_scene(results) + return {"data": results} + "paused": + var depth := _connection.pause_depth() if _connection != null else 0 + if _log_buffer != null: + _log_buffer.log( + "[error] test run aborted in %s: transport paused at checkpoint (depth %d)" + % [phase, depth] + ) + var paused_err := ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + ( + "Test run aborted: the MCP transport was paused at a between-test " + + "checkpoint (pause depth %d) — a paused transport cannot service " + + "the WebSocket heartbeat, so continuing would starve the session. " + + "Partial results: test_manage(op=\"results_get\")." + ) % depth + ) + paused_err["error"]["data"] = _abort_data( + phase, results, tests_not_run, elapsed_ms, budget_sec, {"pause_depth": depth} + ) + return paused_err + "timeout": + var timeout_err := ErrorCodes.make( + ErrorCodes.TEST_RUN_TIMEOUT, + ( + "Test run hit its abort ceiling after %.1fs (budget %.0fs, ceiling = " + + "budget - %.0fs): %d passed, %d failed, %d of the selected tests " + + "never ran. Narrow the run with suite=/test_name= filters, or fetch " + + "the partial results with test_manage(op=\"results_get\")." + ) % [ + elapsed_ms / 1000.0, budget_sec, CEILING_MARGIN_SEC, + int(results.get("passed", 0)), int(results.get("failed", 0)), + tests_not_run, + ] + ) + timeout_err["error"]["data"] = _abort_data( + phase, results, tests_not_run, elapsed_ms, budget_sec, {} + ) + return timeout_err + ## Unknown outcome is a runner bug — surface it loudly. + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, "Unknown test run outcome '%s'" % outcome + ) + + +func _abort_data( + phase: String, + results: Dictionary, + tests_not_run: int, + elapsed_ms: int, + budget_sec: float, + extra: Dictionary, +) -> Dictionary: + var data := { + "phase": phase, + "elapsed_ms": elapsed_ms, + "budget_sec": budget_sec, + "passed": int(results.get("passed", 0)), + "failed": int(results.get("failed", 0)), + "skipped": int(results.get("skipped", 0)), + "total": int(results.get("total", 0)), + "tests_not_run": tests_not_run, + } + data.merge(extra) + return data + + +## Strict validation of the server-provided per-call budget: numeric, +## finite, positive, then clamped to [BUDGET_MIN_SEC, BUDGET_MAX_SEC]. +## Everything else (missing, wrong type, NaN/inf, non-positive) falls back +## to BUDGET_DEFAULT_SEC. typeof() so bool never sneaks through as int. +func _validated_budget_sec(params: Dictionary) -> float: + var raw: Variant = params.get("timeout_budget_sec", null) + var t := typeof(raw) + if t == TYPE_FLOAT or t == TYPE_INT: + var v := float(raw) + if is_finite(v) and v > 0.0: + return clampf(v, BUDGET_MIN_SEC, BUDGET_MAX_SEC) + return BUDGET_DEFAULT_SEC + + +## Many suites assume the project's main scene is the edited scene (they read +## /Main/... nodes directly). Running with another scene open produces a flood +## of phantom failures that look like real regressions. Surface the edited +## scene and a warning when it differs from run/main_scene so the failures are +## attributable at a glance instead of costing a debugging round (#635). +func _annotate_edited_scene(results: Dictionary) -> void: + var scene_root := EditorInterface.get_edited_scene_root() + var edited := scene_root.scene_file_path if scene_root else "" + results["edited_scene"] = edited + var main_scene := str(ProjectSettings.get_setting("application/run/main_scene", "")) + if main_scene.is_empty() or edited == main_scene: + return + if int(results.get("failed", 0)) <= 0: + return + results["scene_warning"] = ( + "Edited scene is '%s' but the project main scene is '%s'. Many suites " + % [edited if not edited.is_empty() else "", main_scene] + + "assume the main scene is open and will report phantom failures " + + "otherwise. If these failures are unexpected, scene_open('%s') and re-run." % main_scene + ) + + +func get_test_results(params: Dictionary) -> Dictionary: + var verbose: bool = params.get("verbose", false) + return {"data": _runner.get_results(verbose)} + + +## Returns {"suites": Array, "errors": Array[String], "outcome": String}. +## Resilient: a broken script doesn't kill discovery of the rest. A +## non-empty outcome ("timeout" / "transport_lost" / "paused") means a +## between-load checkpoint aborted discovery — script loading is itself an +## atomic phase, and a directory of heavy scripts must neither starve the +## heartbeat nor escape the run budget. +func _discover_suites( + service_cb: Callable = Callable(), + deadline_ticks_ms: int = 0, + run_state: Dictionary = {}, +) -> Dictionary: + var suites := [] + var errors: Array[String] = [] + var dir := DirAccess.open("res://tests") + if dir == null: + return { + "suites": suites, + "errors": ["DirAccess.open('res://tests') returned null — directory may not exist"], + "outcome": "", + } + + dir.list_dir_begin() + var file_name := dir.get_next() + while not file_name.is_empty(): + if file_name.begins_with("test_") and file_name.ends_with(".gd"): + var stop := _discovery_checkpoint(service_cb, deadline_ticks_ms, run_state) + if not stop.is_empty(): + return {"suites": suites, "errors": errors, "outcome": stop} + var path := "res://tests/" + file_name + var script = ResourceLoader.load(path, "", ResourceLoader.CACHE_MODE_IGNORE) + if script == null: + errors.append("%s (load failed — check for parse errors or duplicate methods)" % file_name) + elif script.can_instantiate(): + var instance = script.new() + if instance is McpTestSuite: + suites.append(instance) + else: + errors.append("%s (not a McpTestSuite subclass)" % file_name) + else: + errors.append("%s (cannot instantiate — abstract or broken)" % file_name) + file_name = dir.get_next() + + ## Sort by suite name for deterministic order. + suites.sort_custom(func(a, b) -> bool: + return a.suite_name() < b.suite_name() + ) + return {"suites": suites, "errors": errors, "outcome": ""} + + +## Discovery-phase twin of McpTestRunner._checkpoint. Both delegate to the +## shared McpConnection.exclusive_run_checkpoint so the outcome mapping +## cannot drift between the discovery and between-test paths. +func _discovery_checkpoint( + service_cb: Callable, deadline_ticks_ms: int, run_state: Dictionary +) -> String: + return McpConnection.exclusive_run_checkpoint(service_cb, deadline_ticks_ms, run_state) diff --git a/addons/godot_ai/handlers/test_handler.gd.uid b/addons/godot_ai/handlers/test_handler.gd.uid new file mode 100644 index 0000000..e56fce1 --- /dev/null +++ b/addons/godot_ai/handlers/test_handler.gd.uid @@ -0,0 +1 @@ +uid://bfg3c6iinhwmx diff --git a/addons/godot_ai/handlers/texture_handler.gd b/addons/godot_ai/handlers/texture_handler.gd new file mode 100644 index 0000000..4e90d18 --- /dev/null +++ b/addons/godot_ai/handlers/texture_handler.gd @@ -0,0 +1,199 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Creates procedural textures — GradientTexture2D (wrapping a Gradient) +## and NoiseTexture2D (wrapping a FastNoiseLite). Assigns to a node slot +## (undoable, bundles sub-resources) or saves to a .tres file. + +const NodeHandler := preload("res://addons/godot_ai/handlers/node_handler.gd") + +var _undo_redo: EditorUndoRedoManager +var _connection: McpConnection + + +func _init(undo_redo: EditorUndoRedoManager, connection: McpConnection = null) -> void: + _undo_redo = undo_redo + _connection = connection + + +const _FILL_MODES := { + "linear": GradientTexture2D.FILL_LINEAR, + "radial": GradientTexture2D.FILL_RADIAL, + "square": GradientTexture2D.FILL_SQUARE, +} + +const _NOISE_TYPES := { + "simplex": FastNoiseLite.TYPE_SIMPLEX, + "simplex_smooth": FastNoiseLite.TYPE_SIMPLEX_SMOOTH, + "perlin": FastNoiseLite.TYPE_PERLIN, + "cellular": FastNoiseLite.TYPE_CELLULAR, + "value": FastNoiseLite.TYPE_VALUE, + "value_cubic": FastNoiseLite.TYPE_VALUE_CUBIC, +} + + +# ============================================================================ +# gradient_texture_create +# ============================================================================ + +func create_gradient_texture(params: Dictionary) -> Dictionary: + var stops: Array = params.get("stops", []) + var width: int = params.get("width", 256) + var height: int = params.get("height", 1) + var fill: String = params.get("fill", "linear") + + if stops.size() < 2: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "gradient_texture_create requires at least 2 stops, got %d" % stops.size() + ) + if not _FILL_MODES.has(fill): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid fill '%s'. Valid: %s" % [fill, ", ".join(_FILL_MODES.keys())] + ) + + var home_err := McpResourceIO.validate_home(params) + if home_err != null: + return home_err + + var gradient := Gradient.new() + var offsets := PackedFloat32Array() + var colors := PackedColorArray() + for i in range(stops.size()): + var stop = stops[i] + if not stop is Dictionary: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "stops[%d] must be a dict with 'offset' and 'color' keys" % i + ) + if not stop.has("offset") or not stop.has("color"): + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "stops[%d] missing 'offset' or 'color' key" % i + ) + offsets.append(float(stop["offset"])) + var color_value = NodeHandler._coerce_value(stop["color"], TYPE_COLOR) + var color_err := NodeHandler._check_coerced(color_value, TYPE_COLOR, "stops[%d].color" % i) + if color_err != null: + return color_err + colors.append(color_value) + gradient.offsets = offsets + gradient.colors = colors + + var tex := GradientTexture2D.new() + tex.gradient = gradient + tex.width = width + tex.height = height + tex.fill = _FILL_MODES[fill] + + return _finalize(tex, [gradient], params, "Gradient texture", { + "texture_class": "GradientTexture2D", + "gradient_class": "Gradient", + "stop_count": stops.size(), + "fill": fill, + }) + + +# ============================================================================ +# noise_texture_create +# ============================================================================ + +func create_noise_texture(params: Dictionary) -> Dictionary: + var noise_type: String = params.get("noise_type", "simplex_smooth") + var width: int = params.get("width", 512) + var height: int = params.get("height", 512) + var frequency: float = params.get("frequency", 0.01) + var seed_value: int = params.get("seed", 0) + var fractal_octaves: int = params.get("fractal_octaves", 0) # 0 = leave default + + if not _NOISE_TYPES.has(noise_type): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid noise_type '%s'. Valid: %s" % [noise_type, ", ".join(_NOISE_TYPES.keys())] + ) + + var home_err := McpResourceIO.validate_home(params) + if home_err != null: + return home_err + + var noise := FastNoiseLite.new() + noise.noise_type = _NOISE_TYPES[noise_type] + noise.frequency = frequency + noise.seed = seed_value + if fractal_octaves > 0: + noise.fractal_octaves = fractal_octaves + + var tex := NoiseTexture2D.new() + tex.noise = noise + tex.width = width + tex.height = height + + return _finalize(tex, [noise], params, "Noise texture", { + "texture_class": "NoiseTexture2D", + "noise_class": "FastNoiseLite", + "noise_type": noise_type, + }) + + +# ============================================================================ +# shared helpers +# ============================================================================ + +func _finalize(tex: Resource, sub_resources: Array, params: Dictionary, label: String, extra: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + var property: String = params.get("property", "") + var resource_path: String = params.get("resource_path", "") + var overwrite: bool = params.get("overwrite", false) + + if not resource_path.is_empty(): + return McpResourceIO.save_to_disk(tex, resource_path, overwrite, label, extra, _connection) + return _assign_texture(tex, sub_resources, node_path, property, label, extra) + + +func _assign_texture(tex: Resource, sub_resources: Array, node_path: String, property: String, label: String, extra: Dictionary) -> Dictionary: + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + + var found := false + var prop_type: int = TYPE_NIL + for prop in node.get_property_list(): + if prop.name == property: + found = true + prop_type = prop.get("type", TYPE_NIL) + break + if not found: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + McpPropertyErrors.build_message(node, property) + ) + if prop_type != TYPE_NIL and prop_type != TYPE_OBJECT: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Property '%s' on %s is not an Object slot" % [property, node.get_class()] + ) + + var old_value = node.get(property) + + _undo_redo.create_action("MCP: Create %s for %s.%s" % [label, node.name, property]) + _undo_redo.add_do_property(node, property, tex) + _undo_redo.add_undo_property(node, property, old_value) + _undo_redo.add_do_reference(tex) + for sub in sub_resources: + _undo_redo.add_do_reference(sub) + _undo_redo.commit_action() + + var data := { + "path": node_path, + "property": property, + "undoable": true, + } + data.merge(extra) + return {"data": data} + + diff --git a/addons/godot_ai/handlers/texture_handler.gd.uid b/addons/godot_ai/handlers/texture_handler.gd.uid new file mode 100644 index 0000000..a0a0f73 --- /dev/null +++ b/addons/godot_ai/handlers/texture_handler.gd.uid @@ -0,0 +1 @@ +uid://cmloikhre8lhe diff --git a/addons/godot_ai/handlers/theme_handler.gd b/addons/godot_ai/handlers/theme_handler.gd new file mode 100644 index 0000000..a71c745 --- /dev/null +++ b/addons/godot_ai/handlers/theme_handler.gd @@ -0,0 +1,476 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles Theme resource authoring: creating, modifying color/constant/font-size/ +## stylebox slots, and applying a theme to a Control subtree. +## +## Themes are Godot's equivalent of USS: a Theme holds (class, name) -> value +## entries (colors, constants, fonts, font_sizes, styleboxes, icons) which +## cascade down a Control subtree when the theme is assigned at any ancestor. +## One well-authored theme replaces hundreds of per-node property sets. + +const _COLOR_HINT := "expected hex #rrggbb, named color, or {r,g,b,a} dict" + +var _undo_redo: EditorUndoRedoManager +var _connection: McpConnection + + +func _init(undo_redo: EditorUndoRedoManager, connection: McpConnection = null) -> void: + _undo_redo = undo_redo + _connection = connection + + +# ============================================================================ +# theme_create +# ============================================================================ + +func create_theme(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var overwrite: bool = params.get("overwrite", false) + + var err := _validate_res_path(path, ".tres", "path", true) + if err != null: + return err + + # Capture whether the file was already there BEFORE the save so we can + # report `overwritten` accurately (after save the file always exists). + var existed_before := FileAccess.file_exists(path) + if existed_before and not overwrite: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Theme already exists at %s (pass overwrite=true to replace)" % path + ) + + # Ensure parent directory exists. make_dir_recursive is idempotent — + # no need to check dir_exists first (avoids TOCTOU race). + var dir_path := path.get_base_dir() + var mkdir_err := DirAccess.make_dir_recursive_absolute(dir_path) + if mkdir_err != OK and mkdir_err != ERR_ALREADY_EXISTS: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to create directory: %s (error %d)" % [dir_path, mkdir_err] + ) + + var theme := Theme.new() + var save_err := McpResourceIO.guarded_save(theme, path, _connection) + if save_err != OK: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to save theme to %s: %s (error %d)" % [path, error_string(save_err), save_err] + ) + + # Make sure the editor's filesystem picks up the new file. + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(path) + + return { + "data": { + "path": path, + "overwritten": existed_before, + "undoable": false, + "reason": "File creation is persistent; delete the file manually to revert", + } + } + + +# ============================================================================ +# theme_set_color / theme_set_constant / theme_set_font_size +# ============================================================================ + +func set_color(params: Dictionary) -> Dictionary: + return _set_scalar(params, "color", func(theme, name, cls): return theme.get_color(name, cls), + func(theme, name, cls, val): theme.set_color(name, cls, val), + func(theme, name, cls): theme.clear_color(name, cls), + func(theme, name, cls): return theme.has_color(name, cls), + func(v): return _parse_color(v)) + + +# constant / font_size parsers validate before coercing: int("abc")/int({})/int([]) +# all return 0 in GDScript (never null), so a bare `int(v)` would silently store +# garbage as 0 and report success. Returning null for non-numeric input lets +# _set_scalar's null guard surface a VALUE_OUT_OF_RANGE error, matching the +# color path's contract. +func set_constant(params: Dictionary) -> Dictionary: + return _set_scalar(params, "constant", func(theme, name, cls): return theme.get_constant(name, cls), + func(theme, name, cls, val): theme.set_constant(name, cls, int(val)), + func(theme, name, cls): theme.clear_constant(name, cls), + func(theme, name, cls): return theme.has_constant(name, cls), + func(v): return int(v) if (v is int or v is float or (v is String and v.is_valid_int())) else null) + + +func set_font_size(params: Dictionary) -> Dictionary: + return _set_scalar(params, "font_size", func(theme, name, cls): return theme.get_font_size(name, cls), + func(theme, name, cls, val): theme.set_font_size(name, cls, int(val)), + func(theme, name, cls): theme.clear_font_size(name, cls), + func(theme, name, cls): return theme.has_font_size(name, cls), + func(v): return int(v) if (v is int or v is float or (v is String and v.is_valid_int())) else null) + + +# Shared implementation for scalar Theme slots (color, constant, font_size). +# Captures old value, applies new value, saves to disk, registers undo that +# restores the old value and saves again. +func _set_scalar( + params: Dictionary, + kind: String, + getter: Callable, + setter: Callable, + clearer: Callable, + has_fn: Callable, + parser: Callable, +) -> Dictionary: + var load_result := _load_theme_from_params(params) + if load_result.has("error"): + return load_result + var theme: Theme = load_result.theme + var theme_path: String = load_result.path + + var class_name_param: String = params.get("class_name", "") + if class_name_param.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: class_name") + + var name: String = params.get("name", "") + if name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: name") + + if not "value" in params: + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: value") + + var raw_value = params.get("value") + if raw_value == null: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid %s value: null (pass a concrete value; use the appropriate clear command to remove a slot)" % kind + ) + var parsed = parser.call(raw_value) + if parsed == null: + ## color slots want a color hint; constant/font_size are integer slots. + var hint := _COLOR_HINT if kind == "color" else "expected an integer" + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, + "Invalid %s value: %s (%s)" % [kind, raw_value, hint]) + + var had_before: bool = has_fn.call(theme, name, class_name_param) + var before_value = getter.call(theme, name, class_name_param) if had_before else null + + _undo_redo.create_action("MCP: Theme set %s %s/%s" % [kind, class_name_param, name]) + _undo_redo.add_do_method(self, "_apply_scalar", theme_path, setter, name, class_name_param, parsed) + if had_before: + _undo_redo.add_undo_method(self, "_apply_scalar", theme_path, setter, name, class_name_param, before_value) + else: + _undo_redo.add_undo_method(self, "_clear_scalar", theme_path, clearer, name, class_name_param) + _undo_redo.commit_action() + + return { + "data": { + "path": theme_path, + "kind": kind, + "class_name": class_name_param, + "name": name, + "value": _serialize_value(parsed), + "previous_value": _serialize_value(before_value) if had_before else null, + "undoable": true, + } + } + + +func _apply_scalar(theme_path: String, setter: Callable, name: String, class_name_param: String, value: Variant) -> void: + var theme: Theme = ResourceLoader.load(theme_path) + if theme == null: + push_warning("MCP: Failed to load theme for undo/redo: %s" % theme_path) + return + setter.call(theme, name, class_name_param, value) + McpResourceIO.guarded_save(theme, theme_path, _connection) + + +func _clear_scalar(theme_path: String, clearer: Callable, name: String, class_name_param: String) -> void: + var theme: Theme = ResourceLoader.load(theme_path) + if theme == null: + push_warning("MCP: Failed to load theme for undo/redo: %s" % theme_path) + return + clearer.call(theme, name, class_name_param) + McpResourceIO.guarded_save(theme, theme_path, _connection) + + +# ============================================================================ +# theme_set_stylebox_flat +# ============================================================================ + +## Compose a StyleBoxFlat and assign it to a theme slot. +## +## Parameters (beyond theme_path / class_name / name): +## bg_color (Color, "#rrggbb", "#rrggbbaa", or {r,g,b,a}) +## border_color (Color) +## border {all|top|bottom|left|right: int} — side keys override `all` +## corners {all|top_left|top_right|bottom_left|bottom_right: int} +## margins {all|top|bottom|left|right: float} +## shadow {color, size: int, offset_x: float, offset_y: float} +## anti_aliasing (bool) +## +## Unknown keys inside any nested dict are rejected with INVALID_PARAMS so +## typos fail loudly instead of silently being ignored. +func set_stylebox_flat(params: Dictionary) -> Dictionary: + var load_result := _load_theme_from_params(params) + if load_result.has("error"): + return load_result + var theme: Theme = load_result.theme + var theme_path: String = load_result.path + + var class_name_param: String = params.get("class_name", "") + if class_name_param.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: class_name") + + var name: String = params.get("name", "") + if name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: name") + + var sb := StyleBoxFlat.new() + if params.has("bg_color"): + var bg := _parse_color(params.bg_color) + if bg == null: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Invalid bg_color: %s (%s)" % [str(params.bg_color), _COLOR_HINT]) + sb.bg_color = bg + if params.has("border_color"): + var bc := _parse_color(params.border_color) + if bc == null: + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Invalid border_color: %s (%s)" % [str(params.border_color), _COLOR_HINT]) + sb.border_color = bc + + # border: {all, top, bottom, left, right} — int widths + if params.has("border"): + var err := _apply_sides(sb, params.border, "border", + ["top", "bottom", "left", "right"], + "border_width_", + TYPE_INT) + if err != "": + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, err) + + # corners: {all, top_left, top_right, bottom_left, bottom_right} — int radii + if params.has("corners"): + var err2 := _apply_sides(sb, params.corners, "corners", + ["top_left", "top_right", "bottom_left", "bottom_right"], + "corner_radius_", + TYPE_INT) + if err2 != "": + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, err2) + + # margins: {all, top, bottom, left, right} — float padding + if params.has("margins"): + var err3 := _apply_sides(sb, params.margins, "margins", + ["top", "bottom", "left", "right"], + "content_margin_", + TYPE_FLOAT) + if err3 != "": + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, err3) + + # shadow: {color, size, offset_x, offset_y} + if params.has("shadow"): + if typeof(params.shadow) != TYPE_DICTIONARY: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "'shadow' must be a dict with color/size/offset_x/offset_y") + var shadow: Dictionary = params.shadow + var allowed_shadow_keys := {"color": true, "size": true, "offset_x": true, "offset_y": true} + for k in shadow.keys(): + if not allowed_shadow_keys.has(k): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Unknown key in 'shadow': %s (valid: color, size, offset_x, offset_y)" % k) + if shadow.has("color"): + var sc := _parse_color(shadow.color) + if sc == null: + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, + "Invalid shadow.color: %s (%s)" % [str(shadow.color), _COLOR_HINT]) + sb.shadow_color = sc + if shadow.has("size"): + sb.shadow_size = int(shadow.size) + if shadow.has("offset_x") or shadow.has("offset_y"): + sb.shadow_offset = Vector2( + float(shadow.get("offset_x", 0)), + float(shadow.get("offset_y", 0)), + ) + + if params.has("anti_aliasing"): + sb.anti_aliasing = bool(params.anti_aliasing) + + var had_before := theme.has_stylebox(name, class_name_param) + var before_sb: StyleBox = theme.get_stylebox(name, class_name_param) if had_before else null + + _undo_redo.create_action("MCP: Theme set stylebox %s/%s" % [class_name_param, name]) + _undo_redo.add_do_method(self, "_apply_stylebox", theme_path, name, class_name_param, sb) + if had_before: + _undo_redo.add_undo_method(self, "_apply_stylebox", theme_path, name, class_name_param, before_sb) + else: + _undo_redo.add_undo_method(self, "_clear_stylebox", theme_path, name, class_name_param) + _undo_redo.commit_action() + + return { + "data": { + "path": theme_path, + "class_name": class_name_param, + "name": name, + "stylebox_class": "StyleBoxFlat", + "bg_color": _serialize_value(sb.bg_color), + "border": { + "top": sb.border_width_top, + "bottom": sb.border_width_bottom, + "left": sb.border_width_left, + "right": sb.border_width_right, + }, + "corners": { + "top_left": sb.corner_radius_top_left, + "top_right": sb.corner_radius_top_right, + "bottom_left": sb.corner_radius_bottom_left, + "bottom_right": sb.corner_radius_bottom_right, + }, + "margins": { + "top": sb.content_margin_top, + "bottom": sb.content_margin_bottom, + "left": sb.content_margin_left, + "right": sb.content_margin_right, + }, + "undoable": true, + } + } + + +## Parse a {all, , , ...} dict and apply it to StyleBoxFlat via +## its set_ properties. Returns "" on success, an error +## message on failure. Validates that only known keys are present. +func _apply_sides(sb: StyleBoxFlat, sides_dict: Variant, dict_name: String, + side_names: Array, prop_prefix: String, value_type: int) -> String: + if typeof(sides_dict) != TYPE_DICTIONARY: + return "'%s' must be a dict with 'all' and/or side-specific keys" % dict_name + var valid_keys := {"all": true} + for s in side_names: + valid_keys[s] = true + for k in sides_dict.keys(): + if not valid_keys.has(k): + return "Unknown key in '%s': %s (valid: all, %s)" % [ + dict_name, k, ", ".join(side_names) + ] + # Apply `all` first, then override with side-specific keys. + if sides_dict.has("all"): + var all_val: Variant = sides_dict.all + for s in side_names: + var v: Variant = int(all_val) if value_type == TYPE_INT else float(all_val) + sb.set(prop_prefix + s, v) + for s in side_names: + if sides_dict.has(s): + var v2: Variant = int(sides_dict[s]) if value_type == TYPE_INT else float(sides_dict[s]) + sb.set(prop_prefix + s, v2) + return "" + + +func _apply_stylebox(theme_path: String, name: String, class_name_param: String, sb: StyleBox) -> void: + var theme: Theme = ResourceLoader.load(theme_path) + if theme == null: + push_warning("MCP: Failed to load theme for undo/redo: %s" % theme_path) + return + theme.set_stylebox(name, class_name_param, sb) + McpResourceIO.guarded_save(theme, theme_path, _connection) + + +func _clear_stylebox(theme_path: String, name: String, class_name_param: String) -> void: + var theme: Theme = ResourceLoader.load(theme_path) + if theme == null: + push_warning("MCP: Failed to load theme for undo/redo: %s" % theme_path) + return + theme.clear_stylebox(name, class_name_param) + McpResourceIO.guarded_save(theme, theme_path, _connection) + + +# ============================================================================ +# theme_apply — assign a theme to a Control +# ============================================================================ + +func apply_theme(params: Dictionary) -> Dictionary: + var node_path: String = params.get("node_path", "") + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: node_path") + + var theme_path: String = params.get("theme_path", "") + var theme: Theme = null + if not theme_path.is_empty(): + var path_err := _validate_res_path(theme_path, ".tres") + if path_err != null: + return path_err + if not ResourceLoader.exists(theme_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Theme not found: %s" % theme_path) + theme = ResourceLoader.load(theme_path) + if theme == null or not theme is Theme: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Theme" % theme_path) + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var _scene_root: Node = _resolved.scene_root + if not node is Control and not node is Window: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node %s is not a Control or Window (got %s)" % [node_path, node.get_class()] + ) + + var before_theme: Theme = node.theme + _undo_redo.create_action("MCP: Apply theme to %s" % node.name) + _undo_redo.add_do_property(node, "theme", theme) + _undo_redo.add_undo_property(node, "theme", before_theme) + _undo_redo.commit_action() + + return { + "data": { + "node_path": node_path, + "theme_path": theme_path if theme != null else "", + "cleared": theme == null, + "undoable": true, + } + } + + +# ============================================================================ +# Helpers +# ============================================================================ + +func _load_theme_from_params(params: Dictionary) -> Dictionary: + var theme_path: String = params.get("theme_path", "") + var err := _validate_res_path(theme_path, ".tres", "theme_path", true) + if err != null: + return err + if not ResourceLoader.exists(theme_path): + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Theme not found: %s" % theme_path) + var theme: Theme = ResourceLoader.load(theme_path) + if theme == null or not theme is Theme: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "Resource at %s is not a Theme" % theme_path) + return {"theme": theme, "path": theme_path} + + +static func _validate_res_path(path: String, required_suffix: String, param_name: String = "theme_path", for_write: bool = false) -> Variant: + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: %s" % param_name) + var path_err := McpPathValidator.validate_resource_path(path, for_write) + if not path_err.is_empty(): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "%s: %s" % [param_name, path_err]) + if not path.ends_with(required_suffix): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "%s must end with %s (got %s)" % [param_name, required_suffix, path] + ) + return null + + +## Parse a color from Color, "#rrggbb", "#rrggbbaa", named (red/blue/...) or dict. +## Returns null if the input cannot be parsed. +## Delegates to the canonical parser (#714) — gains [r,g,b(,a)] array +## support and strict key/component checking, same shapes as every other +## color-accepting handler. +static func _parse_color(value: Variant) -> Variant: + return McpJsonValues.parse_color(value) + + +static func _serialize_value(value: Variant) -> Variant: + if value == null: + return null + if value is Color: + return {"r": value.r, "g": value.g, "b": value.b, "a": value.a} + if value is Vector2: + return {"x": value.x, "y": value.y} + return value diff --git a/addons/godot_ai/handlers/theme_handler.gd.uid b/addons/godot_ai/handlers/theme_handler.gd.uid new file mode 100644 index 0000000..b77af13 --- /dev/null +++ b/addons/godot_ai/handlers/theme_handler.gd.uid @@ -0,0 +1 @@ +uid://gjyldaddj7mu diff --git a/addons/godot_ai/handlers/tilemap_handler.gd b/addons/godot_ai/handlers/tilemap_handler.gd new file mode 100644 index 0000000..ac68e34 --- /dev/null +++ b/addons/godot_ai/handlers/tilemap_handler.gd @@ -0,0 +1,163 @@ +@tool +extends RefCounted + +## TileMap / TileMapLayer authoring — set, fill, clear, and read tile cells +## directly in the editor scene with full undo/redo support. +## +## All ops target TileMapLayer nodes in the currently edited scene by +## scene-relative path (e.g. "/LavaLake20x20/Ground"). + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +const MAX_RECT_FILL_CELLS := 4096 + +var _undo_redo: EditorUndoRedoManager + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +## Set a single tile cell. +## params: {path, source_id, atlas_col, atlas_row, map_x, map_y} +## Returns: {map_x, map_y, source_id, atlas_col, atlas_row} +func set_cell(params: Dictionary) -> Dictionary: + var layer := _resolve_layer(params) + if layer.has("error"): return layer + var node: TileMapLayer = layer.node + var pos := Vector2i(params.get("map_x", 0), params.get("map_y", 0)) + var src := int(params.get("source_id", 0)) + var atlas := Vector2i(params.get("atlas_col", 0), params.get("atlas_row", 0)) + var prev := _capture_cell_state(node, pos) + _undo_redo.create_action("MCP: TileMap set_cell") + _undo_redo.add_do_method(node, "set_cell", pos, src, atlas) + _undo_redo.add_undo_method(self, "_restore_cell_state", node, pos, prev) + _undo_redo.commit_action() + return {"data": {"map_x": pos.x, "map_y": pos.y, "source_id": src, + "atlas_col": atlas.x, "atlas_row": atlas.y, "undoable": true}} + + +## Fill a rectangular region with one tile type in a single undo action. +## params: {path, source_id, atlas_col, atlas_row, rect_x, rect_y, rect_w, rect_h} +## Returns: {cells_filled, rect: {x, y, w, h}} +func set_cells_rect(params: Dictionary) -> Dictionary: + var layer := _resolve_layer(params) + if layer.has("error"): return layer + var node: TileMapLayer = layer.node + var src := int(params.get("source_id", 0)) + var atlas := Vector2i(params.get("atlas_col", 0), params.get("atlas_row", 0)) + var rx := int(params.get("rect_x", 0)); var ry := int(params.get("rect_y", 0)) + var rw := int(params.get("rect_w", 1)); var rh := int(params.get("rect_h", 1)) + if rw <= 0 or rh <= 0: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "rect_w and rect_h must be > 0 (got %d x %d)" % [rw, rh] + ) + var cell_count := rw * rh + if cell_count > MAX_RECT_FILL_CELLS: + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Rect too large: %d cells exceeds max %d" % [cell_count, MAX_RECT_FILL_CELLS] + ) + var cells: Array[Vector2i] = [] + var snapshot: Array[Dictionary] = [] + for x in range(rx, rx + rw): + for y in range(ry, ry + rh): + var pos := Vector2i(x, y) + cells.append(pos) + snapshot.append({"pos": pos, "state": _capture_cell_state(node, pos)}) + _undo_redo.create_action("MCP: TileMap set_cells_rect %dx%d" % [rw, rh]) + for pos in cells: + _undo_redo.add_do_method(node, "set_cell", pos, src, atlas) + _undo_redo.add_undo_method(self, "_restore_rect_snapshot", node, snapshot) + _undo_redo.commit_action() + return {"data": {"cells_filled": cells.size(), + "rect": {"x": rx, "y": ry, "w": rw, "h": rh}, "undoable": true}} + + +## Remove all tiles from a TileMapLayer. +## params: {path} +## Returns: {cleared: true} +func clear_layer(params: Dictionary) -> Dictionary: + var layer := _resolve_layer(params) + if layer.has("error"): return layer + var node: TileMapLayer = layer.node + var snapshot := _capture_used_cells_snapshot(node) + _undo_redo.create_action("MCP: TileMap clear") + _undo_redo.add_do_method(node, "clear") + _undo_redo.add_undo_method(self, "_restore_cells_snapshot", node, snapshot) + _undo_redo.commit_action() + return {"data": {"cleared": true, "undoable": true}} + + +## Return all used cell coordinates. +## params: {path} +## Returns: {cells: [{x, y}, ...], count: int} +func get_used_cells(params: Dictionary) -> Dictionary: + var layer := _resolve_layer(params) + if layer.has("error"): return layer + var node: TileMapLayer = layer.node + var cells := node.get_used_cells() + var result: Array = [] + for c in cells: + result.append({"x": c.x, "y": c.y}) + return {"data": {"cells": result, "count": result.size()}} + + +## Resolve a TileMapLayer node from params["path"] in the currently edited +## scene. Returns {"node": TileMapLayer} on success, or an error dict. +func _resolve_layer(params: Dictionary) -> Dictionary: + var path: String = params.get("path", "") + var scene_file: String = params.get("scene_file", "") + var resolved := McpNodeValidator.resolve_or_error(path, "path", scene_file) + if resolved.has("error"): + return resolved + var node: Node = resolved.node + if not node is TileMapLayer: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, + "Node is not a TileMapLayer: %s" % path) + return {"node": node} + + +func _capture_cell_state(node: TileMapLayer, pos: Vector2i) -> Dictionary: + var source_id := node.get_cell_source_id(pos) + if source_id == -1: + return {"has_tile": false} + var atlas: Vector2i = node.get_cell_atlas_coords(pos) + var alternative := node.get_cell_alternative_tile(pos) + return { + "has_tile": true, + "source_id": source_id, + "atlas_col": atlas.x, + "atlas_row": atlas.y, + "alternative": alternative, + } + + +func _capture_used_cells_snapshot(node: TileMapLayer) -> Array[Dictionary]: + var snapshot: Array[Dictionary] = [] + for pos in node.get_used_cells(): + snapshot.append({"pos": pos, "state": _capture_cell_state(node, pos)}) + return snapshot + + +func _restore_cells_snapshot(node: TileMapLayer, snapshot: Array[Dictionary]) -> void: + node.clear() + for entry in snapshot: + _restore_cell_state(node, entry.pos, entry.state) + + +func _restore_rect_snapshot(node: TileMapLayer, snapshot: Array[Dictionary]) -> void: + for entry in snapshot: + _restore_cell_state(node, entry.pos, entry.state) + + +func _restore_cell_state(node: TileMapLayer, pos: Vector2i, state: Dictionary) -> void: + if not state.get("has_tile", false): + node.erase_cell(pos) + return + node.set_cell( + pos, + int(state.get("source_id", -1)), + Vector2i(int(state.get("atlas_col", -1)), int(state.get("atlas_row", -1))), + int(state.get("alternative", 0)) + ) diff --git a/addons/godot_ai/handlers/tilemap_handler.gd.uid b/addons/godot_ai/handlers/tilemap_handler.gd.uid new file mode 100644 index 0000000..8cbed53 --- /dev/null +++ b/addons/godot_ai/handlers/tilemap_handler.gd.uid @@ -0,0 +1 @@ +uid://cm8s7a0ey2q6k diff --git a/addons/godot_ai/handlers/tileset_handler.gd b/addons/godot_ai/handlers/tileset_handler.gd new file mode 100644 index 0000000..a443b01 --- /dev/null +++ b/addons/godot_ai/handlers/tileset_handler.gd @@ -0,0 +1,178 @@ +@tool +extends RefCounted + +## TileSet management — atlas inspection helpers. + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + + +func _init() -> void: + pass + + +## Query all occupied atlas tile positions for a single source. +## +## params: +## tileset_path — res:// path to the TileSet resource (required, non-empty) +## source_id — raw TileSet source id (required) +## +## Returns: +## {"data": {"tiles": [{"col": int, "row": int}, ...], "count": int}} +## on success (including empty sources, where tiles=[] and count=0) +## ErrorCodes.make(code, message) on any validation or load failure +## +## Error codes: +## MISSING_REQUIRED_PARAM — tileset_path absent/empty, or source_id absent +## RESOURCE_NOT_FOUND — ResourceLoader.exists(tileset_path) is false +## WRONG_TYPE — loaded resource is not a TileSet, or source is +## not a TileSetAtlasSource +## VALUE_OUT_OF_RANGE — source_id not present in TileSet +## +## This method is read-only: it never calls ResourceSaver or modifies any resource. +func get_atlas_tiles(params: Dictionary) -> Dictionary: + var resolved := _resolve_atlas_source(params) + if resolved.has("error"): + return resolved + var src: TileSetAtlasSource = resolved.src + + var tiles: Array = [] + for i in range(src.get_tiles_count()): + var v: Vector2i = src.get_tile_id(i) + tiles.append({"col": v.x, "row": v.y}) + + return {"data": {"tiles": tiles, "count": tiles.size()}} + + +## Return the atlas texture of a TileSetAtlasSource as a Base64-encoded PNG. +## +## params: +## tileset_path — res:// path to the TileSet resource (required, non-empty) +## source_id — raw TileSet source id (required) +## max_size — optional int; if > 0, the image is scaled so its longest +## edge is at most max_size pixels (default 0 = full res) +## +## Returns: +## {"data": {"image_base64": String, "width": int, "height": int, +## "original_width": int, "original_height": int, "format": "png"}} +## on success +## ErrorCodes.make(code, message) on any validation or load failure +## +## Error codes: +## MISSING_REQUIRED_PARAM — tileset_path absent/empty, or source_id absent +## RESOURCE_NOT_FOUND — ResourceLoader.exists(tileset_path) is false +## WRONG_TYPE — loaded resource is not a TileSet, or source is +## not a TileSetAtlasSource, or texture is null +## VALUE_OUT_OF_RANGE — source_id not present in TileSet +## +## This method is read-only: it never calls ResourceSaver or modifies anything. +func get_atlas_image(params: Dictionary) -> Dictionary: + var resolved := _resolve_atlas_source(params) + if resolved.has("error"): + return resolved + var source_id: int = resolved.source_id + var src: TileSetAtlasSource = resolved.src + + var tex: Texture2D = src.texture + if tex == null: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Source %d has no texture assigned" % source_id + ) + + var img: Image = tex.get_image() + if img == null: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Could not retrieve image data from texture of source %d" % source_id + ) + if img.is_compressed(): + var decompress_err := img.decompress() + if decompress_err != OK: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Could not decompress texture of source %d: %s" % [source_id, error_string(decompress_err)] + ) + + var original_width: int = img.get_width() + var original_height: int = img.get_height() + + var max_size: int = params.get("max_size", 0) + if max_size > 0: + var longest_edge: int = max(original_width, original_height) + if longest_edge > max_size: + var scale: float = float(max_size) / float(longest_edge) + var new_w: int = max(1, int(original_width * scale)) + var new_h: int = max(1, int(original_height * scale)) + img.resize(new_w, new_h, Image.INTERPOLATE_LANCZOS) + + var png_bytes: PackedByteArray = img.save_png_to_buffer() + if png_bytes.is_empty(): + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "PNG encoding produced empty output for source %d" % source_id + ) + var b64: String = Marshalls.raw_to_base64(png_bytes) + + return { + "data": { + "image_base64": b64, + "width": img.get_width(), + "height": img.get_height(), + "original_width": original_width, + "original_height": original_height, + "format": "png", + } + } + + +func _resolve_atlas_source(params: Dictionary) -> Dictionary: + var tileset_path: String = params.get("tileset_path", "") + if tileset_path.is_empty(): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "'tileset_path' parameter is required and must not be empty" + ) + + if not params.has("source_id"): + return ErrorCodes.make( + ErrorCodes.MISSING_REQUIRED_PARAM, + "'source_id' parameter is required" + ) + + var tileset_path_err = McpPathValidator.loadable_error(tileset_path, "tileset_path") + if tileset_path_err != null: + return tileset_path_err + + if not ResourceLoader.exists(tileset_path): + return ErrorCodes.make( + ErrorCodes.RESOURCE_NOT_FOUND, + "TileSet resource not found: %s" % tileset_path + ) + + var ts = load(tileset_path) + if not ts is TileSet: + var loaded_type := "null" if ts == null else ts.get_class() + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Resource at '%s' is not a TileSet (got %s)" % [tileset_path, loaded_type] + ) + + var source_id: int = int(params.get("source_id", -999)) + if source_id < 0 or not ts.has_source(source_id): + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "source_id %d does not exist in TileSet" % source_id + ) + + var src = ts.get_source(source_id) + if not src is TileSetAtlasSource: + var source_type: String = "null" if src == null else src.get_class() + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Source %d is not a TileSetAtlasSource (got %s)" % [source_id, source_type] + ) + + return { + "source_id": source_id, + "src": src, + } diff --git a/addons/godot_ai/handlers/tileset_handler.gd.uid b/addons/godot_ai/handlers/tileset_handler.gd.uid new file mode 100644 index 0000000..643cfd3 --- /dev/null +++ b/addons/godot_ai/handlers/tileset_handler.gd.uid @@ -0,0 +1 @@ +uid://de3v4m1pnk7tr diff --git a/addons/godot_ai/handlers/ui_handler.gd b/addons/godot_ai/handlers/ui_handler.gd new file mode 100644 index 0000000..9795097 --- /dev/null +++ b/addons/godot_ai/handlers/ui_handler.gd @@ -0,0 +1,525 @@ +@tool +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Handles UI-specific (Control) layout helpers: anchor presets, etc. +## +## Anchors/offsets are the worst part of Control layout to set one-property-at-a-time. +## This handler wraps Godot's built-in presets (FULL_RECT, CENTER, TOP_LEFT, ...) so +## callers can set a whole layout with one command, with proper undo. + +var _undo_redo: EditorUndoRedoManager + + +const _PRESETS := { + "top_left": Control.PRESET_TOP_LEFT, + "top_right": Control.PRESET_TOP_RIGHT, + "bottom_left": Control.PRESET_BOTTOM_LEFT, + "bottom_right": Control.PRESET_BOTTOM_RIGHT, + "center_left": Control.PRESET_CENTER_LEFT, + "center_top": Control.PRESET_CENTER_TOP, + "center_right": Control.PRESET_CENTER_RIGHT, + "center_bottom": Control.PRESET_CENTER_BOTTOM, + "center": Control.PRESET_CENTER, + "left_wide": Control.PRESET_LEFT_WIDE, + "top_wide": Control.PRESET_TOP_WIDE, + "right_wide": Control.PRESET_RIGHT_WIDE, + "bottom_wide": Control.PRESET_BOTTOM_WIDE, + "vcenter_wide": Control.PRESET_VCENTER_WIDE, + "hcenter_wide": Control.PRESET_HCENTER_WIDE, + "full_rect": Control.PRESET_FULL_RECT, +} + +const _RESIZE_MODES := { + "minsize": Control.PRESET_MODE_MINSIZE, + "keep_width": Control.PRESET_MODE_KEEP_WIDTH, + "keep_height": Control.PRESET_MODE_KEEP_HEIGHT, + "keep_size": Control.PRESET_MODE_KEEP_SIZE, +} + +const _ANCHOR_OFFSET_PROPS := [ + "anchor_left", "anchor_top", "anchor_right", "anchor_bottom", + "offset_left", "offset_top", "offset_right", "offset_bottom", +] + + +func _init(undo_redo: EditorUndoRedoManager) -> void: + _undo_redo = undo_redo + + +## Apply a Control layout preset (anchors + offsets) to a UI node. +## +## Params: +## path - scene path to a Control node (required) +## preset - preset name: full_rect, center, top_left, ... (required) +## resize_mode - minsize | keep_width | keep_height | keep_size (default: minsize) +## margin - integer margin in pixels from the anchor edges (default: 0) +func set_anchor_preset(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + var preset_name: String = str(params.get("preset", "")).to_lower() + if preset_name.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: preset") + if not _PRESETS.has(preset_name): + var names := _PRESETS.keys() + names.sort() + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown preset '%s'. Valid: %s" % [preset_name, ", ".join(names)] + ) + + var resize_mode_name: String = str(params.get("resize_mode", "minsize")).to_lower() + if not _RESIZE_MODES.has(resize_mode_name): + var names := _RESIZE_MODES.keys() + names.sort() + return ErrorCodes.make( + ErrorCodes.VALUE_OUT_OF_RANGE, + "Unknown resize_mode '%s'. Valid: %s" % [resize_mode_name, ", ".join(names)] + ) + + var margin: int = int(params.get("margin", 0)) + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var scene_root: Node = _resolved.scene_root + if not node is Control: + var got_class: String = node.get_class() + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node %s is not a Control (got %s)%s" % [ + node_path, got_class, _canvas_layer_overlay_hint(got_class) + ] + ) + + var control := node as Control + var preset_value: int = _PRESETS[preset_name] + var resize_mode_value: int = _RESIZE_MODES[resize_mode_name] + + # Snapshot before so we can undo every property the preset may have touched. + var before: Dictionary = {} + for prop in _ANCHOR_OFFSET_PROPS: + before[prop] = control.get(prop) + + _undo_redo.create_action("MCP: Set %s anchor preset %s" % [control.name, preset_name]) + _undo_redo.add_do_method( + control, "set_anchors_and_offsets_preset", preset_value, resize_mode_value, margin + ) + for prop in _ANCHOR_OFFSET_PROPS: + _undo_redo.add_undo_property(control, prop, before[prop]) + _undo_redo.commit_action() + + var after: Dictionary = {} + for prop in _ANCHOR_OFFSET_PROPS: + after[prop] = control.get(prop) + + return { + "data": { + "path": node_path, + "preset": preset_name, + "resize_mode": resize_mode_name, + "margin": margin, + "anchors": { + "left": after.anchor_left, + "top": after.anchor_top, + "right": after.anchor_right, + "bottom": after.anchor_bottom, + }, + "offsets": { + "left": after.offset_left, + "top": after.offset_top, + "right": after.offset_right, + "bottom": after.offset_bottom, + }, + "undoable": true, + } + } + + +## Set the visible `text` property on a UI Control (Label, Button + subclasses, +## LineEdit, TextEdit, RichTextLabel, LinkButton). Undoable. +func set_text(params: Dictionary) -> Dictionary: + var node_path: String = params.get("path", "") + if node_path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: path") + + if not params.has("text"): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: text") + var text_value: Variant = params["text"] + if typeof(text_value) != TYPE_STRING: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "text must be a string") + + var _resolved := McpNodeValidator.resolve_or_error(node_path, "node_path") + if _resolved.has("error"): + return _resolved + var node: Node = _resolved.node + var scene_root: Node = _resolved.scene_root + var node_type := node.get_class() + if not node is Control: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Node %s is not a Control (got %s)" % [node_path, node_type] + ) + # Scan get_property_list() (matches set_property / _apply_property in this + # repo) so we can both confirm `text` exists and that it's actually a String + # — guards against a custom Control whose `text` happens to be some other + # type, where set()-ing a String would silently mis-coerce. + var text_prop_type := TYPE_NIL + var has_text := false + for prop in node.get_property_list(): + if prop.get("name", "") == "text": + has_text = true + text_prop_type = prop.get("type", TYPE_NIL) + break + if not has_text: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Control %s has no 'text' property (got %s)" % [node_path, node_type] + ) + if text_prop_type != TYPE_STRING: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + "Control %s has a non-string 'text' property (got %s)" % [node_path, node_type] + ) + + var old_value: String = node.get("text") + + _undo_redo.create_action("MCP: Set %s text" % node.name) + _undo_redo.add_do_property(node, "text", text_value) + _undo_redo.add_undo_property(node, "text", old_value) + _undo_redo.commit_action() + + return { + "data": { + "path": node_path, + "text": text_value, + "old_text": old_value, + "node_type": node_type, + "undoable": true, + } + } + + +# ============================================================================ +# build_layout — declarative nested-dict → Control tree in one undo action +# ============================================================================ + +## Build a tree of Control nodes atomically. +## +## Params: +## tree - Dictionary describing the root node. Required fields: "type". +## Optional: "name", "properties" (dict), "anchor_preset", +## "anchor_margin", "theme" (res://, uid:// or user:// path), "children" (array). +## parent_path - Parent scene path. Empty or "/" = scene root. +## +## Validation is done before any scene mutation: class names, property +## existence, and res:// paths are all checked up-front. If anything is +## invalid, no node is created. +func build_layout(params: Dictionary) -> Dictionary: + var tree = params.get("tree") + if not params.has("tree"): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: tree") + if typeof(tree) != TYPE_DICTIONARY: + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "tree must be a dictionary") + + var _scene_check := McpNodeValidator.require_scene_or_error() + if _scene_check.has("error"): + return _scene_check + var scene_root: Node = _scene_check.scene_root + + var parent_path: String = params.get("parent_path", "") + var parent: Node = scene_root + if not parent_path.is_empty() and parent_path != "/": + parent = McpScenePath.resolve(parent_path, scene_root) + if parent == null: + return ErrorCodes.make(ErrorCodes.NODE_NOT_FOUND, McpScenePath.format_parent_error(parent_path, scene_root)) + + # Validate + build in memory first; if anything fails, free and bail. + var built := _build_subtree(tree) + if built.has("error"): + return built + var root_node: Node = built.node + var created: Array[Node] = built.created + + _undo_redo.create_action("MCP: Build UI layout (%d nodes)" % created.size()) + _undo_redo.add_do_method(parent, "add_child", root_node, true) + _undo_redo.add_do_method(root_node, "set_owner", scene_root) + for n in created: + _undo_redo.add_do_method(n, "set_owner", scene_root) + _undo_redo.add_do_reference(n) + _undo_redo.add_undo_method(parent, "remove_child", root_node) + _undo_redo.commit_action() + + return { + "data": { + "root_path": McpScenePath.from_node(root_node, scene_root), + "node_count": created.size(), + "undoable": true, + } + } + + +## Recursively instantiate + configure a node and its children in memory. +## Returns {"node": root, "created": [all descendants incl. root]} or {"error": ...}. +func _build_subtree(spec: Dictionary) -> Dictionary: + var node_type: String = spec.get("type", "") + if node_type.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Every layout node requires a 'type'") + if not ClassDB.class_exists(node_type): + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unknown type: %s" % node_type) + if not ClassDB.is_parent_class(node_type, "Node"): + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "%s is not a Node type" % node_type) + + var node: Node = ClassDB.instantiate(node_type) + if node == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to instantiate %s" % node_type) + + var node_name: String = spec.get("name", "") + if not node_name.is_empty(): + node.name = node_name + + # Properties. + if spec.has("properties"): + var props = spec.get("properties") + if typeof(props) != TYPE_DICTIONARY: + node.free() + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "properties must be a dictionary") + for key in props: + var value = props[key] + var apply_err := _apply_property(node, str(key), value) + if apply_err != null: + node.free() + return apply_err + + # Theme (res:// / uid:// / user:// path -> Resource). + if spec.has("theme"): + var theme_path: String = str(spec.get("theme", "")) + if not theme_path.is_empty(): + var theme_path_err = McpPathValidator.loadable_error(theme_path, "theme") + if theme_path_err != null: + node.free() + return theme_path_err + if not ResourceLoader.exists(theme_path): + node.free() + return ErrorCodes.make(ErrorCodes.RESOURCE_NOT_FOUND, "Theme not found: %s" % theme_path) + var theme_res: Resource = ResourceLoader.load(theme_path) + if theme_res == null or not theme_res is Theme: + node.free() + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "theme path must point to a Theme resource: %s" % theme_path) + if not node is Control and not node is Window: + node.free() + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "theme can only be set on Control / Window (got %s)%s" % [ + node_type, _canvas_layer_overlay_hint(node_type) + ] + ) + node.theme = theme_res as Theme + + # Anchor preset — applied before children so children inherit sensible anchors. + if spec.has("anchor_preset"): + var preset_name: String = str(spec.get("anchor_preset", "")).to_lower() + if not _PRESETS.has(preset_name): + node.free() + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unknown anchor_preset: %s" % preset_name) + if not node is Control: + node.free() + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "anchor_preset requires a Control (got %s)%s" % [ + node_type, _canvas_layer_overlay_hint(node_type) + ] + ) + var preset_value: int = _PRESETS[preset_name] + var margin: int = int(spec.get("anchor_margin", 0)) + (node as Control).set_anchors_and_offsets_preset(preset_value, Control.PRESET_MODE_MINSIZE, margin) + + var created: Array[Node] = [node] + if spec.has("children"): + var children = spec.get("children") + if typeof(children) != TYPE_ARRAY: + node.free() + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "children must be an array") + for child_spec in children: + if typeof(child_spec) != TYPE_DICTIONARY: + node.free() + return ErrorCodes.make(ErrorCodes.WRONG_TYPE, "each child must be a dictionary") + var child_result := _build_subtree(child_spec) + if child_result.has("error"): + node.free() + return child_result + var child_node: Node = child_result.node + node.add_child(child_node) + for n in child_result.created: + created.append(n) + return {"node": node, "created": created} + + +## Mapping from theme_override_* property prefixes to their add/remove methods. +const _THEME_OVERRIDE_MAP := { + "theme_override_colors/": { + "add": "add_theme_color_override", + "remove": "remove_theme_color_override", + "coerce_type": TYPE_COLOR, + }, + "theme_override_constants/": { + "add": "add_theme_constant_override", + "remove": "remove_theme_constant_override", + "coerce_type": TYPE_INT, + }, + "theme_override_font_sizes/": { + "add": "add_theme_font_size_override", + "remove": "remove_theme_font_size_override", + "coerce_type": TYPE_INT, + }, + "theme_override_styles/": { + "add": "add_theme_stylebox_override", + "remove": "remove_theme_stylebox_override", + "coerce_type": TYPE_OBJECT, + }, +} + + +## Apply a property to a newly-instantiated node. Handles Color/Vector2/NodePath +## coercion from JSON-friendly forms. Returns null on success, error dict on failure. +func _apply_property(node: Node, prop: String, value: Variant) -> Variant: + # Handle theme_override_* pseudo-properties before the regular property scan. + for prefix in _THEME_OVERRIDE_MAP: + if prop.begins_with(prefix): + if not node is Control: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "theme_override_* requires a Control node (got %s)" % node.get_class() + ) + var override_name := prop.substr(prefix.length()) + var info: Dictionary = _THEME_OVERRIDE_MAP[prefix] + var coerce_type: int = info.coerce_type + + # For stylebox overrides, load from a res:// / uid:// / user:// path. + if coerce_type == TYPE_OBJECT: + if value is String and (value.begins_with("res://") or value.begins_with("uid://") or value.begins_with("user://")): + var style_path_err = McpPathValidator.loadable_error(value, "stylebox") + if style_path_err != null: + return style_path_err + var res := ResourceLoader.load(value) + if res == null or not res is StyleBox: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "Style resource not found or not a StyleBox: %s" % value + ) + node.call(info.add, override_name, res) + else: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "theme_override_styles/ expects a res:// / uid:// / user:// path to a StyleBox" + ) + else: + var coercion := _coerce_for_type(value, coerce_type) + if not coercion.ok: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Cannot coerce '%s' for %s" % [value, prop] + ) + node.call(info.add, override_name, coercion.value) + return null + + var found := false + var prop_type := TYPE_NIL + for p in node.get_property_list(): + if p.name == prop: + found = true + prop_type = p.get("type", TYPE_NIL) + break + if not found: + return ErrorCodes.make( + ErrorCodes.PROPERTY_NOT_ON_CLASS, + McpPropertyErrors.build_message(node, prop) + ) + + var coercion := _coerce_for_type(value, prop_type) + if not coercion.ok: + return ErrorCodes.make( + ErrorCodes.WRONG_TYPE, + "Property '%s' on %s expects type %s (cannot coerce %s)" % [ + prop, node.get_class(), type_string(prop_type), value + ] + ) + node.set(prop, coercion.value) + return null + + +## Coerce a JSON-friendly value to the target Godot type. Returns +## {"ok": true, "value": coerced} on success, {"ok": false} on failure. +## For types we don't explicitly coerce, the value is returned as-is +## (Godot will typecheck at set() time and fail loudly if it disagrees). +static func _coerce_for_type(value: Variant, prop_type: int) -> Dictionary: + match prop_type: + TYPE_COLOR: + ## Canonical parser (#714): adds [r,g,b(,a)] array support and + ## strict key/component checking, same shapes everywhere. + var parsed_color = McpJsonValues.parse_color(value) + if parsed_color != null: + return {"ok": true, "value": parsed_color} + return {"ok": false} + TYPE_VECTOR2: + ## Same canonical parser as TYPE_COLOR (CodeRabbit review): + ## keeping the inline copy here would re-introduce exactly the + ## permissive-vs-strict drift this PR removes elsewhere. + var parsed_v2 = McpJsonValues.parse_vector2(value) + if parsed_v2 != null: + return {"ok": true, "value": parsed_v2} + return {"ok": false} + TYPE_VECTOR2I: + if value is Vector2i: + return {"ok": true, "value": value} + if value is Dictionary and value.has("x") and value.has("y"): + return {"ok": true, "value": Vector2i(int(value.x), int(value.y))} + if value is Array and value.size() == 2: + return {"ok": true, "value": Vector2i(int(value[0]), int(value[1]))} + return {"ok": false} + TYPE_RECT2: + if value is Rect2: + return {"ok": true, "value": value} + if value is Array and value.size() == 4: + return { + "ok": true, + "value": + Rect2(float(value[0]), float(value[1]), float(value[2]), float(value[3])), + } + if value is Dictionary: + if value.has("x") and value.has("y") and value.has("w") and value.has("h"): + return { + "ok": true, + "value": + Rect2(float(value.x), float(value.y), float(value.w), float(value.h)), + } + if value.has("position") and value.has("size"): + var pos := _coerce_for_type(value.position, TYPE_VECTOR2) + var sz := _coerce_for_type(value.size, TYPE_VECTOR2) + if pos.ok and sz.ok: + return {"ok": true, "value": Rect2(pos.value, sz.value)} + return {"ok": false} + TYPE_NODE_PATH: + if value is NodePath: + return {"ok": true, "value": value} + if value is String: + return {"ok": true, "value": NodePath(value)} + return {"ok": false} + return {"ok": true, "value": value} + + +# CanvasLayer is the canonical HUD parent but isn't a Control, so applying +# Control-only properties (theme, anchor_preset) to it is a common mistake. +# The recovery shape is always the same: nest a Control child under the layer. +static func _canvas_layer_overlay_hint(node_class: String) -> String: + if node_class != "CanvasLayer": + return "" + return ( + ". CanvasLayer is not a Control — add a Control (e.g. Panel or Control " + + "with anchor_preset=full_rect) as its child and apply theme / " + + "anchor_preset to that overlay." + ) diff --git a/addons/godot_ai/handlers/ui_handler.gd.uid b/addons/godot_ai/handlers/ui_handler.gd.uid new file mode 100644 index 0000000..f48f841 --- /dev/null +++ b/addons/godot_ai/handlers/ui_handler.gd.uid @@ -0,0 +1 @@ +uid://ckm6f1objpgvw diff --git a/addons/godot_ai/mcp_dock.gd b/addons/godot_ai/mcp_dock.gd new file mode 100644 index 0000000..fef75fc --- /dev/null +++ b/addons/godot_ai/mcp_dock.gd @@ -0,0 +1,3784 @@ +@tool +class_name McpDock +extends VBoxContainer + +## Editor dock panel showing MCP connection status, client config, and command log. +## +## Audit-v2 #360 partial extraction. Two cohesive subpanels live in +## res://addons/godot_ai/dock_panels/: +## - log_viewer.gd: MCP request/response log (dev-mode only). +## - port_picker_panel.gd: spawn-failure escape hatch nested in the crash panel. +## +## The audit also called for ServerStatusPanel and ClientRowController +## extractions; those were *deliberately deferred*. Their UI scatters across +## the dock layout (status icon at top, crash panel mid, setup section lower; +## client rows + drift banner + scroll grid spread similarly), so a clean +## extract-by-panel needs either visible UI reorganization or a coordinator- +## Node pattern with property-accessor façades on McpDock that re-tangle the +## very state they claim to move. +## +## A future refactor probably wants extract-by-concern instead — e.g. +## `utils/mcp_async_refresh_state_machine.gd` owning the IDLE → RUNNING → +## RUNNING_TIMED_OUT → DEFERRED_FOR_FILESYSTEM → SHUTTING_DOWN transitions +## and pending-flag triplet, `utils/mcp_client_action_dispatcher.gd` owning +## the per-row Configure/Remove worker pool. The dock would keep UI +## construction and lose the state-machine ownership. See issue #360. + +const ServerStateScript := preload("res://addons/godot_ai/utils/mcp_server_state.gd") +const ClientRefreshStateScript := preload("res://addons/godot_ai/utils/mcp_client_refresh_state.gd") +const Telemetry := preload("res://addons/godot_ai/telemetry.gd") +const UpdateManagerScript := preload("res://addons/godot_ai/utils/update_manager.gd") +const UpdateMixedStateScript := preload("res://addons/godot_ai/utils/update_mixed_state.gd") +const Client := preload("res://addons/godot_ai/clients/_base.gd") +const ClientConfigurator := preload("res://addons/godot_ai/client_configurator.gd") +const ClientRegistry := preload("res://addons/godot_ai/clients/_registry.gd") +const JsonStrategy := preload("res://addons/godot_ai/clients/_json_strategy.gd") +const TomlStrategy := preload("res://addons/godot_ai/clients/_toml_strategy.gd") +const CliStrategy := preload("res://addons/godot_ai/clients/_cli_strategy.gd") +const ToolCatalog := preload("res://addons/godot_ai/tool_catalog.gd") +const LogViewerScript := preload("res://addons/godot_ai/dock_panels/log_viewer.gd") +const PortPickerPanelScript := preload("res://addons/godot_ai/dock_panels/port_picker_panel.gd") +const VisionRoutingScript := preload("res://addons/godot_ai/vision_routing.gd") + +const DEV_MODE_SETTING := "godot_ai/dev_mode" +## "Change the port + reconfigure your clients" guide. Surfaced from the crash +## panel when a foreign process holds the HTTP port — the one piece of recovery +## (per-client config rewrite) that doesn't fit in the inline crash body. +## Resolved against the installed plugin version at click time (see +## `_port_conflict_docs_url`) so a shipped build opens the guide as it shipped, +## not tip-of-main, which may have drifted from that build's UI. +const PORT_CONFLICT_DOCS_PATH := "docs/port-conflicts.md" +const REPO_BLOB_BASE := "https://github.com/hi-godot/godot-ai/blob" +## Opened by the "How to install uv" button. See _on_install_uv for why the +## dock links here instead of running an installer itself. +const UV_INSTALL_DOCS_URL := "https://docs.astral.sh/uv/getting-started/installation/" +const CLIENT_STATUS_REFRESH_COOLDOWN_MSEC := 15 * 1000 +const CLIENT_STATUS_REFRESH_TIMEOUT_MSEC := 30 * 1000 +const CLIENT_ACTION_TIMEOUT_MSEC := 30 * 1000 +static var COLOR_MUTED := Color(0.7, 0.7, 0.7) +static var COLOR_HEADER := Color(0.95, 0.95, 0.95) +## Used for "in-progress" / "stale, action needed" UI: the startup-grace +## status icon, the spawn-failure suggested-port hint, the drift banner, +## and the per-row mismatch dot. One constant so a future palette tweak +## doesn't have to find every literal. +static var COLOR_AMBER := Color(1.0, 0.75, 0.25) + +var _connection +var _log_buffer +var _plugin: EditorPlugin + +# Always visible +var _redock_btn: Button +var _status_icon: ColorRect +var _status_label: Label +var _body_scroll: ScrollContainer +var _body: VBoxContainer +var _client_grid: VBoxContainer +var _client_configure_all_btn: Button +var _client_empty_cta_btn: Button +var _clients_summary_label: Label +var _clients_window: Window +var _dev_mode_toggle: CheckButton +var _install_label: Label + +# Tools tab (secondary window, Tab 2) — domain-exclusion UI for clients +# that cap total tool count (Antigravity: 100). Pending set is mutated by +# checkbox clicks; saved set reflects what the spawned server actually +# sees. `Apply and Restart Server` writes pending → setting and triggers a +# plugin reload so the new server comes up with the trimmed list. +var _tools_pending_excluded: PackedStringArray = PackedStringArray() +var _tools_saved_excluded: PackedStringArray = PackedStringArray() +## Custom (addon-registered) tools list — rebuilt live on registry +## tools_changed; per-tool checkboxes apply immediately (no restart). +var _custom_tools_list: VBoxContainer +var _custom_tools_count_label: Label +var _tools_domain_checkboxes: Dictionary = {} +var _tools_count_label: Label +var _tools_apply_btn: Button +var _tools_reset_btn: Button +var _tools_dirty_warning: Label +var _tools_close_confirm: ConfirmationDialog +var _telemetry_toggle: CheckButton +var _telemetry_pending_enabled: bool = true +var _telemetry_saved_enabled: bool = true + +# Settings tab (secondary window, Tab 3) — Vision Routing section plus the +# LAN opt-in (#507): "Allow remote hosts (CIDR)" behind a collapsed +# "Remote access (advanced)" disclosure (auto-expands when a non-empty +# allowlist is configured). The value feeds `--allow-host` at server spawn +# (see plugin.gd::_build_server_flags). The LineEdit's live text is the +# pending state; `_allow_hosts_saved` mirrors the persisted EditorSetting, +# same pending/saved shape as the Tools tab above. +var _allow_hosts_section: VBoxContainer +var _allow_hosts_fold: FoldableContainer +var _allow_hosts_edit: LineEdit +var _allow_hosts_hint: Label +var _allow_hosts_apply_btn: Button +var _allow_hosts_saved: String = "" + +## Per-client UI handles, keyed by client id. Each entry holds the row's +## status dot, configure/remove buttons, config-file buttons, and manual panel. +var _client_rows: Dictionary = {} + +# Drift banner — surfaced near the Clients section when one or more clients +# have a stored entry whose URL no longer matches `http_url()` (typical after +# the user changes `godot_ai/http_port`). Refreshes are stale-while-refreshing: +# cached row dots/banner remain visible while a background worker performs the +# potentially blocking config/CLI probes, then the main thread applies results. +# Automatic focus-in refreshes use a short cooldown to avoid repeated sweeps +# during tab-away/tab-back churn. See #166 and #226. +var _drift_banner: VBoxContainer +var _drift_label: Label +## Set when the user clicks "How to install uv"; consumed by the next +## application focus-in so the uv row is re-probed after the user has had a +## chance to install, not immediately. See _on_install_uv and _notification. +## (Deliberately spelled without the focus-in constant name: the guard in +## tests/unit/test_editor_focus_refocus.py locates the notification handler +## by first occurrence of that token.) +var _uv_recheck_pending := false +## Handles for the Setup section's "Server" row. `_update_status` keeps +## the label text/color in sync with `McpConnection.server_version` so the +## dock reports the TRUE running server version, not the plugin's +## expected version. See #174 follow-up — a plugin upgrade via self- +## update can leave the plugin connected to an older adopted server +## (foreign-port branch never sets `_server_pid`, so `_stop_server` +## can't kill it); the line has to show the mismatch honestly. +var _setup_server_label: Label +## Last rendered server-version string. `_update_status` runs every +## frame; early-outs text repaint when nothing changed. Empty means +## "no line rendered yet" (dev-checkout branch doesn't render a +## user-mode Server line). +var _last_rendered_server_text: String = "" +## Restart-server button shown next to the Setup container when +## `McpConnection.server_version` drifts from the plugin version. Hidden +## in the match case so the UI stays calm. +var _version_restart_btn: Button +var _server_restart_in_progress := false +## Sorted snapshot of the most recent mismatched-client set. Powers two things: +## (a) the Reconfigure button reuses this list instead of re-running +## `check_status` per row (saves ~18 filesystem reads per click), and +## (b) `_refresh_drift_banner` early-returns when the set is unchanged so +## repeated explicit refreshes don't repaint identical text. Mirrors the +## `_last_server_status` pattern used by the crash panel. +var _last_mismatched_ids: Array[String] = [] +## One-shot post-self-update auto-repin (armed by plugin.gd via +## `notify_self_update_success`). After an update, every client configured +## through this plugin still pins the OLD server version — the drift banner +## names them, but until they're rewritten each attach-bridge (re)start +## launches the outdated backend. The first completed status sweep with a +## healthy server consumes this flag and runs the same reconfigure the +## banner button would, so the user isn't left owing a manual click for a +## state the update itself created. Sweeps that land while the server is +## still INCOMPATIBLE (stale-occupant recovery in flight) keep it pending — +## their rows read ERROR, not CONFIGURED_MISMATCH. +var _pending_post_update_repin: bool = false +## The version the completed update replaced — consumed with the flag +## above; the pin-only gate renders each entry against it. +var _post_update_from_version: String = "" +var _client_status_refresh_thread: Thread +## Single source of truth for the refresh-sweep state machine. See +## `ClientRefreshStateScript` for the transition table. Replaces the +## previously scattered booleans (`_in_flight`, `_timed_out`, +## `_deferred_until_filesystem_ready`, `_shutdown_requested`). +var _refresh_state: int = ClientRefreshStateScript.IDLE +## Pending-request flags. Kept separate from `_refresh_state` because +## they're "what should the next refresh look like" — not state of +## any current refresh. A pending request is queued when a refresh +## arrives during RUNNING / RUNNING_TIMED_OUT and consumed by +## `_apply_client_status_refresh_results` once the in-flight worker +## drains. `_pending_force` also captures forced retries deferred via +## DEFERRED_FOR_FILESYSTEM so a pending user click survives the wait. +var _client_status_refresh_pending: bool = false +var _client_status_refresh_pending_force: bool = false +var _client_status_refresh_pending_initial: bool = false +var _last_client_status_refresh_completed_msec: int = 0 +var _client_status_refresh_started_msec: int = 0 +var _client_status_refresh_generation: int = 0 +## Owns the self-update slice: GitHub Releases poll, ZIP download, install +## orchestration, and the install-in-flight gate. Dock keeps banner UI +## only and consults the gate via `_is_self_update_in_progress()`. +var _update_manager +static var _orphaned_client_status_refresh_threads: Array[Thread] = [] + +## Per-row worker state for Configure / Remove. Issue #239: shelling out +## to a hung CLI on main hangs the editor. We dispatch each click to its +## own thread (one slot per client), then `_process` reaps completed workers +## and applies returned payloads on main. The buttons stay disabled while +## the slot is busy so the user can't queue a re-click on the same row. +## +## Per-client (not single-slot) so Configure-all can fan out — the +## workers are independent, only the row UI is shared, and McpCliExec +## bounds the wall-clock for each. +## +## A watchdog can abandon a slot when a worker fails to report completion. +## The thread object is retained in `_orphaned_client_action_threads` until +## it finishes so GDScript does not destroy a live Thread object. +var _client_action_threads: Dictionary = {} +var _client_action_generations: Dictionary = {} +var _client_action_started_msec: Dictionary = {} +var _client_action_names: Dictionary = {} +## Timed-out Configure/Remove workers are abandoned but retained here until +## they finish, so GDScript does not destroy a live Thread object. +static var _orphaned_client_action_threads: Array[Thread] = [] +## Which client each abandoned worker belonged to, so a row whose worker was +## abandoned but is STILL RUNNING can't start a second one on top of it. +## The flat array above exists to keep Thread objects alive; it carries no +## client association, and `_abandon_client_action_thread` erases the row's +## `_client_action_threads` slot — so the dispatch guard alone would let a +## re-click spawn an overlapping worker. Two concurrent Configure workers for +## one client means two uv builds and two writers on the same config file. +## Static for the same reason as the array: a script reload must not GC a +## live Thread. +static var _orphaned_client_action_owners: Dictionary = {} +## Cooperative stop shared across dock instances because orphan action +## threads survive script/dock replacement. A new action clears its row's +## flag before starting; teardown sets every active/orphaned row before join. +static var _client_action_cancel_mutex := Mutex.new() +static var _client_action_cancelled_clients: Dictionary = {} + +# Dev-mode only +var _dev_section: VBoxContainer +var _server_label: Label +var _reload_btn: Button +var _setup_section: VBoxContainer +var _setup_container: VBoxContainer +## Primary dev-section button — always (re)starts a `--reload` dev server. +## Same-version Python edits get adopted as compatible by the lifecycle, so +## neither the drift nor the crash Restart button surfaces; this is the +## unconditional kick contributors need to pick up source changes without +## a version bump. +var _dev_primary_btn: Button +## Small "✕" affordance next to the primary — stops the dev server without +## spawning a replacement. Disabled when no dev server is running. +var _dev_stop_btn: Button +var _log_viewer: LogViewerScript +## Vision Routing (optional) - set by plugin.gd; builds the "Vision Routing" +## tab in Clients & Tools and the quick toggle under Developer mode. +var vision_routing: VisionRoutingScript = null + +var _last_connected := false +var _last_status_text := "" +var _last_status_tooltip := "" +var _startup_grace_until_msec: int = 0 + +# Spawn-failure panel — rendered when `get_server_status` reports a +# non-OK `state`. One panel, one body paragraph per state, no cascading +# booleans. See `_crash_body_for_state`. +var _crash_panel: VBoxContainer +var _crash_output: RichTextLabel +var _crash_restart_btn: Button +var _crash_reload_btn: Button +## Help link — visible only for the genuinely-foreign-occupant INCOMPATIBLE +## case (no `can_recover_incompatible` proof). The inline body names a free +## port; this button carries the per-client reconfigure steps that don't fit +## inline. See `PORT_CONFLICT_DOCS` and `_update_crash_panel`. +var _crash_docs_btn: Button +## Port-picker escape hatch — visible inside the crash panel when the root +## cause is port contention (PORT_EXCLUDED or FOREIGN_PORT). The dock writes +## the EditorSetting and reloads the plugin in response to the panel's +## `port_apply_requested` signal. +var _port_picker_panel: PortPickerPanelScript +## Last status Dict rendered into the panel — used to skip re-population +## when nothing changed, which would otherwise reset the user's scroll +## position on every frame. GDScript Dicts compare by value with `==`. +var _last_server_status: Dictionary = {} + +# First-run grace: uvx installs 60+ Python packages on first run (can take +# 10-30s on a slow connection). Don't scare users with "Disconnected" during +# that window — show "Starting server…" instead. After this expires, fall +# back to the normal disconnect UI. +const STARTUP_GRACE_MSEC := 60 * 1000 + +# Update banner — visible UI only. Releases polling, ZIP download, and +# the install pipeline live on `_update_manager`. +var _update_banner: VBoxContainer +var _update_label: Label +var _update_btn: Button + +# Mixed-state banner — surfaces when `addons/godot_ai/` contains +# `*.update_backup` files left by a self-update whose rollback failed +# (`UpdateReloadRunner.InstallStatus.FAILED_MIXED`). Without this banner +# the user sees "plugin won't start" with no actionable context, re-runs +# the update, and compounds the mismatch (issue #354 / audit-v2 #10). +var _mixed_state_banner: VBoxContainer +var _mixed_state_label: Label +var _mixed_state_files: RichTextLabel +var _mixed_state_rescan_btn: Button + + +func setup(connection: McpConnection, log_buffer: McpLogBuffer, plugin: EditorPlugin) -> void: + _connection = connection + _log_buffer = log_buffer + _plugin = plugin + _startup_grace_until_msec = Time.get_ticks_msec() + STARTUP_GRACE_MSEC + + +func _ready() -> void: + _build_ui() + + +func _process(_delta: float) -> void: + _prune_orphaned_client_status_refresh_threads() + _prune_orphaned_client_action_threads() + _poll_completed_client_status_refresh_thread() + _poll_completed_client_action_threads() + _check_client_status_refresh_timeout() + _check_client_action_timeouts() + if _connection == null: + return + _retry_deferred_client_status_refresh() + _update_status() + if _log_viewer != null and _log_viewer.visible: + _log_viewer.tick() + + +func _exit_tree() -> void: + ## Block on any in-flight refresh worker before letting the dock leave the + ## tree. The plugin disable path (editor_reload_plugin, Project Settings + ## toggle) reloads the McpDock script class — which wipes the static + ## `_orphaned_client_status_refresh_threads`, GCs the Thread objects mid- + ## execution, and triggers `~Thread … destroyed without its completion + ## having been realized` plus GDScript VM corruption (Opcode: 0, IP-bounds + ## errors, intermittent SIGSEGV). Probes finish in well under a second + ## under normal conditions; if a CLI probe genuinely hung, the runtime + ## timeout path (`_abandon_client_status_refresh_thread`) has already + ## moved that thread into the orphan list, so we drain it here too. + ## + ## `wait_to_finish` is unbounded by design: GDScript's Thread API has no + ## timeout, and a polling/abandon fallback would just re-introduce the + ## GC-mid-execution crash this fix exists to prevent. Blocking the editor + ## briefly on plugin-reload is strictly better than the SIGSEGV. + _refresh_state = ClientRefreshStateScript.SHUTTING_DOWN + _drain_client_status_refresh_workers() + _drain_client_action_workers() + + +## Public drain entry consulted by `McpUpdateManager._install_zip` before +## any disk write. Pairs both worker pools so the manager doesn't reach +## into private dock methods. `_exit_tree` still calls the two underlying +## drains directly because it has additional state-machine work +## (SHUTTING_DOWN sticky-set) that the install-time path must NOT inherit. +func prepare_for_self_update_drain() -> void: + _poll_completed_client_status_refresh_thread() + _poll_completed_client_action_threads() + _drain_client_status_refresh_workers() + _drain_client_action_workers() + + +func _drain_client_status_refresh_workers() -> void: + ## Block until any in-flight refresh worker (and any orphaned workers from + ## a prior timeout) finish, then clear refresh state. Same blocking + ## semantics as the `_exit_tree` drain — see #232. Used by `_exit_tree` + ## (dock teardown) and `McpUpdateManager._install_zip` (before extract + ## overwrites plugin scripts on disk). + _client_status_refresh_generation += 1 + if _client_status_refresh_thread != null: + _client_status_refresh_thread.wait_to_finish() + _client_status_refresh_thread = null + for thread in _orphaned_client_status_refresh_threads: + if thread != null: + thread.wait_to_finish() + _orphaned_client_status_refresh_threads.clear() + ## Don't transition out of SHUTTING_DOWN — the drain is called from + ## `_exit_tree` (sticky shutdown) and from + ## `McpUpdateManager._install_zip`'s post-drain reset, which writes + ## the state explicitly. + if _refresh_state != ClientRefreshStateScript.SHUTTING_DOWN: + _refresh_state = ClientRefreshStateScript.IDLE + _client_status_refresh_pending = false + _client_status_refresh_pending_force = false + _client_status_refresh_pending_initial = false + + +func _drain_client_action_workers() -> void: + ## Same drain semantics as the refresh worker (see comment above): the + ## plugin disable / install-update path reloads our script class, so any + ## live Thread must finish before its slot is GC'd or we hit + ## `~Thread … destroyed without its completion having been realized` → + ## VM corruption. Normal UI recovery is handled by the per-row watchdog; + ## teardown still blocks because GDScript's Thread API has no kill/timeout + ## primitive and destroying a live Thread corrupts the VM. + ## + ## Generation-bumped per-row so any result from a worker that finished + ## after we started draining detects the generation mismatch and + ## short-circuits without touching freed UI state. + ## + ## After draining, restore the row UI for any in-flight rows: bare + ## `_client_action_threads.clear()` would leave the dock stuck showing + ## "Configuring…" / "Removing…" with disabled buttons forever — a + ## user-visible failure mode for the install-update bail-out branch + ## (zip extract failure on the manager clears `_install_in_flight` and + ## the dock stays alive). + ## Signal every worker before joining any one of them. Normal Configure + ## keeps its full cold-install budget, while shutdown/update can stop all + ## in-flight uvx poll loops concurrently and avoid a 180s editor stall. + for client_id in _client_action_threads.keys(): + _set_client_action_cancel_requested(String(client_id), true) + for client_id in _orphaned_client_action_owners.keys(): + _set_client_action_cancel_requested(String(client_id), true) + for client_id in _client_action_threads.keys(): + var t: Thread = _client_action_threads[client_id] + if t != null: + t.wait_to_finish() + _client_action_generations[client_id] = int(_client_action_generations.get(client_id, 0)) + 1 + _client_action_started_msec.erase(client_id) + _client_action_names.erase(client_id) + _clear_client_action_phase(String(client_id)) + _finalize_action_buttons(String(client_id)) + var row: Dictionary = _client_rows.get(String(client_id), {}) + if not row.is_empty(): + _apply_row_status( + String(client_id), + row.get("status", Client.Status.NOT_CONFIGURED), + "" + ) + _client_action_threads.clear() + for thread in _orphaned_client_action_threads: + if thread != null: + thread.wait_to_finish() + _orphaned_client_action_threads.clear() + _orphaned_client_action_owners.clear() + _client_action_started_msec.clear() + _client_action_names.clear() + _client_action_phase_mutex.lock() + _client_action_phases.clear() + _client_action_phase_mutex.unlock() + _client_action_phase_shown.clear() + _client_action_cancel_mutex.lock() + _client_action_cancelled_clients.clear() + _client_action_cancel_mutex.unlock() + + +func _check_client_action_timeouts() -> void: + var now := Time.get_ticks_msec() + for client_id in _client_action_threads.keys(): + if not _client_action_started_msec.has(client_id): + continue + var started := int(_client_action_started_msec.get(client_id, 0)) + if now - started >= _client_action_budget_msec(String(client_id)): + _abandon_client_action_thread(String(client_id)) + + +## Watchdog budget for an in-flight client action. +## +## The 30s default is sized for a CLI registry call. Once the worker reports it +## has moved on to building the pinned uv environment, that budget is far too +## short: a cold build is *expected* to run for tens of seconds, and abandoning +## it would report a false Configure timeout for exactly the slow cold start the +## pre-warm exists to absorb — re-enabling the row and discarding the worker's +## completion while the build is still running and about to succeed. +## +## The prewarm phase therefore gets the base budget plus the pre-warm's own +## ceiling. The action still cannot hang forever: `McpCliExec.run` bounds the +## build at `PREWARM_TIMEOUT_MS` on its own, so this is a backstop above a +## backstop rather than the only limit. +func _client_action_budget_msec(client_id: String) -> int: + if _read_client_action_phase(client_id) == _PHASE_PREWARM: + return CLIENT_ACTION_TIMEOUT_MSEC + ClientConfigurator.PREWARM_TIMEOUT_MS + return CLIENT_ACTION_TIMEOUT_MSEC + + +func _abandon_client_action_thread(client_id: String) -> void: + if not _client_action_threads.has(client_id): + return + var thread: Thread = _client_action_threads[client_id] + var elapsed := Time.get_ticks_msec() - int(_client_action_started_msec.get(client_id, Time.get_ticks_msec())) + var worker_alive := thread != null and thread.is_alive() + if thread != null: + _orphaned_client_action_threads.append(thread) + if worker_alive: + ## The worker can cross the base watchdog immediately before it + ## announces PREWARM. Cancel now so it cannot become an orphan and + ## then begin a fresh 180s uvx operation outside timeout tracking. + _set_client_action_cancel_requested(client_id, true) + var owned: Array = _orphaned_client_action_owners.get(client_id, []) + owned.append(thread) + _orphaned_client_action_owners[client_id] = owned + _client_action_threads.erase(client_id) + _client_action_started_msec.erase(client_id) + _clear_client_action_phase(client_id) + var action := str(_client_action_names.get(client_id, "configure")) + _client_action_names.erase(client_id) + _client_action_generations[client_id] = int(_client_action_generations.get(client_id, 0)) + 1 + ## Only hand the row back when nothing is still running for it. Re-enabling + ## while the abandoned worker is mid-build invites a second worker on top + ## of the first; the prune below re-enables the row once it actually ends. + if not worker_alive: + _finalize_action_buttons(client_id) + print("MCP | client action timed out: client=%s action=%s elapsed_ms=%d worker_alive=%s" % [ + client_id, + action, + elapsed, + str(worker_alive), + ]) + var label := "Remove" if action == "remove" else "Configure" + var detail := ( + "%s is taking longer than expected and is still running; refreshing current status." % label + if worker_alive + else "%s did not report completion in time; refreshing current status." % label + ) + _apply_row_status(client_id, Client.Status.ERROR, detail) + _refresh_clients_summary() + if is_inside_tree(): + _request_client_status_refresh(true) + + +func _prune_orphaned_client_action_threads() -> void: + var completed_orphan := false + for i in range(_orphaned_client_action_threads.size() - 1, -1, -1): + var thread := _orphaned_client_action_threads[i] + if thread == null: + _orphaned_client_action_threads.remove_at(i) + elif not thread.is_alive(): + thread.wait_to_finish() + _orphaned_client_action_threads.remove_at(i) + completed_orphan = true + _release_finished_orphan_owners() + if completed_orphan and is_inside_tree(): + _request_client_action_completion_refresh() + + +## Hand a row back once its abandoned worker has actually finished. Pairs with +## `_abandon_client_action_thread`, which deliberately leaves the buttons +## disabled while the orphan is still running — without this the row would stay +## disabled forever. +func _release_finished_orphan_owners() -> void: + for client_id in _orphaned_client_action_owners.keys(): + var owned: Array = _orphaned_client_action_owners[client_id] + for i in range(owned.size() - 1, -1, -1): + var t: Thread = owned[i] + if t == null or not t.is_alive(): + owned.remove_at(i) + if owned.is_empty(): + _orphaned_client_action_owners.erase(client_id) + if not _client_action_threads.has(client_id): + _finalize_action_buttons(String(client_id)) + + +## True while a previously-abandoned worker for this client is still running. +static func _has_live_orphan(client_id: String) -> bool: + var owned: Array = _orphaned_client_action_owners.get(client_id, []) + for t in owned: + if t != null and (t as Thread).is_alive(): + return true + return false + + +func _request_client_action_completion_refresh() -> void: + _request_client_status_refresh(true) + + +func _notification(what: int) -> void: + # Detect dock/undock by watching for reparenting events. + if what == NOTIFICATION_PARENTED or what == NOTIFICATION_UNPARENTED: + _update_redock_visibility.call_deferred() + elif what == NOTIFICATION_APPLICATION_FOCUS_IN: + if _should_refresh_client_statuses_on_focus_in(): + _request_client_status_refresh(false) + ## Re-probe uv only when the user actually went off to install it + ## (see _on_install_uv). `check_uv_version()` is cached, so an + ## ungated refresh here would usually be free — but after the + ## button invalidated that cache it costs one blocking + ## `uvx --version`, and this notification must not grow a probe on + ## the common focus-in path. One-shot: clear before refreshing. + if _uv_recheck_pending: + _uv_recheck_pending = false + _refresh_setup_status.call_deferred() + + +func _should_refresh_client_statuses_on_focus_in() -> bool: + ## Focus-in is part of Godot/editor window activation. Keep automatic refresh, + ## but only through the async/cooldown-protected path; never run a blocking + ## client-status sweep directly from this notification. + return true + + +func _is_floating() -> bool: + var p := get_parent() + while p != null: + if p is Window: + return p != get_tree().root + p = p.get_parent() + return false + + +func _update_redock_visibility() -> void: + if _redock_btn == null: + return + var floating := _is_floating() + if _redock_btn.visible != floating: + _redock_btn.visible = floating + + +func _on_redock() -> void: + # When floating, our Window is NOT the editor root. Closing it triggers + # Godot's internal dock-return logic (same as clicking the window's X). + var win := get_window() + if win != null and win != get_tree().root: + win.close_requested.emit() + + +func _build_margin_container(margin: int = 12) -> MarginContainer: + var margin_container := MarginContainer.new() + margin_container.add_theme_constant_override("margin_left", margin) + margin_container.add_theme_constant_override("margin_right", margin) + margin_container.add_theme_constant_override("margin_top", margin) + margin_container.add_theme_constant_override("margin_bottom", margin) + return margin_container + + +func _build_ui() -> void: + add_theme_constant_override("separation", 8) + + # --- Top row: status indicator + redock button (when floating) --- + var status_row := HBoxContainer.new() + status_row.add_theme_constant_override("separation", 8) + + _status_icon = ColorRect.new() + _status_icon.custom_minimum_size = Vector2(14, 14) + # Amber on first paint — matches the "Starting server…" label text and + # distinguishes from a real disconnect (red). + _status_icon.color = COLOR_AMBER + var icon_center := CenterContainer.new() + icon_center.add_child(_status_icon) + status_row.add_child(icon_center) + + _status_label = Label.new() + # Start in grace state — _update_status will take over on the next frame + # once the connection is available. Never show bare "Disconnected" on + # first paint because that's misleading while the server is still + # spinning up. + _status_label.text = "Starting server…" + _status_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + status_row.add_child(_status_label) + + _redock_btn = Button.new() + _redock_btn.text = "Dock" + _redock_btn.tooltip_text = "Return this panel to the editor dock" + _redock_btn.visible = false + _redock_btn.pressed.connect(_on_redock) + status_row.add_child(_redock_btn) + + add_child(status_row) + + # Install-mode line — so a git-clone user doesn't press the yellow Update + # banner below and silently downgrade from main to the last release tag. + # See #144. + _install_label = Label.new() + _install_label.add_theme_color_override("font_color", COLOR_MUTED) + _install_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _install_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _install_label.text = _install_mode_text() + _install_label.tooltip_text = _install_mode_tooltip() + _install_label.mouse_filter = Control.MOUSE_FILTER_STOP + add_child(_install_label) + + _body_scroll = ScrollContainer.new() + _body_scroll.name = "DockBodyScroll" + _body_scroll.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _body_scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL + _body_scroll.custom_minimum_size = Vector2(0, 48) + _body_scroll.horizontal_scroll_mode = ScrollContainer.SCROLL_MODE_DISABLED + add_child(_body_scroll) + + _body = VBoxContainer.new() + _body.name = "DockBody" + _body.add_theme_constant_override("separation", 8) + _body.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _body_scroll.add_child(_body) + + # --- Spawn-failure panel (shown when `_start_server` reports a non-OK + # state via `get_server_status`). One body paragraph + the matching + # action; the top status label already carries the state headline. + _crash_panel = VBoxContainer.new() + _crash_panel.add_theme_constant_override("separation", 6) + _crash_panel.visible = false + + _crash_output = RichTextLabel.new() + _crash_output.custom_minimum_size = Vector2(0, 60) + _crash_output.bbcode_enabled = false + _crash_output.selection_enabled = true + _crash_output.scroll_following = false + _crash_output.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _crash_output.fit_content = true + _crash_panel.add_child(_crash_output) + + _port_picker_panel = PortPickerPanelScript.new() + _port_picker_panel.setup() + _port_picker_panel.port_apply_requested.connect(_on_port_apply_requested) + _crash_panel.add_child(_port_picker_panel) + + _crash_restart_btn = Button.new() + _crash_restart_btn.text = "Restart Server" + _crash_restart_btn.tooltip_text = "Stop the old server on this port and start the bundled godot-ai server" + _crash_restart_btn.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _crash_restart_btn.add_theme_color_override("font_color", Color.WHITE) + _crash_restart_btn.add_theme_color_override("font_hover_color", Color.WHITE) + _crash_restart_btn.add_theme_color_override("font_pressed_color", Color.WHITE) + _crash_restart_btn.pressed.connect(_on_restart_stale_server) + _crash_restart_btn.visible = false + _crash_panel.add_child(_crash_restart_btn) + + _crash_reload_btn = Button.new() + _crash_reload_btn.text = "Reload Plugin" + _crash_reload_btn.tooltip_text = "Re-run the spawn after fixing the underlying issue" + _crash_reload_btn.pressed.connect(_on_reload_plugin) + _crash_panel.add_child(_crash_reload_btn) + + _crash_docs_btn = Button.new() + _crash_docs_btn.text = "How to change the port" + _crash_docs_btn.tooltip_text = "Open the guide: change godot_ai/http_port and reconfigure your MCP clients" + _crash_docs_btn.visible = false + _crash_docs_btn.pressed.connect(func(): OS.shell_open(_port_conflict_docs_url())) + _crash_panel.add_child(_crash_docs_btn) + + _crash_panel.add_child(HSeparator.new()) + _body.add_child(_crash_panel) + + _build_mixed_state_banner() + _refresh_mixed_state_banner() + + # --- Update banner (top of dock, hidden until check finds a newer version) --- + _update_banner = VBoxContainer.new() + _update_banner.add_theme_constant_override("separation", 4) + _update_banner.visible = false + + _update_label = Label.new() + _update_label.add_theme_font_size_override("font_size", 15) + _update_label.add_theme_color_override("font_color", Color(1.0, 0.85, 0.3)) + ## Wrap long banner text (e.g. the < 4.5 support-floor guidance) instead + ## of letting a single line stretch the whole dock wide. The dock is a + ## fixed-width side panel, so constrain horizontally and wrap. + _update_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _update_label.size_flags_horizontal = Control.SIZE_FILL + _update_label.custom_minimum_size = Vector2(0, 0) + _update_banner.add_child(_update_label) + + var update_btn_row := HBoxContainer.new() + update_btn_row.add_theme_constant_override("separation", 6) + + _update_btn = Button.new() + _update_btn.text = "Update" + _update_btn.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _update_btn.pressed.connect(_on_update_pressed) + update_btn_row.add_child(_update_btn) + + var release_link := Button.new() + release_link.text = "Release notes" + release_link.pressed.connect(func(): OS.shell_open(UpdateManagerScript.RELEASES_PAGE)) + update_btn_row.add_child(release_link) + + _update_banner.add_child(update_btn_row) + _update_banner.add_child(HSeparator.new()) + + _body.add_child(_update_banner) + + if _update_manager == null: + _update_manager = UpdateManagerScript.new() + _update_manager.setup(_plugin, self) + _update_manager.update_check_completed.connect(_on_update_check_result) + _update_manager.install_state_changed.connect(_on_install_state_changed) + _body.add_child(_update_manager) + _update_manager.check_for_updates.call_deferred() + + # --- Dev-only connection extras (server label + reload button) --- + _dev_section = VBoxContainer.new() + _dev_section.add_theme_constant_override("separation", 6) + _body.add_child(_dev_section) + + _server_label = Label.new() + _server_label.add_theme_color_override("font_color", COLOR_MUTED) + _dev_section.add_child(_server_label) + _refresh_server_label() + + var btn_row := HBoxContainer.new() + btn_row.add_theme_constant_override("separation", 6) + + _reload_btn = Button.new() + _reload_btn.text = "Dev: Reload Plugin" + _reload_btn.tooltip_text = "Developer utility: reload the GDScript plugin. This does not restart or replace the server." + _reload_btn.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _reload_btn.pressed.connect(_on_reload_plugin) + btn_row.add_child(_reload_btn) + + _dev_section.add_child(btn_row) + + # --- Setup section (dev-only or when uv missing) --- + _setup_section = VBoxContainer.new() + _setup_section.add_theme_constant_override("separation", 6) + _body.add_child(_setup_section) + + _setup_section.add_child(HSeparator.new()) + _setup_section.add_child(_make_header("Setup")) + _setup_container = VBoxContainer.new() + _setup_container.add_theme_constant_override("separation", 6) + _setup_section.add_child(_setup_container) + + _body.add_child(HSeparator.new()) + + # --- Clients --- + var clients_header_row := HBoxContainer.new() + clients_header_row.add_theme_constant_override("separation", 8) + + var clients_header := _make_header("Clients") + clients_header_row.add_child(clients_header) + + _clients_summary_label = Label.new() + _clients_summary_label.add_theme_color_override("font_color", COLOR_MUTED) + _clients_summary_label.clip_text = true + _clients_summary_label.text_overrun_behavior = TextServer.OVERRUN_TRIM_ELLIPSIS + _clients_summary_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + clients_header_row.add_child(_clients_summary_label) + + var clients_actions := HFlowContainer.new() + clients_actions.add_theme_constant_override("h_separation", 8) + clients_actions.add_theme_constant_override("v_separation", 4) + + var clients_refresh_btn := Button.new() + clients_refresh_btn.text = "Refresh" + clients_refresh_btn.tooltip_text = "Refresh client status in the background. Cached status stays visible while checks run." + clients_refresh_btn.pressed.connect(_on_refresh_clients_pressed) + clients_actions.add_child(clients_refresh_btn) + + var clients_open_btn := Button.new() + clients_open_btn.text = "Clients & Tools" + clients_open_btn.tooltip_text = "Open the Clients & Tools window — configure AI clients, choose telemetry preferences, or disable tool domains to fit under a client's hard tool-count cap (e.g. Antigravity's 100)." + clients_open_btn.pressed.connect(_on_open_clients_window) + clients_actions.add_child(clients_open_btn) + + _body.add_child(clients_header_row) + _body.add_child(clients_actions) + + _client_empty_cta_btn = Button.new() + _client_empty_cta_btn.text = "Configure an AI client ->" + _client_empty_cta_btn.tooltip_text = "Open the Clients tab to configure an AI coding client for this Godot AI server." + _client_empty_cta_btn.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _client_empty_cta_btn.visible = false + _client_empty_cta_btn.pressed.connect(_on_open_clients_window) + _body.add_child(_client_empty_cta_btn) + + # Drift banner — hidden until a sweep finds at least one mismatched client. + _drift_banner = VBoxContainer.new() + _drift_banner.add_theme_constant_override("separation", 4) + _drift_banner.visible = false + _drift_label = Label.new() + _drift_label.add_theme_color_override("font_color", COLOR_AMBER) + _drift_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _drift_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _drift_banner.add_child(_drift_label) + var drift_btn := Button.new() + drift_btn.text = "Reconfigure mismatched" + drift_btn.tooltip_text = "Re-run Configure on every client whose stored URL doesn't match the current server URL." + drift_btn.pressed.connect(_on_reconfigure_mismatched) + _drift_banner.add_child(drift_btn) + _body.add_child(_drift_banner) + + _clients_window = Window.new() + _clients_window.title = "Godot AI Settings" + ## `Vector2i * float` yields Vector2; wrap the result back to Vector2i. + _clients_window.min_size = Vector2i(Vector2(560, 460) * EditorInterface.get_editor_scale()) + _clients_window.visible = false + _clients_window.close_requested.connect(_on_clients_window_close_requested) + add_child(_clients_window) + + ## Tabbed secondary window: Clients (per-client rows), Tools (domain- + ## exclusion checkboxes for clients that cap total tool count, like + ## Antigravity at 100), and Settings (allow-host LAN opt-in, #507). + ## Adding another tab is one more _build_*_tab call — no surgery on the + ## rest of the window. + var tabs := TabContainer.new() + tabs.anchor_right = 1.0 + tabs.anchor_bottom = 1.0 + _clients_window.add_child(tabs) + + var clients_tab := VBoxContainer.new() + clients_tab.add_theme_constant_override("separation", 8) + var clients_margin := _build_margin_container() + clients_margin.name = "Clients" + clients_margin.add_child(clients_tab) + tabs.add_child(clients_margin) + + _client_configure_all_btn = Button.new() + _client_configure_all_btn.text = "Configure all" + _client_configure_all_btn.tooltip_text = "Configure every client that isn't already pointing at this server" + _client_configure_all_btn.size_flags_horizontal = Control.SIZE_SHRINK_END + _client_configure_all_btn.pressed.connect(_on_configure_all_clients) + clients_tab.add_child(_client_configure_all_btn) + + var clients_scroll := ScrollContainer.new() + clients_scroll.size_flags_horizontal = Control.SIZE_EXPAND_FILL + clients_scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL + clients_scroll.horizontal_scroll_mode = ScrollContainer.SCROLL_MODE_DISABLED + clients_tab.add_child(clients_scroll) + + _client_grid = VBoxContainer.new() + _client_grid.add_theme_constant_override("separation", 4) + _client_grid.size_flags_horizontal = Control.SIZE_EXPAND_FILL + clients_scroll.add_child(_client_grid) + + for client_id in ClientConfigurator.client_ids(): + _build_client_row(client_id) + + _build_tools_tab(tabs) + _build_settings_tab(tabs) + + _body.add_child(HSeparator.new()) + + # --- Dev mode toggle (always visible) --- + var dev_toggle_row := HBoxContainer.new() + var dev_toggle_label := Label.new() + dev_toggle_label.text = "Developer mode" + dev_toggle_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + dev_toggle_row.add_child(dev_toggle_label) + + _dev_mode_toggle = CheckButton.new() + _dev_mode_toggle.button_pressed = _load_dev_mode() + _dev_mode_toggle.toggled.connect(_on_dev_mode_toggled) + dev_toggle_row.add_child(_dev_mode_toggle) + _body.add_child(dev_toggle_row) + + # --- Log section (dev-only) --- + _log_viewer = LogViewerScript.new() + _log_viewer.setup(_log_buffer) + _log_viewer.logging_enabled_changed.connect(_on_log_logging_enabled_changed) + _body.add_child(_log_viewer) + + # Apply initial dev-mode visibility + _apply_dev_mode_visibility() + _refresh_setup_status.call_deferred() + _perform_initial_client_status_refresh() + + +## Static so `dock_panels/*.gd` subpanels can call it via `McpDock._make_header(...)` +## without re-declaring identical helpers + COLOR_HEADER constants. +static func _make_header(text: String) -> Label: + var label := Label.new() + label.text = text + label.add_theme_font_size_override("font_size", 18) + label.add_theme_color_override("font_color", COLOR_HEADER) + return label + + +func _build_client_row(client_id: String) -> void: + var row := HBoxContainer.new() + row.add_theme_constant_override("separation", 6) + row.size_flags_horizontal = Control.SIZE_EXPAND_FILL + + var dot := ColorRect.new() + dot.custom_minimum_size = Vector2(10, 10) + dot.color = COLOR_MUTED + var dot_center := CenterContainer.new() + dot_center.add_child(dot) + row.add_child(dot_center) + + var name_label := Label.new() + name_label.text = ClientConfigurator.client_display_name(client_id) + name_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + ## #838/#816 step 11: say which transport Configure will write — the + ## client-owned attach bridge or the client's native URL mode. + var transport_tag := Label.new() + transport_tag.text = _client_transport_tag(client_id) + transport_tag.add_theme_color_override("font_color", COLOR_MUTED) + transport_tag.tooltip_text = ( + "Configure writes a local `godot-ai attach` launch command for this client." + if transport_tag.text == "attach" + else "Configure writes this client's native URL entry." + ) + ## Long error messages from `_verify_post_state` (e.g. "reported remove ok + ## but verification still reads configured…") used to push the Retry / + ## Configure button off-screen — the row's Label wanted its full text + ## width as minimum size, so the buttons got squeezed out. Wrap onto + ## multiple lines instead so the row keeps its right edge stable and + ## the buttons remain visible; the user can also read the whole message + ## without resizing the window. + name_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + name_label.vertical_alignment = VERTICAL_ALIGNMENT_CENTER + row.add_child(name_label) + row.add_child(transport_tag) + + var configure_btn := Button.new() + configure_btn.text = "Configure" + configure_btn.pressed.connect(_on_configure_client.bind(client_id)) + row.add_child(configure_btn) + + var remove_btn := Button.new() + remove_btn.text = "Remove" + remove_btn.visible = false + remove_btn.pressed.connect(_on_remove_client.bind(client_id)) + row.add_child(remove_btn) + + # F-3-4: use the authoritative facade so Open/Reveal land on the same + # file `_check_status_merged` drives (last-wins across project tiers, + # matching the F2 status fix). + var config_path := ClientConfigurator.effective_authoritative_path(client_id) + var open_config_btn := Button.new() + _apply_editor_icon(open_config_btn, "ExternalLink", "Open") + open_config_btn.custom_minimum_size = Vector2(28, 28) + open_config_btn.visible = not config_path.is_empty() + open_config_btn.pressed.connect(_on_open_config_file.bind(client_id)) + row.add_child(open_config_btn) + + var reveal_btn := Button.new() + _apply_editor_icon(reveal_btn, "Folder", "Reveal") + reveal_btn.custom_minimum_size = Vector2(28, 28) + reveal_btn.visible = not config_path.is_empty() + reveal_btn.pressed.connect(_on_reveal_config_folder.bind(client_id)) + row.add_child(reveal_btn) + + _client_grid.add_child(row) + + var manual_panel := VBoxContainer.new() + manual_panel.add_theme_constant_override("separation", 4) + manual_panel.visible = false + + var manual_hint := Label.new() + manual_hint.text = "Run this manually:" + manual_hint.add_theme_color_override("font_color", COLOR_MUTED) + manual_panel.add_child(manual_hint) + + var manual_text := TextEdit.new() + manual_text.editable = false + manual_text.custom_minimum_size = Vector2(0, 60) + manual_text.wrap_mode = TextEdit.LINE_WRAPPING_BOUNDARY + manual_panel.add_child(manual_text) + + var copy_btn := Button.new() + copy_btn.text = "Copy" + copy_btn.pressed.connect(_on_copy_manual_command.bind(client_id)) + manual_panel.add_child(copy_btn) + + _client_grid.add_child(manual_panel) + + _client_rows[client_id] = { + "dot": dot, + "status": Client.Status.NOT_CONFIGURED, + "name_label": name_label, + "configure_btn": configure_btn, + "remove_btn": remove_btn, + "open_config_btn": open_config_btn, + "reveal_btn": reveal_btn, + "config_path": config_path, + "manual_panel": manual_panel, + "manual_text": manual_text, + } + _refresh_client_config_file_buttons(client_id) + + +func _apply_editor_icon(button: Button, icon_name: String, fallback_text: String) -> void: + if has_theme_icon(icon_name, "EditorIcons"): + button.icon = get_theme_icon(icon_name, "EditorIcons") + else: + button.text = fallback_text + + +# --- Status updates --- + +func _update_status() -> void: + var connected: bool = _connection != null and _connection.is_connected + ## Pull the connection's transport snapshot on this existing refresh tick. + ## `has_method` preserves the plugin self-update seam while an older + ## Connection instance is still alive under a hot-reloaded dock script. + var transport_status: Dictionary = ( + _connection.get_transport_status() + if _connection != null and _connection.has_method("get_transport_status") + else {} + ) + ## During plugin self-update there's a brief window where this dock + ## script is already the new version (Godot hot-reloads scripts on + ## file change) but `_plugin` is still the old `EditorPlugin` instance + ## (only `set_plugin_enabled(false, true)` re-instantiates that). When + ## the new dock calls a method the old plugin doesn't have, `_process` + ## errors every frame until `McpUpdateManager._reload_after_update` + ## lands. Guard every `_plugin.()` call with `has_method` + ## so that window stays silent. See #168. + var server_status: Dictionary = ( + _plugin.get_server_status() + if _plugin != null and _plugin.has_method("get_server_status") + else {} + ) + var state: int = int(server_status.get("state", ServerStateScript.UNINITIALIZED)) + if ServerStateScript.blocks_client_health(state): + connected = false + + ## One `match`/`elif` chain, one source of truth. Adding a new + ## spawn outcome = one `ServerStateScript` constant + one arm here + + ## one body string in `_crash_body_for_state`. + ## Default covers both a missing/old Connection instance and an unknown + ## future transport phase. Every recognized state below overrides it, so + ## startup grace and settled disconnect have one rendering path. + var inside_startup_grace := Time.get_ticks_msec() < _startup_grace_until_msec + var status_text := "Starting server…" if inside_startup_grace else "Disconnected" + var status_color := COLOR_AMBER if inside_startup_grace else Color.RED + if _server_restart_in_progress: + status_text = "Restarting server..." + status_color = COLOR_AMBER + elif connected: + status_text = _connected_status_text() + status_color = Color.GREEN + elif state == ServerStateScript.CRASHED: + var exit_ms: int = server_status.get("exit_ms", 0) + status_text = "Server exited after %.1fs" % (exit_ms / 1000.0) + status_color = Color.RED + elif state == ServerStateScript.PORT_EXCLUDED: + status_text = "Port %d reserved by Windows" % ClientConfigurator.http_port() + status_color = Color.RED + elif state == ServerStateScript.INCOMPATIBLE: + status_text = "Incompatible server on port %d" % ClientConfigurator.http_port() + status_color = Color.RED + elif state == ServerStateScript.FOREIGN_PORT: + ## #647: the post-crash probe names the actual conflicting port + ## (HTTP or WS) — don't blame port 8000 when 9500 is the occupant. + var conflict_port: int = int(server_status.get("conflict_port", 0)) + if conflict_port <= 0: + conflict_port = ClientConfigurator.http_port() + status_text = "Port %d held by another process" % conflict_port + status_color = Color.RED + elif state == ServerStateScript.NO_COMMAND: + status_text = "No server command found" + status_color = Color.RED + elif not transport_status.is_empty(): + var transport_phase := str(transport_status.get("phase", "")) + if transport_phase == "connecting": + status_text = _transport_status_text(transport_status) + status_color = COLOR_AMBER + elif transport_phase == "retrying": + status_text = _transport_status_text(transport_status) + status_color = COLOR_AMBER + elif transport_phase == "closing": + status_text = _transport_status_text(transport_status) + status_color = COLOR_AMBER + elif transport_phase == "blocked": + ## Exact terminal labels come from lifecycle state above. This is a + ## generic fallback for a blocked connection without a diagnosis. + status_text = _transport_status_text(transport_status) + status_color = Color.RED + + ## keep_server_on_exit (#800): the reaper env opt-outs are staged at + ## spawn, so a mid-session toggle only lands on the next server start — + ## say so while the running server still carries the old behavior. + if connected and ClientConfigurator.keep_server_on_exit() != bool(server_status.get("keep_alive", false)): + status_text += " — keep-server-on-exit applies after Restart" + + _update_crash_panel(server_status) + _refresh_server_version_label(server_status) + _refresh_server_label(server_status) + + ## A transient disconnect reason remains in the transport snapshot until + ## handshake_ack. Once the dock renders the connection as OPEN, do not pair + ## its green label with the previous peer's recovery diagnostic. + var status_tooltip := "" if connected else str(transport_status.get("reason", "")) + var changed: bool = ( + connected != _last_connected + or status_text != _last_status_text + or status_tooltip != _last_status_tooltip + ) + if not changed: + return + var just_connected: bool = connected and not _last_connected + _last_connected = connected + _last_status_text = status_text + _last_status_tooltip = status_tooltip + _status_icon.color = status_color + _status_label.text = status_text + _status_label.tooltip_text = status_tooltip + if just_connected: + ## #739: the server just came up. If the startup uv probe failed + ## (the reporter's screenshot: green "Server connected" beside a + ## red "uv: not found" row), the failure was transient — re-probe + ## instead of pinning the red row for the whole session. Runs + ## AFTER the label writes above and via the deferred queue, so the + ## status-machine state is committed before the probe can block. + _schedule_uv_reprobe() + + ## Status transitions are exactly when "is the launch still settling?" + ## can change (Starting server… -> connected / Disconnected / terminal + ## diagnosis), so re-evaluate the Setup section's visibility here (#744). + ## Cheap: runs only on `changed`, and the uv probe result is cached. + _apply_dev_mode_visibility() + + _update_dev_section_buttons() + + +## Render the diagnostic panel body for a given spawn state. The top +## status label already names the problem; this answers "what do I do?". +## Panel shows for any non-OK state; picker shows only when moving the HTTP +## port alone is a valid recovery. Incompatible godot-ai servers commonly +## hold both HTTP and WS ports, so their message points to Editor Settings +## instead of offering the HTTP-only quick picker. +func _update_crash_panel(server_status: Dictionary) -> void: + var state: int = int(server_status.get("state", ServerStateScript.UNINITIALIZED)) + if not ServerStateScript.is_terminal_diagnosis(state): + if _crash_panel.visible: + _crash_panel.visible = false + _last_server_status = {} + return + if server_status == _last_server_status: + return + _last_server_status = server_status.duplicate() + _crash_panel.visible = true + _crash_output.clear() + _crash_output.add_text(_crash_body_for_state(state, server_status)) + var show_recovery_restart := ( + state == ServerStateScript.INCOMPATIBLE + and bool(server_status.get("can_recover_incompatible", false)) + ) + if _crash_restart_btn != null: + _crash_restart_btn.visible = show_recovery_restart + _crash_restart_btn.disabled = _server_restart_in_progress + _crash_restart_btn.text = "Restarting..." if _server_restart_in_progress else "Restart Server" + if _crash_reload_btn != null: + _crash_reload_btn.visible = ( + not show_recovery_restart + and state != ServerStateScript.INCOMPATIBLE + ) + ## Docs link only for the genuinely-foreign occupant: a recoverable + ## (older godot-ai) server gets Restart Server instead, and the inline + ## body already names a free port — the link carries the per-client + ## reconfigure steps that don't fit inline. + if _crash_docs_btn != null: + _crash_docs_btn.visible = ( + state == ServerStateScript.INCOMPATIBLE + and not bool(server_status.get("can_recover_incompatible", false)) + ) + + ## #647: the quick picker only moves `godot_ai/http_port`, so hide it + ## when the diagnosed conflict is on the WebSocket port — the crash + ## body already points at `godot_ai/ws_port` in Editor Settings. + var conflict_port := int(server_status.get("conflict_port", 0)) + var http_conflict := conflict_port <= 0 or conflict_port == ClientConfigurator.http_port() + var port_picker_visible := ( + state == ServerStateScript.PORT_EXCLUDED + or (state == ServerStateScript.FOREIGN_PORT and http_conflict) + ) + _port_picker_panel.visible = port_picker_visible + if port_picker_visible: + ## Seed the spinbox with a suggested non-reserved port each time the + ## panel surfaces. Idempotent when the user already has a good + ## candidate queued up. + _port_picker_panel.seed_suggested_port() + + +static func _crash_body_for_state(state: int, server_status: Dictionary = {}) -> String: + ## Single sentence per state. The top status label already names the + ## problem; don't repeat it here. This copy answers "what do I do?". + var port := ClientConfigurator.http_port() + match state: + ServerStateScript.PORT_EXCLUDED: + return "Windows (Hyper-V / WSL2 / Docker) reserved port %d. Pick a free port or try `net stop winnat; net start winnat` in an admin shell." % port + ServerStateScript.INCOMPATIBLE: + var message := str(server_status.get("message", "")) + if bool(server_status.get("can_recover_incompatible", false)): + var expected := str(server_status.get("expected_version", "")) + if expected.is_empty(): + expected = ClientConfigurator.get_plugin_version() + if not message.is_empty(): + return "%s Click Restart Server below to replace it with godot-ai v%s." % [message, expected] + return "Port %d is occupied by an older godot-ai server. Click Restart Server below to replace it with godot-ai v%s." % [port, expected] + ## Genuinely foreign occupant (no recovery proof). Name a concrete + ## free port so the user doesn't have to hunt for one, and let the + ## crash panel's "How to change the port" link carry the per-client + ## reconfigure steps. `suggest_free_port` already routes through the + ## Windows reservation table, so the named port won't itself fail + ## with WinError 10013. + var hint := _free_port_hint(port) + if not message.is_empty(): + return "%s %s" % [message, hint] + return "Port %d is occupied by an incompatible server. %s" % [port, hint] + ServerStateScript.FOREIGN_PORT: + ## #647: prefer the lifecycle's diagnosis (it names the right + ## port — HTTP vs WS — and the Editor Setting to change) over + ## the generic HTTP-port fallback. + var foreign_message := str(server_status.get("message", "")) + if not foreign_message.is_empty(): + return foreign_message + return "Another process is already bound to port %d. Pick a free port or stop the other process." % port + ServerStateScript.CRASHED: + ## #805: a specific crash diagnosis from the lifecycle (e.g. the + ## flapping-occupant latch) beats the generic launch-mode copy. + ## Generic crash paths clear the message, so stale text from an + ## earlier state can't leak in here. + var crash_message := str(server_status.get("message", "")) + if not crash_message.is_empty(): + return crash_message + ## Both spawn attempts failed on the uvx tier — stock releases: + ## PyPI lag. Local builds (version with +metadata): almost always the + ## dev venv was not found (unresolved junction/symlink) so uvx tried + ## a pin that may lack checkout-local extras. + if ClientConfigurator.get_server_launch_mode() == "uvx": + var version := ClientConfigurator.get_plugin_version() + var pin := ClientConfigurator._pypi_pin_version(version) + if pin != version: + ## `%` binds tighter than `+` in GDScript — format the fully + ## concatenated string, never the last fragment alone. + return ( + "The server exited before the WebSocket handshake. " + + "Local plugin version is %s (PEP 440 local build metadata) — uvx pins PyPI godot-ai==%s. " + + "If you need checkout-local server code, ensure addons/godot_ai resolves to your " + + "dev tree (symlink/junction) with a `.venv`, or set GODOT_AI_VENV_PYTHON to that " + + "venv's python binary, then Reload Plugin. Log should show 'MCP | using dev venv: ...'." + ) % [version, pin] + return ( + "The server exited before the WebSocket handshake, even after a `uvx --refresh` retry. " + + "If this is a brand-new release, PyPI's index may still be propagating (~10 min). " + + "Wait a moment and click Reload Plugin to retry, or check Godot's output log for Python's traceback. " + + "Target: godot-ai==%s." + ) % pin + return "The server exited before the WebSocket handshake. Check Godot's output log (bottom panel) for Python's traceback." + ServerStateScript.NO_COMMAND: + return "No godot-ai server found. Install `uv` via the Setup panel above, or run `pip install godot-ai`." + _: + return "" + + +## One sentence naming concrete free ports for the user to switch to. Names +## BOTH http and ws: this branch also fires for an incompatible godot-ai +## server we can't prove we own, which commonly holds both ports — moving only +## http would then leave the new server unable to bind ws. Both suggestions are +## routed through `suggest_free_port` so they clear Windows' winnat reservation +## table (no point suggesting a port that 10013s on bind). Only the http port +## reaches client configs; the ws port is server↔plugin, hence the wording. +## The per-client reconfigure steps live behind the crash panel's docs link. +static func _free_port_hint(port: int) -> String: + var free_http := ClientConfigurator.suggest_free_port(port + 1) + var free_ws := ClientConfigurator.suggest_free_port(ClientConfigurator.ws_port() + 1) + return "Ports %d (HTTP) and %d (WS) are free — set `godot_ai/http_port` and `godot_ai/ws_port` in Editor Settings, then update your client config with the new HTTP port (How to change the port, below)." % [free_http, free_ws] + + +## URL for the port-conflict guide, pinned to the release tag that matches the +## installed plugin version (releases are tagged `v`). The crash-panel +## button only exists in builds that ship `docs/port-conflicts.md`, so the +## versioned ref always resolves — and a shipped build never points users at a +## tip-of-main guide that has drifted from its own UI. +static func _port_conflict_docs_url() -> String: + var version := ClientConfigurator.get_plugin_version() + var git_ref := ("v%s" % version) if not version.is_empty() else "main" + return "%s/%s/%s" % [REPO_BLOB_BASE, git_ref, PORT_CONFLICT_DOCS_PATH] + + +## Build the mixed-state banner. Hidden until `_refresh_mixed_state_banner` +## confirms `*.update_backup` files exist in the addons tree. Mirrors the +## issue #354 fix shape: structured, agent-readable diagnostic that survives +## a normal editor restart so the user can act on it instead of re-running +## the update. +func _build_mixed_state_banner() -> void: + _mixed_state_banner = VBoxContainer.new() + _mixed_state_banner.add_theme_constant_override("separation", 4) + _mixed_state_banner.visible = false + + _mixed_state_label = Label.new() + _mixed_state_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _mixed_state_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _mixed_state_label.add_theme_color_override("font_color", Color.RED) + _mixed_state_banner.add_child(_mixed_state_label) + + _mixed_state_files = RichTextLabel.new() + _mixed_state_files.bbcode_enabled = false + _mixed_state_files.fit_content = true + _mixed_state_files.autowrap_mode = TextServer.AUTOWRAP_OFF + _mixed_state_files.selection_enabled = true + _mixed_state_files.scroll_active = true + _mixed_state_files.custom_minimum_size = Vector2(0, 90) + _mixed_state_files.add_theme_color_override("default_color", COLOR_AMBER) + _mixed_state_banner.add_child(_mixed_state_files) + + _mixed_state_rescan_btn = Button.new() + _mixed_state_rescan_btn.text = "Re-scan" + _mixed_state_rescan_btn.tooltip_text = ( + "Scan addons/godot_ai/ for *.update_backup files again." + + " Click after restoring the addon manually to dismiss this banner." + ) + _mixed_state_rescan_btn.pressed.connect(func(): _refresh_mixed_state_banner(true)) + _mixed_state_banner.add_child(_mixed_state_rescan_btn) + + _mixed_state_banner.add_child(HSeparator.new()) + _body.add_child(_mixed_state_banner) + + +func _refresh_mixed_state_banner(force: bool = false) -> void: + ## Re-scan button passes `force=true` to bypass the scanner's TTL + ## cache so a manual fix is reflected immediately. + _apply_mixed_state_banner_diagnostic(UpdateMixedStateScript.diagnose( + UpdateMixedStateScript.ADDON_DIR, force + )) + + +## Render seam exposed for testing — the GDScript test suite drives this +## directly with synthetic diagnostics so dock banner contracts can be +## pinned without polluting the real `addons/godot_ai/` tree with backup +## files. Callers from production go through `_refresh_mixed_state_banner`. +func _apply_mixed_state_banner_diagnostic(diag: Dictionary) -> void: + if _mixed_state_banner == null: + return + if diag.is_empty(): + _mixed_state_banner.visible = false + return + _mixed_state_banner.visible = true + ## `Dictionary.get(...)` returns Variant; Label.text is typed String. + ## Explicit cast keeps the type contract honest and dodges some Godot + ## 4.x point-release quirks around Variant→typed-property assignment. + _mixed_state_label.text = String(diag.get("message", "")) + _mixed_state_files.clear() + for path in diag.get("backup_files", []): + _mixed_state_files.add_text(String(path)) + _mixed_state_files.newline() + if bool(diag.get("truncated", false)): + _mixed_state_files.add_text( + "… (list truncated at %d entries)" % UpdateMixedStateScript.MAX_BACKUP_RESULTS + ) + _mixed_state_files.newline() + + +## Signal handler for the extracted LogViewer — the panel owns its own +## display visibility, the dock owns logging routing. Routes to BOTH the +## dispatcher (gates [recv]/[send] recording) and the log buffer's console +## echo — the connection logs [event]/[defer] lines directly to the buffer, +## bypassing the dispatcher, so gating only `mcp_logging` left the console +## spamming with the toggle off (#626). Ring recording is unaffected, so +## the dock's log panel keeps working while the console stays quiet. +func _on_log_logging_enabled_changed(enabled: bool) -> void: + if _connection and _connection.dispatcher: + _connection.dispatcher.mcp_logging = enabled + if _log_buffer != null: + _log_buffer.enabled = enabled + + +## Signal handler for the extracted PortPickerPanel — the panel range-validates +## the spinbox value before emitting, so we just write the EditorSetting and +## reload the plugin here. +func _on_port_apply_requested(new_port: int) -> void: + var es := EditorInterface.get_editor_settings() + if es != null: + es.set_setting(McpSettings.SETTING_HTTP_PORT, new_port) + ## Every saved client config now points at the old port. Re-sweep so the + ## drift banner appears in the same frame the user committed the change — + ## the plugin reload below will run a second sweep on its own first paint, + ## but we want the banner up immediately rather than after the reload + ## handshake races to completion. See #166. + _refresh_all_client_statuses() + ## Reload after the setting is committed so `_start_server` reads the new + ## port on the re-enabled plugin instance. + _on_reload_plugin() + + +func _refresh_server_label(server_status: Dictionary = {}) -> void: + if _server_label == null: + return + var ws_port := ClientConfigurator.ws_port() + if _plugin != null and _plugin.has_method("get_resolved_ws_port"): + ws_port = int(_plugin.get_resolved_ws_port()) + var text := "WS: %d HTTP: %d" % [ws_port, ClientConfigurator.http_port()] + if server_status.is_empty() and _plugin != null and _plugin.has_method("get_server_status"): + server_status = _plugin.get_server_status() + if _plugin != null and _plugin.has_method("get_server_pid"): + var ownership := _server_ownership_tag( + int(server_status.get("state", ServerStateScript.UNINITIALIZED)), + int(_plugin.get_server_pid()), + ) + if not ownership.is_empty(): + text += " · %s" % ownership + _server_label.text = text + + +## #838/#816 step 11: name which backend flavor the editor is riding. +## Diagnostic display only — never kill proof (external adoption clears PID +## authority, see server_lifecycle.gd::adopt_compatible_server / #669). +static func _server_ownership_tag(state: int, server_pid: int) -> String: + if state != ServerStateScript.READY: + return "" + return "plugin-managed backend" if server_pid > 0 else "externally adopted backend" + + +## "attach" when Configure writes a client-owned launch command for this +## client, "URL" when it writes the client's native URL entry. Derived from +## descriptor data so the tag can never disagree with what Configure does. +static func _client_transport_tag(client_id: String) -> String: + var client := ClientRegistry.get_by_id(client_id) + if client == null: + return "" + return "URL" if client.command_shape == Client.CommandShape.NONE else "attach" + + +# --- Telemetry setting persistence --- + + +## Returns true if GODOT_AI_DISABLE_TELEMETRY or DISABLE_TELEMETRY is set +## to a truthy value, false if either is set and non-truthy, null if neither +## env var is present at all. +func _is_telemetry_disabled_via_env() -> Variant: + if not (OS.has_environment("GODOT_AI_DISABLE_TELEMETRY") or OS.has_environment("DISABLE_TELEMETRY")): + return null + return McpSettings.env_truthy("GODOT_AI_DISABLE_TELEMETRY") or McpSettings.env_truthy("DISABLE_TELEMETRY") + + +## Reads the telemetry preference, applying env-var override when present. +## Initialises _telemetry_pending_enabled / _telemetry_saved_enabled and +## sets the checkbox state + locked tooltip. Call after _telemetry_toggle +## has been created. +func _load_telemetry_setting() -> void: + var es := EditorInterface.get_editor_settings() + var env_disabled = _is_telemetry_disabled_via_env() + + var enabled: bool + if env_disabled != null: + ## Env var present: resolve and save to EditorSettings so future sessions without + ## the env var honour the last-set value. + enabled = not bool(env_disabled) + if es != null: + es.set_setting(McpSettings.SETTING_TELEMETRY_ENABLED, enabled) + else: + ## No env var: read (or create) the EditorSettings key. + if es != null and es.has_setting(McpSettings.SETTING_TELEMETRY_ENABLED): + enabled = bool(es.get_setting(McpSettings.SETTING_TELEMETRY_ENABLED)) + else: + enabled = true + if es != null: + es.set_setting(McpSettings.SETTING_TELEMETRY_ENABLED, true) + + _telemetry_pending_enabled = enabled + _telemetry_saved_enabled = enabled + + if _telemetry_toggle == null: + return + _telemetry_toggle.set_pressed_no_signal(enabled) + if env_disabled != null: + _telemetry_toggle.disabled = true + _telemetry_toggle.tooltip_text = ( + "Telemetry is controlled by an environment variable " + + "(GODOT_AI_DISABLE_TELEMETRY / DISABLE_TELEMETRY)." + ) + else: + _telemetry_toggle.disabled = false + _telemetry_toggle.tooltip_text = "" + + +func _on_telemetry_toggled(pressed: bool) -> void: + _telemetry_pending_enabled = pressed + _refresh_tools_ui_state() + + +# --- Dev mode persistence --- + + +func _load_dev_mode() -> bool: + # Default OFF for every install (including dev checkouts). Contributors + # who want the extra diagnostic UI (Reload Plugin, MCP log + # panel, Start/Stop Dev Server) can flip the toggle once — editor + # settings persist across sessions. + var es := EditorInterface.get_editor_settings() + if es == null: + return false + if not es.has_setting(DEV_MODE_SETTING): + es.set_setting(DEV_MODE_SETTING, false) + return false + return bool(es.get_setting(DEV_MODE_SETTING)) + + +func _on_dev_mode_toggled(enabled: bool) -> void: + var es := EditorInterface.get_editor_settings() + if es != null: + es.set_setting(DEV_MODE_SETTING, enabled) + _apply_dev_mode_visibility() + _refresh_setup_status() + + +func _apply_dev_mode_visibility() -> void: + if _dev_mode_toggle == null: + return ## dock UI not built yet (unit tests, teardown window) + var dev := _dev_mode_toggle.button_pressed + _dev_section.visible = dev + if _log_viewer != null: + _log_viewer.visible = dev + # Setup section: visible in dev mode, OR in user mode when uv is missing + # (so users can install uv from the dock) — but not while the server + # launch is still settling (#744): mid-launch a red "uv: not found" row + # is usually a transient probe failure (#739) or irrelevant because the + # launch is succeeding via the .venv or system tiers. `_update_status` + # re-applies visibility on every status transition, so the section + # appears the moment the launch outcome makes it relevant. + var is_dev := ClientConfigurator.is_dev_checkout() + var uv_missing := not is_dev and ClientConfigurator.check_uv_version().is_empty() + _setup_section.visible = _setup_section_should_show(dev, uv_missing, _server_launch_pending()) + + +## Pure visibility decision for the Setup section (#744). Split out so the +## truth table is unit-testable without faking the uv probe or a dev +## checkout: dev toggle always shows the section; a missing uv only shows +## it once the server launch has settled. +static func _setup_section_should_show( + dev_toggle: bool, uv_missing: bool, launch_pending: bool +) -> bool: + return dev_toggle or (uv_missing and not launch_pending) + + +## True while the server launch outcome is still unknown: not connected, +## no terminal diagnosis yet, and the startup grace window ("Starting +## server…" in the status row) is still running. Mirrors the status-label +## logic in `_update_status` so the Setup section and the amber status +## text agree on what "still launching" means. +func _server_launch_pending() -> bool: + if _last_connected: + return false + var server_status: Dictionary = ( + _plugin.get_server_status() + if _plugin != null and _plugin.has_method("get_server_status") + else {} + ) + var state: int = int(server_status.get("state", ServerStateScript.UNINITIALIZED)) + if ServerStateScript.is_terminal_diagnosis(state): + return false + return Time.get_ticks_msec() < _startup_grace_until_msec + + +# --- Button handlers --- + + +func _do_plugin_reload() -> void: + EditorInterface.set_plugin_enabled("res://addons/godot_ai/plugin.cfg", false) + EditorInterface.set_plugin_enabled("res://addons/godot_ai/plugin.cfg", true) + + +func _on_reload_plugin() -> void: + # Persist a pending plugin_reload telemetry event *before* the + # disable kills the live WebSocket — the new plugin's _enter_tree + # flushes it via `_telemetry.flush_pending_plugin_reload()`. + Telemetry.record_pending_plugin_reload("dock_button") + # Defer the toggle so any in-flight input event finishes propagating + # before the dock (and its Window children) leave the tree. Calling + # set_plugin_enabled synchronously from a button press frees the + # viewport mid-dispatch. + _do_plugin_reload.call_deferred() + + +## Setup-section "Server" row: always report the TRUE running server +## version (from the handshake_ack) rather than the plugin's expected +## version, and highlight the mismatch so self-update drift is visible +## at a glance instead of silently masked by a green label. +## +## Render states, keyed off live version metadata: +## - empty (pre-ack): show the expected version only as an unverified target +## - matches plugin: show it green, no Restart button +## - dev mismatch: show amber with an explicit dev marker +## - release mismatch: show actual vs expected; only surface Restart when the +## plugin has ownership proof for the process +func _refresh_server_version_label(server_status: Dictionary = {}) -> void: + if _setup_server_label == null: + return + var plugin_ver := ClientConfigurator.get_plugin_version() + if server_status.is_empty(): + ## Re-fetch only when called outside `_update_status`'s frame + ## (e.g. from `_apply_new_port`, `_on_restart_*`). Inside the + ## per-frame loop, the caller threads its cached snapshot through + ## so we don't allocate a fresh Dictionary every frame. + server_status = ( + _plugin.get_server_status() + if _plugin != null and _plugin.has_method("get_server_status") + else {} + ) + var server_ver: String = _connection.server_version if _connection != null else "" + if server_ver.is_empty(): + server_ver = str(server_status.get("actual_version", "")) + var expected_ver := str(server_status.get("expected_version", "")) + if expected_ver.is_empty(): + expected_ver = plugin_ver + var state: int = int(server_status.get("state", ServerStateScript.UNINITIALIZED)) + if _server_restart_in_progress and ( + server_ver == expected_ver + or ( + ServerStateScript.is_terminal_diagnosis(state) + and state != ServerStateScript.INCOMPATIBLE + ) + ): + _server_restart_in_progress = false + var text: String + var color: Color + var show_restart := false + if _server_restart_in_progress: + text = "restarting server..." + color = COLOR_AMBER + show_restart = true + elif server_ver.is_empty(): + text = "checking live version (expected godot-ai == %s)" % expected_ver + color = COLOR_MUTED + elif server_ver == expected_ver: + text = "godot-ai == %s" % server_ver + color = Color.GREEN + else: + text = "godot-ai == %s (expected %s)" % [server_ver, expected_ver] + var is_incompatible: bool = state == ServerStateScript.INCOMPATIBLE + color = Color.RED if is_incompatible else COLOR_AMBER + var has_managed_proof: bool = ( + _plugin != null + and _plugin.has_method("can_restart_managed_server") + and _plugin.can_restart_managed_server() + ) + var can_recover: bool = bool(server_status.get("can_recover_incompatible", false)) + show_restart = ( + (not is_incompatible and has_managed_proof) + ## Recoverable incompatible servers get the primary action in + ## the top error panel. Duplicating it in Setup made the UI + ## look like it had multiple restart paths. + or (is_incompatible and can_recover and _crash_restart_btn == null) + ) + if text == _last_rendered_server_text: + _setup_server_label.add_theme_color_override("font_color", color) + _update_restart_button(show_restart) + return + _last_rendered_server_text = text + _setup_server_label.text = text + _setup_server_label.add_theme_color_override("font_color", color) + _update_restart_button(show_restart) + + +func _update_restart_button(visible: bool) -> void: + if _version_restart_btn != null: + _version_restart_btn.visible = visible + _version_restart_btn.disabled = _server_restart_in_progress + _version_restart_btn.text = "Restarting..." if _server_restart_in_progress else "Restart" + if _crash_restart_btn != null: + _crash_restart_btn.disabled = _server_restart_in_progress + _crash_restart_btn.text = "Restarting..." if _server_restart_in_progress else "Restart Server" + + +func _on_restart_stale_server() -> void: + if _plugin == null or _server_restart_in_progress: + return + _server_restart_in_progress = true + _last_rendered_server_text = "" + _refresh_server_version_label() + if not is_inside_tree(): + await _dispatch_stale_server_restart() + _server_restart_in_progress = false + _last_rendered_server_text = "" + _refresh_server_version_label() + return + call_deferred("_restart_stale_server_after_feedback") + + +func _restart_stale_server_after_feedback() -> void: + await get_tree().create_timer(0.15).timeout + if not await _dispatch_stale_server_restart(): + _server_restart_in_progress = false + _last_rendered_server_text = "" + _refresh_server_version_label() + + +func _dispatch_stale_server_restart() -> bool: + if _plugin == null: + return false + var status: Dictionary = ( + _plugin.get_server_status() + if _plugin.has_method("get_server_status") + else {} + ) + if int(status.get("state", ServerStateScript.UNINITIALIZED)) == ServerStateScript.INCOMPATIBLE: + if _plugin.has_method("recover_incompatible_server"): + ## Coroutine in production (#678): recovery reports success only + ## after the respawn walk completes and the connection unblocks. + return bool(await _plugin.recover_incompatible_server()) + elif _plugin.has_method("force_restart_server"): + _plugin.force_restart_server() + return true + return false + + +# --- Setup section --- + +## #739: a `uvx --version` probe that failed once at editor startup used +## to pin "uv: not found" for the whole session — the Install-uv click +## was the only invalidation path, so the fix users discovered was +## re-clicking Install on every launch. Re-probe on events that suggest +## the failure was transient (server-connect transition, manual Refresh). +## No-op once uv has been found, so this costs nothing in the healthy +## steady state; when uv is genuinely absent, the re-probe is a fast +## negative (CliFinder's well-known-dir walk plus one bounded `where`). +## Runs on the main thread like the initial probe — same wall-clock +## bound, and the triggering events are rare (once per connect / click). +## +## Callers go through _schedule_uv_reprobe() rather than calling this +## inline: the cache-miss probe shells out (bounded at 3s) on the +## calling thread, and both call sites sit mid-flow in UI handlers — +## the connect transition wants its status-label writes committed +## first, and the Refresh click wants the client sweep dispatched +## without waiting on the probe. Same deferred convention as +## _on_install_uv. (The deferred queue still flushes on the main +## thread, so a worst-case 3s probe delays that frame — acceptable for +## a rare, bounded event; a worker thread would be the heavier cure.) +func _schedule_uv_reprobe() -> void: + _reprobe_uv_if_negative.call_deferred() + + +func _reprobe_uv_if_negative() -> void: + if not ClientConfigurator.uv_probe_negative(): + return + ClientConfigurator.invalidate_uv_detection() + _refresh_setup_status() + _apply_dev_mode_visibility() + + +func _refresh_setup_status() -> void: + if _setup_container == null: + return + for child in _setup_container.get_children(): + child.queue_free() + _dev_primary_btn = null + _dev_stop_btn = null + + var is_dev := ClientConfigurator.is_dev_checkout() + if is_dev: + _setup_container.add_child(_make_status_row("Mode", "Dev (venv)", Color.CYAN)) + + var btn_row := HBoxContainer.new() + btn_row.add_theme_constant_override("separation", 4) + btn_row.size_flags_horizontal = Control.SIZE_EXPAND_FILL + + _dev_primary_btn = Button.new() + _dev_primary_btn.text = "Restart Dev Server" + _dev_primary_btn.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _dev_primary_btn.pressed.connect(_on_dev_primary_pressed) + btn_row.add_child(_dev_primary_btn) + + _dev_stop_btn = Button.new() + _dev_stop_btn.text = "✕" + _dev_stop_btn.tooltip_text = "Stop the dev server without spawning a replacement." + _dev_stop_btn.pressed.connect(_on_dev_stop_pressed) + btn_row.add_child(_dev_stop_btn) + + _setup_container.add_child(btn_row) + _update_dev_section_buttons() + return + + # User mode — check for uv + var uv_version := ClientConfigurator.check_uv_version() + if not uv_version.is_empty(): + var compact_uv_version := _compact_uv_version_text(uv_version) + var uv_tooltip := uv_version if compact_uv_version != uv_version else "" + _setup_container.add_child(_make_status_row("uv", compact_uv_version, Color.GREEN, uv_tooltip)) + ## Build the Server row with a placeholder label we can update every + ## frame. `_refresh_server_version_label` replaces the text + color + ## once `McpConnection.server_version` lands via `handshake_ack`, and + ## flips to amber + "(plugin X)" on drift. Pre-ack we show the + ## plugin's expected version so the row isn't blank. + var server_row := HBoxContainer.new() + server_row.add_theme_constant_override("separation", 8) + var key_label := Label.new() + key_label.text = "Server" + key_label.add_theme_color_override("font_color", COLOR_MUTED) + key_label.custom_minimum_size = Vector2(60, 0) + server_row.add_child(key_label) + _setup_server_label = Label.new() + _setup_server_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + server_row.add_child(_setup_server_label) + _version_restart_btn = Button.new() + _version_restart_btn.text = "Restart" + _version_restart_btn.tooltip_text = "Kill the server on port %d and respawn with the plugin's bundled version" % ClientConfigurator.http_port() + _version_restart_btn.pressed.connect(_on_restart_stale_server) + _version_restart_btn.visible = false + server_row.add_child(_version_restart_btn) + _setup_container.add_child(server_row) + _last_rendered_server_text = "" + _refresh_server_version_label() + else: + _setup_container.add_child(_make_status_row("uv", "not found", Color.RED)) + var install_btn := Button.new() + install_btn.text = "How to install uv" + install_btn.tooltip_text = ( + "Opens the official uv installation docs. Godot AI deliberately does " + + "not run the installer for you — see _on_install_uv." + ) + install_btn.pressed.connect(_on_install_uv) + _setup_container.add_child(install_btn) + + +func _install_mode_text() -> String: + if ClientConfigurator.is_dev_checkout(): + return "Install: dev checkout — update via git pull" + return "Install: v%s" % ClientConfigurator.get_plugin_version() + + +func _install_mode_tooltip() -> String: + if not ClientConfigurator.is_dev_checkout(): + return "Plugin installed from a release ZIP, Asset Library, or source copy. Update button in this dock downloads the latest GitHub release." + var target := _resolve_plugin_symlink_target() + if target.is_empty(): + return "Plugin source tree resolved via local .venv — press Reload Plugin after editing." + return "Plugin source: %s\nPress Reload Plugin after editing." % target + + +func _resolve_plugin_symlink_target() -> String: + var logical := ProjectSettings.globalize_path("res://addons/godot_ai").rstrip("/").rstrip("\\") + var resolved := ClientConfigurator.resolve_addons_realpath() + if resolved.is_empty() or resolved == logical: + return "" + return resolved + + +static func _compact_uv_version_text(uv_version: String) -> String: + var text := uv_version.strip_edges() + if text.ends_with(")"): + var metadata_start := text.rfind(" (") + if metadata_start >= 0: + return text.substr(0, metadata_start).strip_edges() + return text + + +func _make_status_row( + label_text: String, + value_text: String, + value_color: Color, + tooltip_text: String = "" +) -> HBoxContainer: + var row := HBoxContainer.new() + row.add_theme_constant_override("separation", 6) + if not tooltip_text.is_empty(): + row.tooltip_text = tooltip_text + + var label := Label.new() + label.text = label_text + label.add_theme_color_override("font_color", COLOR_MUTED) + label.custom_minimum_size.x = 60 + if not tooltip_text.is_empty(): + label.tooltip_text = tooltip_text + row.add_child(label) + + var value := Label.new() + value.text = value_text + value.add_theme_color_override("font_color", value_color) + if not tooltip_text.is_empty(): + value.tooltip_text = tooltip_text + row.add_child(value) + + return row + + +## Pure helper for the primary "Restart Dev Server" button. Always enabled +## (clicking with nothing running just spawns fresh); tooltip adapts to +## whether a kill+respawn or fresh spawn is what'll happen. +static func _dev_primary_btn_state(has_managed: bool, dev_running: bool) -> Dictionary: + var port := ClientConfigurator.http_port() + if has_managed or dev_running: + return { + "text": "Restart Dev Server", + "tooltip": ( + "Kill the server on port %d and start a fresh --reload dev server. " + + "Use this to pick up Python source changes that don't bump the version." + ) % port, + } + return { + "text": "Start Dev Server", + "tooltip": "Spawn a --reload dev server on port %d. Auto-restarts when you edit Python sources." % port, + } + + +## Pure helper for the small "✕" stop button — only enabled when a dev +## server is actually running. Stops without respawning; intentionally +## never targets a managed server (that's the lifecycle's responsibility). +static func _dev_stop_btn_state(dev_running: bool) -> Dictionary: + if dev_running: + return {"enabled": true, "tooltip": "Stop the dev server without spawning a replacement."} + return {"enabled": false, "tooltip": "No --reload dev server to stop."} + + +func _on_dev_primary_pressed() -> void: + if _plugin == null or _server_restart_in_progress: + return + if not _plugin.has_method("force_restart_or_start_dev_server"): + return + if _plugin.has_method("record_dev_server_toggle"): + _plugin.record_dev_server_toggle("start") + _server_restart_in_progress = true + _update_dev_section_buttons() + if not is_inside_tree(): + ## Test path — no scene tree means no timer; run synchronously + ## so suite assertions see the dispatch without `await`. + _plugin.force_restart_or_start_dev_server() + _server_restart_in_progress = false + return + call_deferred("_perform_dev_restart_after_feedback") + + +func _on_dev_stop_pressed() -> void: + if _plugin == null: + return + if _plugin.has_method("stop_dev_server"): + _plugin.stop_dev_server() + if _plugin.has_method("record_dev_server_toggle"): + _plugin.record_dev_server_toggle("stop") + _update_dev_section_buttons.call_deferred() + + +func _perform_dev_restart_after_feedback() -> void: + ## Brief paint cycle so the user sees "Restarting..." before the + ## blocking _wait_for_port_free freezes the editor for up to 5s. + await get_tree().create_timer(0.15).timeout + ## Re-check has_method post-await — a self-update mixed-state window + ## could swap _plugin's script class while we were sleeping, leaving + ## the old reference pointing at a class that no longer carries the + ## new method. Same #168 guard pattern as _update_dev_section_buttons. + if _plugin != null and _plugin.has_method("force_restart_or_start_dev_server"): + _plugin.force_restart_or_start_dev_server() + ## start_dev_server's spawn happens via a 0.5s SceneTree timer; give + ## it time to land plus a buffer for the WS reconnect before clearing + ## the busy state. The unconditional clear matches sibling restart + ## buttons — overshoot is fine because subsequent _update_status calls + ## refresh the button against live plugin state. + await get_tree().create_timer(2.0).timeout + _server_restart_in_progress = false + _update_dev_section_buttons() + + +## Single-scan refresh of every dev-section button state. Both buttons +## key off the same `has_managed_server` / `is_dev_server_running` pair, +## and the latter scrapes lsof/ps — so doing the discovery once and +## applying to both avoids the duplicate subprocess fork on every +## connection-state transition. +func _update_dev_section_buttons() -> void: + if _plugin == null: + return + if not (_plugin.has_method("has_managed_server") and _plugin.has_method("is_dev_server_running")): + return + var has_managed: bool = _plugin.has_managed_server() + var dev_running: bool = _plugin.is_dev_server_running() + if _dev_primary_btn != null: + if _server_restart_in_progress: + _dev_primary_btn.disabled = true + _dev_primary_btn.text = "Restarting..." + _dev_primary_btn.tooltip_text = "Killing the current server and respawning..." + else: + var primary_state := _dev_primary_btn_state(has_managed, dev_running) + _dev_primary_btn.disabled = false + _dev_primary_btn.text = primary_state["text"] + _dev_primary_btn.tooltip_text = primary_state["tooltip"] + if _dev_stop_btn != null: + var stop_state := _dev_stop_btn_state(dev_running) + _dev_stop_btn.disabled = (not stop_state["enabled"]) or _server_restart_in_progress + _dev_stop_btn.tooltip_text = stop_state["tooltip"] + + +func _client_status_refresh_has_completed() -> bool: + return _last_client_status_refresh_completed_msec > 0 + + +func _connected_status_text() -> String: + return "Server connected" + + +static func _transport_status_text(snapshot: Dictionary) -> String: + ## Total over the transport enum for isolated consumers/tests. The dock's + ## connected fast path renders `_connected_status_text()` before calling it. + var phase := str(snapshot.get("phase", "")) + var attempt := maxi(1, int(snapshot.get("attempt", 0))) + match phase: + "connected": + return "Server connected" + "connecting": + return "Connecting — attempt %d" % attempt + "retrying": + var retry_in_sec := ceili(maxf(0.0, float(snapshot.get("retry_in_sec", 0.0)))) + return "Retrying in %ds — attempt %d" % [retry_in_sec, attempt] + "closing": + return "Disconnecting…" + "blocked": + return "Connection blocked" + return "Disconnected" + + +## Open uv's official install documentation rather than executing an +## installer on the user's behalf. +## +## This used to shell out to `curl -LsSf https://astral.sh/uv/install.sh | sh` +## (and the PowerShell `irm … | iex` equivalent). That is arbitrary remote +## code execution as the editor user, one dock click deep, with no version +## pin, no checksum, and no signature — while this same plugin verifies its +## OWN updates with an RSA-4096 signature over a SHA-256 sidecar, pinned to a +## GitHub host and this repo's release-asset path. Holding a third-party +## installer to a weaker standard than our own payload is the wrong trade, +## and pinning a digest here would only cover the bootstrap script, not the +## uv binary it goes on to fetch. +## +## Opening the docs keeps the discovery value of the button (the user still +## learns uv is missing and how to get it) while leaving the decision to +## install — and the choice of install method — with the user. Mirrors the +## dock's existing "Run this manually" fallback for client CLIs. +func _on_install_uv() -> void: + OS.shell_open(UV_INSTALL_DOCS_URL) + ## Drop the cached uvx path AND the cached `uvx --version` so that once + ## the user has installed uv (in a terminal, from the docs we just + ## opened), the dock finds the new binary instead of replaying the + ## cached "not found" result for the rest of the session. + ## Routing through the configurator matters on Windows, where the + ## CLI-finder cache key is `uvx.exe` — invalidating just `"uvx"` + ## would leave the cache stale and the dock would keep showing + ## "uv: not found" for the rest of the session. + ClientConfigurator.invalidate_uv_detection() + ## Deliberately do NOT refresh here. `OS.shell_open` returns as soon as + ## the browser is handed the URL, so an immediate refresh would run long + ## before the user could install anything and would simply re-cache + ## "not found" — undoing the invalidation above. (The old shell-out was + ## a blocking `OS.execute`, so refreshing straight after it was correct + ## then; it stopped being correct when the installer call went away.) + ## Re-probe when the editor regains focus instead — see _notification. + _uv_recheck_pending = true + + +# --- Client section --- + +func _on_configure_client(client_id: String) -> void: + if _server_blocks_client_health(): + _apply_row_status(client_id, Client.Status.ERROR, _server_blocked_client_message()) + _refresh_clients_summary() + return + _dispatch_client_action(client_id, "configure") + + +func _on_remove_client(client_id: String) -> void: + _dispatch_client_action(client_id, "remove") + + +## Spawn a worker thread for Configure / Remove so a hung CLI can't lock +## the editor (issue #239). The action verbs are: "configure" → calls +## `ClientConfigurator.configure`; "remove" → calls +## `ClientConfigurator.remove`. Both routes shell out to the per-client +## CLI via `McpCliExec.run`, which is wall-clock-bounded. +## +## Per-row in-flight rules: +## - One worker at a time per client (the row's slot). +## - Both buttons disabled while the slot is busy — prevents a +## double-click queueing a stale Configure on top of a still-running +## Remove. +## - The dot turns amber and the row label gets a "Configuring…" / +## "Removing…" suffix so the user can see the click was registered. +func _dispatch_client_action(client_id: String, action: String) -> void: + if _is_self_update_in_progress(): + ## Same gate as the refresh worker — the install window overwrites + ## plugin scripts on disk, and a worker mid-call into them would + ## SIGABRT in `GDScriptFunction::call`. See `_update_manager`. + return + if _client_action_threads.has(client_id): + return + ## An abandoned-but-still-running worker owns this row's config file just + ## as much as a tracked one does. Defensive: `_abandon_client_action_thread` + ## already leaves the buttons disabled in that state. + if _has_live_orphan(client_id): + return + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + + ## Drop any phase left behind by a previous action on this row — a + ## generation-mismatch or shutdown return can skip the normal finalize, + ## and a stale phase would suppress the label for this new action. + _clear_client_action_phase(client_id) + _set_client_action_cancel_requested(client_id, false) + _set_row_action_in_flight(client_id, action) + ## Snapshot `server_url` on main: `http_url()` reads + ## `EditorInterface.get_editor_settings()`, which is main-thread-only. + ## The status-refresh worker uses the same pattern — see + ## `_perform_initial_client_status_refresh` and + ## `_request_client_status_refresh`. + var launch_context := ClientConfigurator.capture_launch_context() + var server_url := ClientConfigurator.server_url_from(launch_context) + ## #691: refresh the env snapshot on main before this worker starts — + ## configure/remove resolve CLI + config paths off-thread and must not + ## race a concurrent spawn window's setenv/unsetenv. + ClientConfigurator.warm_env_snapshot() + var generation := int(_client_action_generations.get(client_id, 0)) + 1 + _client_action_generations[client_id] = generation + var thread := Thread.new() + _client_action_threads[client_id] = thread + _client_action_started_msec[client_id] = Time.get_ticks_msec() + _client_action_names[client_id] = action + var err := thread.start( + Callable(self, "_run_client_action_worker").bind( + client_id, action, server_url, launch_context, generation + ) + ) + if err != OK: + _client_action_threads.erase(client_id) + _client_action_started_msec.erase(client_id) + _client_action_names.erase(client_id) + _finalize_action_buttons(client_id) + _apply_row_status(client_id, Client.Status.ERROR, "couldn't start worker thread") + _refresh_clients_summary() + + +func _run_client_action_worker( + client_id: String, + action: String, + server_url: String, + launch_context: Dictionary, + generation: int, +) -> Dictionary: + var result: Dictionary + var prewarm: Dictionary = {} + if action == "remove": + result = ClientConfigurator.remove(client_id, server_url, launch_context) + else: + result = ClientConfigurator.configure(client_id, server_url, launch_context) + ## #851: the entry we just wrote pins an exact `godot-ai==X`. If uv has + ## never built that environment, the FIRST client spawn builds it — + ## ~67 packages — which is what flashes a terminal window on Windows + ## and what can push a bridge spawn past the MCP client's default 30s + ## connect timeout, so the tools appear to vanish. Pay that cost here, + ## on a deliberate click the dock can label, instead of on the client's + ## critical path. + ## + ## Best-effort: the config file is already written and correct. A + ## failed or timed-out warm only means the next launch pays the cold + ## cost it always used to, so `result` is deliberately left untouched. + if result.get("status") == "ok": + _set_client_action_phase(client_id, _PHASE_PREWARM) + prewarm = ClientConfigurator.prewarm_attach_launch( + launch_context, + ClientConfigurator.PREWARM_TIMEOUT_MS, + {}, + Callable(self, "_is_client_action_cancel_requested").bind(client_id), + ) + return { + "client_id": client_id, + "action": action, + "result": result, + "prewarm": prewarm, + "generation": generation, + } + + +func _poll_completed_client_action_threads() -> void: + for client_id in _client_action_threads.keys(): + var thread: Thread = _client_action_threads[client_id] + if thread == null: + continue + if thread.is_alive(): + _apply_client_action_phase(String(client_id)) + continue + var payload: Variant = thread.wait_to_finish() + _client_action_threads[client_id] = null + if payload is Dictionary: + var data := payload as Dictionary + var result: Dictionary = data.get("result", {}) + _report_prewarm_outcome( + String(data.get("client_id", client_id)), data.get("prewarm", {}) + ) + _apply_client_action_result( + String(data.get("client_id", client_id)), + String(data.get("action", _client_action_names.get(client_id, "configure"))), + result, + int(data.get("generation", _client_action_generations.get(client_id, 0))) + ) + else: + _apply_client_action_result( + String(client_id), + String(_client_action_names.get(client_id, "configure")), + {"status": "error", "message": "worker returned no result"}, + int(_client_action_generations.get(client_id, 0)) + ) + + +func _apply_client_action_result(client_id: String, action: String, result: Dictionary, generation: int) -> void: + if int(_client_action_generations.get(client_id, 0)) != generation: + if _client_action_threads.get(client_id, null) == null: + _client_action_threads.erase(client_id) + _client_action_started_msec.erase(client_id) + _client_action_names.erase(client_id) + return + if _refresh_state == ClientRefreshStateScript.SHUTTING_DOWN: + return + if _client_action_threads.has(client_id): + var t: Thread = _client_action_threads[client_id] + if t != null: + t.wait_to_finish() + _client_action_threads.erase(client_id) + _client_action_started_msec.erase(client_id) + _client_action_names.erase(client_id) + _clear_client_action_phase(client_id) + _finalize_action_buttons(client_id) + if _server_blocks_client_health(): + _apply_row_status(client_id, Client.Status.ERROR, _server_blocked_client_message()) + _refresh_clients_summary() + return + + var success_status := Client.Status.NOT_CONFIGURED if action == "remove" else Client.Status.CONFIGURED + if result.get("status") == "ok": + ## #877: Remove targets only the selected scope, so a configure is the + ## only action with an all-scope sweep to disclose. The manual panel + ## that lists those removes is shown on the failure path below, which + ## left the success path — where the sweep actually ran — silent. + var sweep_note := ( + ClientConfigurator.configure_sweep_note(client_id) if action == "configure" else "" + ) + _apply_row_status(client_id, success_status, sweep_note) + var row: Dictionary = _client_rows.get(client_id, {}) + if not row.is_empty(): + (row["manual_panel"] as VBoxContainer).visible = false + else: + _apply_row_status(client_id, Client.Status.ERROR, str(result.get("message", "failed"))) + if action == "configure": + _show_manual_command_for(client_id) + _refresh_clients_summary() + + +## Phase label for the Configure worker's pre-warm step. The config write +## itself is fast; building the pinned uv environment is the part that can +## run for tens of seconds, so it gets its own label rather than sitting +## under a motionless "Configuring…". +const _PHASE_PREWARM := "prewarm" + +## Worker-written, main-read. `Dictionary` writes are not atomic across +## threads, so both sides take the mutex — the same discipline `CliFinder` +## uses for its cache. Held only across the dictionary access, never across +## the subprocess, so the main thread can never block on uv. +var _client_action_phase_mutex := Mutex.new() +var _client_action_phases: Dictionary = {} +## Rows whose button text already reflects their phase, so the per-frame poll +## rewrites the label once instead of on every frame. +var _client_action_phase_shown: Dictionary = {} + + +## Thread-safe cancellation state read by McpCliExec's 50ms poll loop. +func _set_client_action_cancel_requested(client_id: String, requested: bool) -> void: + _client_action_cancel_mutex.lock() + if requested: + _client_action_cancelled_clients[client_id] = true + else: + _client_action_cancelled_clients.erase(client_id) + _client_action_cancel_mutex.unlock() + + +func _is_client_action_cancel_requested(client_id: String) -> bool: + _client_action_cancel_mutex.lock() + var requested := bool(_client_action_cancelled_clients.get(client_id, false)) + _client_action_cancel_mutex.unlock() + return requested + + +func _set_client_action_phase(client_id: String, phase: String) -> void: + _client_action_phase_mutex.lock() + _client_action_phases[client_id] = phase + _client_action_phase_mutex.unlock() + + +func _read_client_action_phase(client_id: String) -> String: + _client_action_phase_mutex.lock() + var phase := String(_client_action_phases.get(client_id, "")) + _client_action_phase_mutex.unlock() + return phase + + +func _clear_client_action_phase(client_id: String) -> void: + _client_action_phase_mutex.lock() + _client_action_phases.erase(client_id) + _client_action_phase_mutex.unlock() + _client_action_phase_shown.erase(client_id) + + +## Per-frame, for a still-running worker: promote the button label when the +## worker reports it has moved on to warming the package environment. Keeps +## the dock honest about why Configure is taking a while — otherwise a cold +## uv build looks like a hang. +func _apply_client_action_phase(client_id: String) -> void: + if _read_client_action_phase(client_id) != _PHASE_PREWARM: + return + if _client_action_phase_shown.get(client_id, "") == _PHASE_PREWARM: + return + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + _client_action_phase_shown[client_id] = _PHASE_PREWARM + (row["configure_btn"] as Button).text = "Installing…" + + +## One line per Configure so a cold build is attributable after the fact — +## the dock label is transient, and #851's symptom (a terminal window on +## Windows) is easiest to correlate against a timestamped log entry. Silent +## on the skip paths: a dev-venv/system tier having no env to warm is the +## normal case, not news. +func _report_prewarm_outcome(client_id: String, prewarm: Variant) -> void: + if not (prewarm is Dictionary): + return + var data := prewarm as Dictionary + if data.is_empty() or bool(data.get("skipped", false)): + return + if bool(data.get("timed_out", false)): + print( + "MCP | %s: package pre-warm timed out; the first client launch will build the environment" + % client_id + ) + return + if int(data.get("exit_code", -1)) != 0: + print( + "MCP | %s: package pre-warm failed (exit %d); the first client launch will build the environment" + % [client_id, int(data.get("exit_code", -1))] + ) + return + print("MCP | %s: package environment pre-warmed" % client_id) + + +## In-flight visual: rewrite the verb onto the button the user just +## clicked ("Configuring…" / "Removing…") so the feedback lands where +## their attention already is. Don't pollute the row label — that'd +## clobber any drift hint ("URL out of date") still relevant to the row. +## The dot turns amber so the row reads as "busy" at a glance, not as +## green (premature success) or red (premature failure). Both buttons +## go disabled so a double-click or second action can't queue stale +## work behind the in-flight worker. +func _set_row_action_in_flight(client_id: String, action: String) -> void: + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + var configure_btn: Button = row["configure_btn"] + var remove_btn: Button = row["remove_btn"] + configure_btn.disabled = true + remove_btn.disabled = true + if action == "remove": + remove_btn.text = "Removing…" + else: + configure_btn.text = "Configuring…" + (row["dot"] as ColorRect).color = COLOR_AMBER + + +## Re-enable both buttons and reset their text back to canonical labels. +## `_apply_row_status` sets `configure_btn.text` per the resulting +## Status (Configure / Reconfigure / Retry), so we only need to reset +## `remove_btn.text` here — its sibling visibility toggle already +## handles whether to show it at all. +func _finalize_action_buttons(client_id: String) -> void: + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + (row["configure_btn"] as Button).disabled = false + var remove_btn: Button = row["remove_btn"] + remove_btn.disabled = false + remove_btn.text = "Remove" + + +func _on_refresh_clients_pressed() -> void: + ## Explicit user action — also give a failed uv probe another chance + ## (#739), mirroring how the same click already re-sweeps client CLIs. + _schedule_uv_reprobe() + _request_client_status_refresh(true) + + +func _on_configure_all_clients() -> void: + if _server_blocks_client_health(): + for client_id in _client_rows: + _apply_row_status(String(client_id), Client.Status.ERROR, _server_blocked_client_message()) + _refresh_clients_summary() + return + if ClientRefreshStateScript.should_disable_client_actions(_refresh_state): + return + for client_id in _client_rows: + var status: Client.Status = _client_rows[client_id].get("status", Client.Status.NOT_CONFIGURED) + if status == Client.Status.CONFIGURED: + continue + _on_configure_client(String(client_id)) + _refresh_clients_summary() + + +func _on_open_clients_window() -> void: + if _clients_window == null: + return + ## Re-sweep before the user has time to act on stale dot colors. The request + ## is async/stale-while-refreshing so the popup paints immediately with + ## last-known state; the fresh colors land when the background worker returns. + ## This is an explicit user action, so it bypasses the focus-in cooldown. + _request_client_status_refresh(true) + ## Also re-sync the Tools tab from the persisted setting — another + ## editor instance (or a hand-edit of editor_settings-4.tres) may have + ## changed the excluded list while the window was closed. + _reset_tools_pending_from_setting() + _refresh_tools_ui_state() + if vision_routing != null: + vision_routing.refresh_ui() + # popup_centered() with a minsize forces the window to that size and + # centers on the parent viewport. Setting .size on a hidden Window + # doesn't always take effect, so we force it at popup time here. + _clients_window.popup_centered(Vector2i(640, 600)) + + +func _settings_are_dirty() -> bool: + return ( + _tools_pending_excluded != _tools_saved_excluded + or _telemetry_pending_enabled != _telemetry_saved_enabled + or _allow_hosts_is_dirty() + ) + + +func _on_clients_window_close_requested() -> void: + if _clients_window == null: + return + ## If the user has unapplied settings, a close would silently throw the + ## pending state away. Prompt before discarding current options and if + ## they confirm, reset pending → saved so the window shows the persisted + ## state the next time they open it. + if _settings_are_dirty(): + _show_tools_close_confirm() + return + _clients_window.hide() + + +# --- Tools tab (domain exclusion) --- + +func _build_tools_tab(tabs: TabContainer) -> void: + ## Tab 2 — domain-exclusion checkboxes. Rendered once, on dock construction. + ## `_reset_tools_pending_from_setting()` re-syncs checkbox state from the + ## saved setting each time the window opens. + var tools_tab := VBoxContainer.new() + tools_tab.add_theme_constant_override("separation", 8) + var tools_margin := _build_margin_container() + tools_margin.name = "Tools" + tools_margin.add_child(tools_tab) + tabs.add_child(tools_margin) + + var intro := Label.new() + intro.text = ( + "Some MCP clients cap tools per connection (Antigravity: 100). " + + "Uncheck a domain to drop its non-core tools from this server. " + + "Core tools stay on. Changes require a server restart." + ) + intro.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + intro.add_theme_color_override("font_color", COLOR_MUTED) + intro.size_flags_horizontal = Control.SIZE_EXPAND_FILL + tools_tab.add_child(intro) + + var count_row := HBoxContainer.new() + count_row.add_theme_constant_override("separation", 8) + var count_header := Label.new() + count_header.text = "Tools Enabled:" + count_header.add_theme_color_override("font_color", COLOR_MUTED) + count_row.add_child(count_header) + _tools_count_label = Label.new() + _tools_count_label.add_theme_font_size_override("font_size", 15) + count_row.add_child(_tools_count_label) + _tools_dirty_warning = Label.new() + _tools_dirty_warning.add_theme_color_override("font_color", COLOR_AMBER) + _tools_dirty_warning.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _tools_dirty_warning.horizontal_alignment = HORIZONTAL_ALIGNMENT_RIGHT + _tools_dirty_warning.visible = false + _tools_dirty_warning.text = "Unapplied changes" + count_row.add_child(_tools_dirty_warning) + tools_tab.add_child(count_row) + + tools_tab.add_child(HSeparator.new()) + + var scroll := ScrollContainer.new() + scroll.size_flags_horizontal = Control.SIZE_EXPAND_FILL + scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL + scroll.horizontal_scroll_mode = ScrollContainer.SCROLL_MODE_DISABLED + tools_tab.add_child(scroll) + + var grid := VBoxContainer.new() + grid.add_theme_constant_override("separation", 4) + grid.size_flags_horizontal = Control.SIZE_EXPAND_FILL + scroll.add_child(grid) + + ## Core pseudo-row — disabled checkbox, always checked. Shows the 5 + ## always-loaded tools as a single line item so the user can see where + ## their baseline tool budget goes without listing individual core names + ## inline (tooltip has them). + var core_row := HBoxContainer.new() + core_row.add_theme_constant_override("separation", 8) + var core_chk := CheckBox.new() + core_chk.button_pressed = true + core_chk.disabled = true + core_chk.focus_mode = Control.FOCUS_NONE + core_row.add_child(core_chk) + var core_label := Label.new() + core_label.text = "Core (always on)" + core_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + core_row.add_child(core_label) + var core_count := Label.new() + core_count.text = "%d tools" % (ToolCatalog.CORE_TOOLS.size() + ToolCatalog.ALWAYS_ON_TOOLS.size()) + core_count.add_theme_color_override("font_color", COLOR_MUTED) + core_row.add_child(core_count) + core_row.tooltip_text = "%s · always on: %s" % [ + ", ".join(ToolCatalog.CORE_TOOLS), + ", ".join(ToolCatalog.ALWAYS_ON_TOOLS), + ] + grid.add_child(core_row) + + grid.add_child(HSeparator.new()) + + _tools_domain_checkboxes.clear() + for entry in ToolCatalog.DOMAINS: + _build_tools_domain_row(grid, entry) + + ## Custom (addon-registered) tools — unlike the domain rows above, + ## toggles apply LIVE: the registry re-pushes the filtered catalog to + ## the server on every change, no restart needed. + grid.add_child(HSeparator.new()) + var custom_header_row := HBoxContainer.new() + custom_header_row.add_theme_constant_override("separation", 8) + var custom_header := Label.new() + custom_header.text = "Custom tools (addon-registered)" + custom_header.size_flags_horizontal = Control.SIZE_EXPAND_FILL + custom_header_row.add_child(custom_header) + _custom_tools_count_label = Label.new() + _custom_tools_count_label.add_theme_color_override("font_color", COLOR_MUTED) + custom_header_row.add_child(_custom_tools_count_label) + grid.add_child(custom_header_row) + var custom_hint := Label.new() + custom_hint.text = "Applies immediately — disabled tools are hidden from agents and rejected if called." + custom_hint.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + custom_hint.add_theme_color_override("font_color", COLOR_MUTED) + custom_hint.size_flags_horizontal = Control.SIZE_EXPAND_FILL + grid.add_child(custom_hint) + _custom_tools_list = VBoxContainer.new() + _custom_tools_list.add_theme_constant_override("separation", 4) + _custom_tools_list.size_flags_horizontal = Control.SIZE_EXPAND_FILL + grid.add_child(_custom_tools_list) + _connect_custom_tool_registry() + _refresh_custom_tools_rows() + + tools_tab.add_child(HSeparator.new()) + + var telemetry_row := HBoxContainer.new() + telemetry_row.add_theme_constant_override("separation", 8) + var telemetry_label := Label.new() + telemetry_label.text = "Telemetry" + telemetry_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + telemetry_row.add_child(telemetry_label) + _telemetry_toggle = CheckButton.new() + _telemetry_toggle.toggled.connect(_on_telemetry_toggled) + telemetry_row.add_child(_telemetry_toggle) + tools_tab.add_child(telemetry_row) + + tools_tab.add_child(HSeparator.new()) + + var footer := HBoxContainer.new() + footer.add_theme_constant_override("separation", 8) + + _tools_apply_btn = Button.new() + _tools_apply_btn.text = "Apply and Restart Server" + _tools_apply_btn.tooltip_text = "Save the excluded list to Editor Settings and reload the plugin so the server respawns with --exclude-domains." + _tools_apply_btn.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _tools_apply_btn.pressed.connect(_on_tools_apply) + footer.add_child(_tools_apply_btn) + + _tools_reset_btn = Button.new() + _tools_reset_btn.text = "Reset to defaults" + _tools_reset_btn.tooltip_text = "Re-enable every domain (no --exclude-domains flag). Still needs Apply." + _tools_reset_btn.pressed.connect(_on_tools_reset) + footer.add_child(_tools_reset_btn) + + tools_tab.add_child(footer) + + _tools_close_confirm = ConfirmationDialog.new() + _tools_close_confirm.title = "Discard unapplied changes?" + ## Generic wording: _settings_are_dirty() covers domain toggles, the + ## telemetry switch, AND the Settings tab's allow-host field (#507) — + ## the old "checked/unchecked domains" text misled non-domain edits. + _tools_close_confirm.dialog_text = ( + "You have unapplied changes in this window.\n" + + "Close it and discard those changes?" + ) + _tools_close_confirm.ok_button_text = "Discard" + _tools_close_confirm.confirmed.connect(_on_tools_discard_confirmed) + add_child(_tools_close_confirm) + + _reset_tools_pending_from_setting() + _refresh_tools_ui_state() + + +## --- Custom (addon-registered) tools section --- + +func _connect_custom_tool_registry() -> void: + var registry := McpToolRegistry.get_instance() + if registry == null: + return + if not registry.tools_changed.is_connected(_on_custom_tool_registry_changed): + registry.tools_changed.connect(_on_custom_tool_registry_changed) + + +func _on_custom_tool_registry_changed() -> void: + ## Deferred: tools_changed can fire from inside a checkbox toggle in + ## this very list — rebuilding synchronously would free the emitting + ## control mid-signal. + _refresh_custom_tools_rows.call_deferred() + + +func _refresh_custom_tools_rows() -> void: + if _custom_tools_list == null or not is_instance_valid(_custom_tools_list): + return + for child in _custom_tools_list.get_children(): + child.queue_free() + var registry := McpToolRegistry.get_instance() + var specs: Array = [] if registry == null else registry.all() + specs.sort_custom(func(a, b): return String(a.name) < String(b.name)) + var enabled_count := 0 + for spec in specs: + if registry.is_tool_enabled(spec.name): + enabled_count += 1 + _custom_tools_list.add_child(_build_custom_tool_row(registry, spec)) + if _custom_tools_count_label != null and is_instance_valid(_custom_tools_count_label): + _custom_tools_count_label.text = "%d/%d enabled" % [enabled_count, specs.size()] + if specs.is_empty(): + var empty := Label.new() + empty.text = "None registered. Addons add tools via McpToolRegistry — see docs/plugin-architecture.md." + empty.add_theme_color_override("font_color", COLOR_MUTED) + empty.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + empty.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _custom_tools_list.add_child(empty) + + +func _build_custom_tool_row(registry: McpToolRegistry, spec: McpCustomToolSpec) -> HBoxContainer: + var row := HBoxContainer.new() + row.add_theme_constant_override("separation", 8) + var chk := CheckBox.new() + chk.button_pressed = registry.is_tool_enabled(spec.name) + chk.toggled.connect(func(pressed: bool): registry.set_tool_enabled(spec.name, pressed)) + row.add_child(chk) + var name_label := Label.new() + name_label.text = spec.name + (" · promoted" if spec.promoted else "") + name_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + row.add_child(name_label) + var source_label := Label.new() + source_label.text = spec.source if not spec.source.is_empty() else spec.source_path.get_base_dir().get_file() + source_label.add_theme_color_override("font_color", COLOR_MUTED) + row.add_child(source_label) + ## Tooltip = the agent-facing description plus provenance, so the user + ## can judge what they're enabling without leaving the dock. + row.tooltip_text = "%s\n\nsource: %s%s" % [ + spec.description, + spec.source_path, + "\npromoted: registers as first-class MCP tool custom_%s" % spec.name if spec.promoted else "", + ] + name_label.tooltip_text = row.tooltip_text + return row + + +func _build_tools_domain_row(parent: VBoxContainer, entry: Dictionary) -> void: + var row := HBoxContainer.new() + row.add_theme_constant_override("separation", 8) + + var chk := CheckBox.new() + chk.button_pressed = true # default; `_reset_tools_pending_from_setting` corrects + chk.toggled.connect(_on_tools_domain_toggled.bind(String(entry["id"]))) + row.add_child(chk) + + var name_label := Label.new() + name_label.text = String(entry["label"]) + name_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + row.add_child(name_label) + + var count_label := Label.new() + count_label.text = "%d tools" % int(entry["count"]) + count_label.add_theme_color_override("font_color", COLOR_MUTED) + row.add_child(count_label) + + ## Hover tooltip = flat list of tool names in this domain. Lets the + ## user decide without leaving the dock (e.g. "I just want to drop + ## `animation_preset_*` — do I lose anything else?"). + var tools_list: Array = entry.get("tools", []) + row.tooltip_text = ", ".join(tools_list) + name_label.tooltip_text = row.tooltip_text + count_label.tooltip_text = row.tooltip_text + + parent.add_child(row) + _tools_domain_checkboxes[String(entry["id"])] = chk + + +func _reset_tools_pending_from_setting() -> void: + ## Read the saved setting → pending/saved arrays, then sync checkbox state. + ## Unknown domain names in the setting (e.g. from an older plugin + ## version) are dropped from the display here (only ids with a checkbox + ## survive). The startup path is protected separately: + ## `ClientConfigurator.excluded_domains()` filters unknown names before + ## they reach `--exclude-domains`, whose `parse_exclude_list` hard-fails + ## on them. + var saved_raw := ClientConfigurator.excluded_domains() + var saved := PackedStringArray() + if not saved_raw.is_empty(): + for part in saved_raw.split(","): + var t := part.strip_edges() + if t.is_empty(): + continue + if _tools_domain_checkboxes.has(t) and saved.find(t) == -1: + saved.append(t) + saved.sort() + _tools_saved_excluded = saved + _tools_pending_excluded = saved.duplicate() + for id in _tools_domain_checkboxes: + var chk: CheckBox = _tools_domain_checkboxes[id] + ## `set_pressed_no_signal` — mutating programmatically should not + ## fire the toggled handler, which would mutate pending back. + chk.set_pressed_no_signal(_tools_pending_excluded.find(id) == -1) + ## Also reset telemetry pending state from the persisted setting. + if _telemetry_toggle != null: + _load_telemetry_setting() + ## And the Settings tab's allow-host field (#507) — same window-open / + ## discard-confirm re-sync contract as the tools checkboxes. + _reset_allow_hosts_from_setting() + + +func _on_tools_domain_toggled(pressed: bool, domain_id: String) -> void: + var idx := _tools_pending_excluded.find(domain_id) + if pressed and idx != -1: + _tools_pending_excluded.remove_at(idx) + elif not pressed and idx == -1: + _tools_pending_excluded.append(domain_id) + _tools_pending_excluded.sort() + _refresh_tools_ui_state() + + +func _refresh_tools_ui_state() -> void: + if _tools_count_label == null: + return + var enabled := ToolCatalog.enabled_tool_count(_tools_pending_excluded) + var total := ToolCatalog.total_tool_count() + _tools_count_label.text = "%d / %d" % [enabled, total] + var dirty := _settings_are_dirty() + _tools_dirty_warning.visible = dirty + _tools_apply_btn.disabled = not dirty + ## Color the count when the user is over Antigravity's cap — a soft + ## signal that their selection still won't fit. 100 is the Antigravity + ## limit; other clients may cap higher, so this is advisory only. + if enabled > 100: + _tools_count_label.add_theme_color_override("font_color", COLOR_AMBER) + else: + _tools_count_label.remove_theme_color_override("font_color") + + +func _on_tools_apply() -> void: + var canonical_excluded := ToolCatalog.canonical(_tools_pending_excluded) + var es := EditorInterface.get_editor_settings() + if es != null: + es.set_setting(McpSettings.SETTING_EXCLUDED_DOMAINS, canonical_excluded) + es.set_setting(McpSettings.SETTING_TELEMETRY_ENABLED, _telemetry_pending_enabled) + _tools_saved_excluded = _tools_pending_excluded.duplicate() + _telemetry_saved_enabled = _telemetry_pending_enabled + _refresh_tools_ui_state() + ## Plugin reload respawns the server with the new `--exclude-domains` flag + ## (see `plugin.gd::_build_server_flags`) and telemetry option. Mirrors the + ## port-change Apply flow. + _on_reload_plugin() + + +func _on_tools_reset() -> void: + ## Resets only the tool-domain exclusions, not the telemetry toggle. + ## Telemetry is a privacy preference users typically want to set once + ## and have honored — flipping it back to "on" via a generic Reset + ## button would be a surprising privacy regression. The button label + ## is scoped to tools accordingly. + _tools_pending_excluded = PackedStringArray() + for id in _tools_domain_checkboxes: + var chk: CheckBox = _tools_domain_checkboxes[id] + chk.set_pressed_no_signal(true) + _refresh_tools_ui_state() + + +func _show_tools_close_confirm() -> void: + if _tools_close_confirm == null: + return + _tools_close_confirm.popup_centered() + + +func _on_tools_discard_confirmed() -> void: + _reset_tools_pending_from_setting() + _refresh_tools_ui_state() + if _clients_window != null: + _clients_window.hide() + + +# --- Settings tab (allow-host LAN opt-in, #507) --- + +func _build_settings_tab(tabs: TabContainer) -> void: + ## Tab 3 — settings-style controls that don't fit Clients or Tools: the + ## Vision Routing section plus the `--allow-host` LAN opt-in behind a + ## collapsed "Remote access (advanced)" disclosure, so its security + ## warning renders exactly at the point of configuration. Rendered once + ## on dock construction, mirroring `_build_tools_tab`; + ## `_reset_allow_hosts_from_setting()` and `vision_routing.refresh_ui()` + ## re-sync each time the window opens (via + ## `_reset_tools_pending_from_setting` / `_on_open_clients_window`). + var settings_tab := VBoxContainer.new() + settings_tab.add_theme_constant_override("separation", 8) + var settings_margin := _build_margin_container() + settings_margin.name = "Settings" + settings_margin.add_child(settings_tab) + tabs.add_child(settings_margin) + + ## Vision Routing is configuration, not status — it lives here rather + ## than in the dock. Not dev-gated: it is the Settings tab's primary + ## content and must work for every user. + if vision_routing != null: + vision_routing.build_section(settings_tab) + + ## Remote access (advanced): collapsed by default; auto-expands when a + ## non-empty CIDR allowlist is already configured so an active + ## off-loopback bind is never hidden behind a collapsed header. The + ## disclosure replaces the former developer-mode gate for this block. + _allow_hosts_fold = FoldableContainer.new() + _allow_hosts_fold.title = "Remote access (advanced)" + _allow_hosts_fold.folded = true + settings_tab.add_child(_allow_hosts_fold) + + _allow_hosts_section = VBoxContainer.new() + _allow_hosts_section.add_theme_constant_override("separation", 6) + _allow_hosts_fold.add_child(_allow_hosts_section) + + _allow_hosts_section.add_child(_make_header("Allow remote hosts (CIDR)")) + + var intro := Label.new() + intro.text = ( + "Comma-separated CIDRs or bare IPs (e.g. 192.168.1.0/24, 10.0.0.5). " + + "When non-empty, the server binds off loopback and accepts MCP " + + "connections from these ranges (--allow-host)." + ) + intro.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + intro.add_theme_color_override("font_color", COLOR_MUTED) + intro.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _allow_hosts_section.add_child(intro) + + ## Warning banner — the DNS-rebinding guard is widened to every machine + ## in the named ranges, so make the user name a network they trust + ## instead of offering a blanket "expose everything" toggle (#507). + var warning := Label.new() + warning.text = ( + "Warning: every machine in these ranges can drive this Godot editor, " + + "and the DNS-rebinding guard's Host allowlist is widened to match. " + + "Only name networks you trust. On untrusted or shared networks, " + + "prefer an SSH tunnel or Tailscale instead of exposing the port." + ) + warning.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + warning.add_theme_color_override("font_color", COLOR_AMBER) + warning.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _allow_hosts_section.add_child(warning) + + _allow_hosts_edit = LineEdit.new() + _allow_hosts_edit.placeholder_text = "e.g. 192.168.1.0/24, 10.0.0.5 — empty = loopback only" + _allow_hosts_edit.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _allow_hosts_edit.text_changed.connect(_on_allow_hosts_text_changed) + _allow_hosts_section.add_child(_allow_hosts_edit) + + _allow_hosts_hint = Label.new() + _allow_hosts_hint.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _allow_hosts_hint.add_theme_color_override("font_color", Color.RED) + _allow_hosts_hint.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _allow_hosts_hint.visible = false + _allow_hosts_section.add_child(_allow_hosts_hint) + + _allow_hosts_apply_btn = Button.new() + _allow_hosts_apply_btn.text = "Apply and Restart Server" + _allow_hosts_apply_btn.tooltip_text = ( + "Save the allowlist to Editor Settings and reload the plugin so the " + + "server respawns with --allow-host. Clear the field and Apply to " + + "return to loopback-only." + ) + _allow_hosts_apply_btn.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _allow_hosts_apply_btn.pressed.connect(_on_allow_hosts_apply) + _allow_hosts_section.add_child(_allow_hosts_apply_btn) + + _reset_allow_hosts_from_setting() + + +func _reset_allow_hosts_from_setting() -> void: + _allow_hosts_saved = ClientConfigurator.allow_hosts() + _refresh_allow_hosts_fold_state() + if _allow_hosts_edit == null: + return + _allow_hosts_edit.text = _allow_hosts_saved + _refresh_allow_hosts_ui_state() + + +## Auto-expands the "Remote access (advanced)" disclosure whenever a +## non-empty allowlist is configured, so an active off-loopback bind is +## never hidden behind a collapsed header. +func _refresh_allow_hosts_fold_state() -> void: + if _allow_hosts_fold == null: + return + if ClientConfigurator.allow_hosts().is_empty(): + _allow_hosts_fold.fold() + else: + _allow_hosts_fold.expand() + + +func _allow_hosts_is_dirty() -> bool: + if _allow_hosts_edit == null: + return false + return McpAllowHosts.normalize(_allow_hosts_edit.text) != _allow_hosts_saved + + +func _on_allow_hosts_text_changed(_new_text: String) -> void: + _refresh_allow_hosts_ui_state() + + +func _refresh_allow_hosts_ui_state() -> void: + if _allow_hosts_edit == null or _allow_hosts_apply_btn == null: + return + var invalid := McpAllowHosts.invalid_tokens(_allow_hosts_edit.text) + if invalid.is_empty(): + _allow_hosts_hint.visible = false + else: + ## Name the accepted syntax in the hint — matches the server's + ## `parse_allow_hosts` (CIDR / bare IP, comma-separated). + _allow_hosts_hint.text = ( + "Invalid entries (must be a CIDR like 192.168.1.0/24 or a bare IP, comma-separated): %s" + % ", ".join(invalid) + ) + _allow_hosts_hint.visible = true + _allow_hosts_apply_btn.disabled = not _allow_hosts_is_dirty() or not invalid.is_empty() + + +func _on_allow_hosts_apply() -> void: + if _allow_hosts_edit == null: + return + var normalized := McpAllowHosts.normalize(_allow_hosts_edit.text) + if not McpAllowHosts.invalid_tokens(normalized).is_empty(): + return + var es := EditorInterface.get_editor_settings() + if es != null: + es.set_setting(McpSettings.SETTING_ALLOW_HOSTS, normalized) + _allow_hosts_saved = normalized + _allow_hosts_edit.text = normalized + _refresh_allow_hosts_ui_state() + ## Plugin reload respawns the server with the new `--allow-host` flag + ## (see `plugin.gd::_build_server_flags`). Mirrors the Tools-tab Apply + ## and port-change flows. + _on_reload_plugin() + + +func _refresh_clients_summary() -> void: + # Count from cached row status values — `_apply_row_status` is the single + # source of truth, and reading cached status avoids re-running + # filesystem/CLI-hitting checks on every refresh. The same cache re-derives + # the drift banner so per-row mutations (Configure/Reconfigure/Remove on a + # row in the Clients & Tools window) keep the dock-level banner in sync + # without an extra sweep. See #166 and #226. + if _clients_summary_label == null: + return + var configured := 0 + var mismatched_ids: Array[String] = [] + for client_id in _client_rows: + var status: Client.Status = _client_rows[client_id].get("status", Client.Status.NOT_CONFIGURED) + if status == Client.Status.CONFIGURED: + configured += 1 + elif status == Client.Status.CONFIGURED_MISMATCH: + mismatched_ids.append(client_id) + var text := "%d / %d configured" % [configured, _client_rows.size()] + if mismatched_ids.size() > 0: + text += " (%d stale)" % mismatched_ids.size() + if ClientRefreshStateScript.should_show_checking_badge(_refresh_state): + text += ( + " (checking...)" + if _refresh_state != ClientRefreshStateScript.RUNNING_TIMED_OUT + else " (client probe still running)" + ) + _clients_summary_label.text = text + if _client_configure_all_btn != null: + _client_configure_all_btn.disabled = ClientRefreshStateScript.should_disable_client_actions(_refresh_state) + if _client_empty_cta_btn != null: + _client_empty_cta_btn.visible = configured == 0 and _client_status_refresh_has_completed() + _refresh_drift_banner(mismatched_ids) + _update_status() + + +func _show_manual_command_for(client_id: String) -> void: + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + var cmd := ClientConfigurator.manual_command(client_id) + if cmd.is_empty(): + row["manual_panel"].visible = false + return + row["manual_text"].text = cmd + row["manual_panel"].visible = true + ## #680: for rows low in the list the panel materializes below the + ## visible scroll area and the Configure click looks like a no-op. + ## Deferred so the just-shown panel has a settled rect to scroll to. + _scroll_manual_panel_into_view.call_deferred(row["manual_panel"]) + + +func _scroll_manual_panel_into_view(panel: Control) -> void: + if panel == null or not panel.is_inside_tree(): + return + var ancestor := panel.get_parent() + while ancestor != null and not (ancestor is ScrollContainer): + ancestor = ancestor.get_parent() + if ancestor != null: + (ancestor as ScrollContainer).ensure_control_visible(panel) + + +func _on_copy_manual_command(client_id: String) -> void: + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + DisplayServer.clipboard_set(row["manual_text"].text) + + +func _on_open_config_file(client_id: String) -> void: + var path := _client_config_path_for_row(client_id) + if path.is_empty(): + return + if FileAccess.file_exists(path): + OS.shell_open(path) + return + _reveal_config_folder(path) + + +func _on_reveal_config_folder(client_id: String) -> void: + var path := _client_config_path_for_row(client_id) + if path.is_empty(): + return + _reveal_config_folder(path) + + +func _client_config_path_for_row(client_id: String) -> String: + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return "" + return String(row.get("config_path", "")) + + +func _reveal_config_folder(path: String) -> void: + var dir := path.get_base_dir() + if dir.is_empty(): + return + OS.shell_open(dir) + + +func _refresh_all_client_statuses() -> void: + ## Compatibility wrapper for older explicit call sites. Treat this as a manual + ## refresh: it bypasses focus-in cooldown but still runs probes off the editor + ## main thread. + if _server_blocks_client_health(): + for client_id in _client_rows: + _apply_row_status(String(client_id), Client.Status.ERROR, _server_blocked_client_message()) + _refresh_clients_summary() + return + _request_client_status_refresh(true) + + +func _is_client_status_refresh_in_cooldown() -> bool: + if _last_client_status_refresh_completed_msec <= 0: + return false + return Time.get_ticks_msec() - _last_client_status_refresh_completed_msec < CLIENT_STATUS_REFRESH_COOLDOWN_MSEC + + +func _has_client_status_refresh_timed_out() -> bool: + if not ClientRefreshStateScript.has_worker_alive(_refresh_state): + return false + if _client_status_refresh_started_msec <= 0: + return false + return Time.get_ticks_msec() - _client_status_refresh_started_msec >= CLIENT_STATUS_REFRESH_TIMEOUT_MSEC + + +func _check_client_status_refresh_timeout() -> void: + if not _has_client_status_refresh_timed_out(): + return + if _refresh_state == ClientRefreshStateScript.RUNNING_TIMED_OUT: + return + _refresh_state = ClientRefreshStateScript.RUNNING_TIMED_OUT + _refresh_clients_summary() + + +func _abandon_client_status_refresh_thread() -> void: + ## GDScript cannot interrupt a blocking `OS.execute(..., true)` call in a + ## worker. If a CLI probe hangs, orphan this run, bump the generation so any + ## late result becomes a no-op, and let a forced/manual refresh start a fresh + ## probe slot. Completed orphan threads are pruned from `_process`. + _client_status_refresh_generation += 1 + if _client_status_refresh_thread != null: + _orphaned_client_status_refresh_threads.append(_client_status_refresh_thread) + _client_status_refresh_thread = null + if _refresh_state != ClientRefreshStateScript.SHUTTING_DOWN: + _refresh_state = ClientRefreshStateScript.IDLE + ## Reset the full pending-request triplet, not just the + ## focus-in / cooldown half. A timed-out worker has already + ## warmed bytecode, so any stale `_pending_initial` from an + ## earlier deferred-during-busy startup is no longer load-bearing + ## — leaving it set would cause `_retry_deferred_*` to dispatch + ## `_perform_initial_*` a second time after this abandon + ## (which would then no-op because no fresh worker is needed + ## but still re-warm bytecode and walk the row set redundantly). + _client_status_refresh_pending = false + _client_status_refresh_pending_force = false + _client_status_refresh_pending_initial = false + _client_status_refresh_started_msec = 0 + _refresh_clients_summary() + + +func _prune_orphaned_client_status_refresh_threads() -> void: + for i in range(_orphaned_client_status_refresh_threads.size() - 1, -1, -1): + var thread := _orphaned_client_status_refresh_threads[i] + if thread == null: + _orphaned_client_status_refresh_threads.remove_at(i) + elif not thread.is_alive(): + thread.wait_to_finish() + _orphaned_client_status_refresh_threads.remove_at(i) + + +func _perform_initial_client_status_refresh() -> void: + ## Pre-warm strategy bytecode on main, then hand every client probe + ## (JSON / TOML / CLI alike) to the worker. + ## + ## Godot's GDScript hot-reload of overwritten plugin files is lazy: the + ## bytecode swap happens on first dereference, not at `set_plugin_enabled` + ## time. A worker thread spawned from a fresh `_build_ui` walks into + ## `_json_strategy.*` / `_cli_strategy.*` / `client_configurator.*` while + ## bytecode pages are mid-swap → SIGABRT. Dereferencing those scripts on + ## main first forces the swap to complete here; the worker then finds + ## stable bytecode. Filesystem signals don't bracket the swap window + ## (they fire before bytecode replacement), and FOCUS_IN doesn't fire on + ## in-place plugin reload because the editor stays focused — so neither + ## works as a gate. See #233 / #235. + ## + ## Phase 1 (sync, on main): a single explicit `_warm_strategy_bytecode` + ## call invokes a pure-memory helper on each strategy script — + ## `_json_strategy.gd`, `_toml_strategy.gd`, `_cli_strategy.gd`, plus + ## `client_configurator.gd` via `client_ids()` / `get_by_id`. No disk, + ## no `OS.execute`, no JSON parse on main. `client_status_probe_snapshot` + ## per client adds the `installed` flag and (for CLI clients) a cached + ## CLI path to each probe. + ## + ## Phase 2 (worker): every probe — JSON, TOML, CLI — runs through the + ## same `_run_client_status_refresh_worker` pipeline. Disk reads + JSON + ## parses for the ~17 non-CLI clients now happen off the main thread, + ## so the dock paints immediately on cold open instead of stalling + ## behind ~16 sync `FileAccess.open` + `JSON.parse_string` calls. + ## + ## No-op outside the tree — GDScript tests instantiate via `new()`. + if not is_inside_tree(): + return + if _client_rows.is_empty(): + return + if ClientRefreshStateScript.is_blocked_for_spawn(_refresh_state): + return + if _is_self_update_in_progress(): + return + if _is_editor_filesystem_busy(): + _defer_initial_client_status_refresh_until_filesystem_ready() + return + if ClientRefreshStateScript.has_worker_alive(_refresh_state): + return + + if _server_blocks_client_health(): + for client_id in _client_rows: + _apply_row_status(String(client_id), Client.Status.ERROR, _server_blocked_client_message()) + _refresh_clients_summary() + return + + _warm_strategy_bytecode() + + var generation := _begin_client_status_refresh_run() + var launch_context := ClientConfigurator.capture_launch_context() + var server_url := ClientConfigurator.server_url_from(launch_context) + var all_probes: Array[Dictionary] = [] + + for client_id in _client_rows: + var probe := ClientConfigurator.client_status_probe_snapshot(String(client_id)) + if probe.is_empty(): + continue + all_probes.append(probe) + _refresh_clients_summary() + + if all_probes.is_empty(): + _finalize_completed_refresh() + return + + _client_status_refresh_thread = Thread.new() + var err := _client_status_refresh_thread.start( + Callable(self, "_run_client_status_refresh_worker").bind( + all_probes, server_url, launch_context, generation + ) + ) + if err != OK: + _refresh_state = ClientRefreshStateScript.IDLE + _client_status_refresh_thread = null + _refresh_clients_summary() + + +## Force GDScript's lazy bytecode swap to complete for every script the +## worker thread will reach into. Each call is pure-memory — no disk, no +## network, no `OS.execute` — so it only costs the bytecode dereference +## itself. See `_perform_initial_client_status_refresh` for context and +## #233 / #235 for the SIGABRT this exists to prevent. +func _warm_strategy_bytecode() -> void: + var ids := ClientConfigurator.client_ids() + if ids.is_empty(): + return + var any_client := ClientRegistry.get_by_id(String(ids[0])) + if any_client != null: + JsonStrategy.verify_entry(any_client, {}, "") + TomlStrategy.format_body(PackedStringArray(), "") + CliStrategy.format_args(PackedStringArray(), "", "") + ## #691: refresh the env snapshot on main before the worker starts, so + ## its config-path expansions read the snapshot instead of racing a + ## concurrent spawn window's setenv/unsetenv. + ClientConfigurator.warm_env_snapshot() + + +func _begin_client_status_refresh_run() -> int: + ## Marks a refresh as starting and returns the new generation token. + ## Generation is bumped here (not at completion) so that a worker result + ## reaped after `_abandon_client_status_refresh_thread` or `_exit_tree` + ## fires can be detected as stale via generation mismatch. + _refresh_state = ClientRefreshStateScript.RUNNING + _client_status_refresh_pending = false + _client_status_refresh_pending_force = false + _client_status_refresh_started_msec = Time.get_ticks_msec() + _client_status_refresh_generation += 1 + _refresh_clients_summary() + return _client_status_refresh_generation + + +func _finalize_completed_refresh() -> void: + ## Stamps cooldown and clears in-flight state. Called at the end of every + ## refresh that successfully applied results — the worker reaping path + ## and the no-CLI fast path in `_perform_initial_client_status_refresh`. + _last_client_status_refresh_completed_msec = Time.get_ticks_msec() + if _refresh_state != ClientRefreshStateScript.SHUTTING_DOWN: + _refresh_state = ClientRefreshStateScript.IDLE + _refresh_clients_summary() + ## After the summary pass so `_last_mismatched_ids` reflects the sweep + ## that just completed. + _maybe_auto_repin_after_update() + + +func _request_client_status_refresh(force: bool = false) -> bool: + ## Stale-while-refreshing: do not clear dots, summary, or the drift banner + ## when a refresh is requested. The existing UI remains visible until the + ## background worker's result is applied on the main thread. + if _server_blocks_client_health(): + for client_id in _client_rows: + _apply_row_status(String(client_id), Client.Status.ERROR, _server_blocked_client_message()) + _refresh_clients_summary() + return false + if _is_self_update_in_progress(): + ## Self-update is overwriting plugin scripts on disk; spawning a worker + ## now would crash it inside `GDScriptFunction::call` once the bytecode + ## swap reaches a script the worker is mid-call into. Focus-in / + ## manual button / cooldown timer all funnel through here, so one + ## gate covers every spawn path during the install window. The flag + ## lives on `_update_manager` and dies with the dock instance during + ## `set_plugin_enabled(false)`. + return false + if ClientRefreshStateScript.has_worker_alive(_refresh_state): + if force and _has_client_status_refresh_timed_out(): + _abandon_client_status_refresh_thread() + else: + _client_status_refresh_pending = true + _client_status_refresh_pending_force = _client_status_refresh_pending_force or force + _refresh_clients_summary() + return false + if ClientRefreshStateScript.is_blocked_for_spawn(_refresh_state): + return false + if not force and _is_client_status_refresh_in_cooldown(): + return false + if _client_rows.is_empty(): + return false + if _is_editor_filesystem_busy(): + if force: + _defer_client_status_refresh_until_filesystem_ready(force) + return false + + ## Manual refresh (any `force=true` path: button click, popup open, + ## external API caller) implies "may have installed a CLI since the + ## last sweep" — flush CliFinder so freshly-installed binaries get + ## re-detected. Focus-in (`force=false`) stays cached so the cheap + ## case stays cheap. Per-CLI invalidation + ## (`invalidate_uvx_cli_cache`) still pairs with specific events + ## like `_on_install_uv` where the binary name is known. + if force: + ClientConfigurator.invalidate_cli_cache() + + ## Force the bytecode swap on the same scripts the worker will reach + ## into — same #233/#235 guard `_perform_initial_*` already had. + ## Without this, a manual refresh dispatched before the initial sweep + ## has run (e.g. user clicks Refresh during the deferred-initial + ## window after `_defer_client_status_refresh_until_filesystem_ready` + ## cleared `_pending_initial`) walks into mid-swap bytecode and + ## SIGABRTs. + _warm_strategy_bytecode() + + var client_probes: Array[Dictionary] = [] + for client_id in _client_rows: + client_probes.append(ClientConfigurator.client_status_probe_snapshot(String(client_id))) + var launch_context := ClientConfigurator.capture_launch_context() + var server_url := ClientConfigurator.server_url_from(launch_context) + + var generation := _begin_client_status_refresh_run() + _client_status_refresh_thread = Thread.new() + var err := _client_status_refresh_thread.start( + Callable(self, "_run_client_status_refresh_worker").bind( + client_probes, server_url, launch_context, generation + ) + ) + if err != OK: + _refresh_state = ClientRefreshStateScript.IDLE + _client_status_refresh_thread = null + _refresh_clients_summary() + return false + return true + + +func _is_editor_filesystem_busy() -> bool: + var fs := EditorInterface.get_resource_filesystem() + return fs != null and fs.is_scanning() + + +func _defer_initial_client_status_refresh_until_filesystem_ready() -> void: + _refresh_state = ClientRefreshStateScript.DEFERRED_FOR_FILESYSTEM + _client_status_refresh_pending_initial = true + + +func _defer_client_status_refresh_until_filesystem_ready(force: bool) -> void: + ## Godot can still be reparsing/reloading plugin scripts while the editor + ## filesystem is busy. Do not spawn a worker into that window: the worker + ## can call plugin GDScript while the main thread is reloading it, which + ## crashes in `GDScriptFunction::call`. + ## + ## A manual refresh request is more recent intent than any earlier + ## deferred-initial sweep, so we clear `_pending_initial` here. + ## `_request_client_status_refresh` warms strategy bytecode itself + ## now (see #233/#235), so the safety net the initial path provided + ## still applies to the replayed manual refresh. + _refresh_state = ClientRefreshStateScript.DEFERRED_FOR_FILESYSTEM + _client_status_refresh_pending_force = _client_status_refresh_pending_force or force + _client_status_refresh_pending_initial = false + + +func _retry_deferred_client_status_refresh() -> void: + if _refresh_state != ClientRefreshStateScript.DEFERRED_FOR_FILESYSTEM: + return + if _is_self_update_in_progress(): + return + if _is_editor_filesystem_busy(): + return + + var initial := _client_status_refresh_pending_initial + var force := _client_status_refresh_pending_force + _refresh_state = ClientRefreshStateScript.IDLE + _client_status_refresh_pending_force = false + _client_status_refresh_pending_initial = false + if initial: + _perform_initial_client_status_refresh() + else: + _request_client_status_refresh(force) + + +func _run_client_status_refresh_worker( + client_probes: Array[Dictionary], + server_url: String, + launch_context: Dictionary, + generation: int, +) -> Dictionary: + var results: Dictionary = {} + # Command-shaped clients share one attach launch. Discovery can be the + # dominant cold-cache cost, so resolve it once per refresh worker rather + # than once for Claude Desktop and again for Codex. + var resolved_launch := ClientConfigurator.resolve_attach_launch(launch_context) + for probe in client_probes: + var client_id := String(probe.get("id", "")) + if client_id.is_empty(): + continue + var details := ClientConfigurator.check_status_details_for_url_with_cli_path( + client_id, + server_url, + String(probe.get("cli_path", "")), + launch_context, + resolved_launch, + ) + var installed := bool(probe.get("installed", false)) + results[client_id] = { + "status": details.get("status", Client.Status.NOT_CONFIGURED), + "installed": installed, + "error_msg": details.get("error_msg", ""), + } + return {"results": results, "generation": generation} + + +func _poll_completed_client_status_refresh_thread() -> void: + if _client_status_refresh_thread == null: + return + if _client_status_refresh_thread.is_alive(): + return + var payload: Variant = _client_status_refresh_thread.wait_to_finish() + _client_status_refresh_thread = null + if payload is Dictionary: + var data := payload as Dictionary + var results: Dictionary = data.get("results", {}) + _apply_client_status_refresh_results( + results, + int(data.get("generation", _client_status_refresh_generation)) + ) + else: + _apply_client_status_refresh_results({}, _client_status_refresh_generation) + + +func _apply_client_status_refresh_results(results: Dictionary, generation: int) -> void: + if generation != _client_status_refresh_generation or _refresh_state == ClientRefreshStateScript.SHUTTING_DOWN: + return + if _client_status_refresh_thread != null: + _client_status_refresh_thread.wait_to_finish() + _client_status_refresh_thread = null + if _server_blocks_client_health(): + for client_id in _client_rows: + _apply_row_status(String(client_id), Client.Status.ERROR, _server_blocked_client_message()) + _finalize_completed_refresh() + return + + for client_id in results: + ## Skip rows whose Configure / Remove worker is still running so the + ## status refresh doesn't overwrite the "Configuring…" / "Removing…" + ## badge with a stale dot color. The action's own completion handler + ## will repaint the row when it lands. + if _client_action_threads.has(String(client_id)): + continue + var result: Dictionary = results[client_id] + _apply_row_status( + String(client_id), + result.get("status", Client.Status.NOT_CONFIGURED), + str(result.get("error_msg", "")), + result.get("installed", false) + ) + _finalize_completed_refresh() + + if _client_status_refresh_pending: + var pending_force := _client_status_refresh_pending_force + _client_status_refresh_pending = false + _client_status_refresh_pending_force = false + _request_client_status_refresh(pending_force) + + +func _server_blocks_client_health() -> bool: + if _plugin == null or not _plugin.has_method("get_server_status"): + return false + var status: Dictionary = _plugin.get_server_status() + return ServerStateScript.blocks_client_health( + int(status.get("state", ServerStateScript.UNINITIALIZED)) + ) + + +func _server_blocked_client_message() -> String: + if _plugin == null or not _plugin.has_method("get_server_status"): + return "server incompatible" + var status: Dictionary = _plugin.get_server_status() + var message := str(status.get("message", "")) + return message if not message.is_empty() else "server incompatible" + + +func _refresh_drift_banner(mismatched_ids: Array[String]) -> void: + if _drift_banner == null: + return + ## Sort so set-equality is order-independent — `_client_rows` iteration + ## order is dict-insertion order, but a future change to the iteration + ## site shouldn't make us repaint identical content. + mismatched_ids = mismatched_ids.duplicate() + mismatched_ids.sort() + if mismatched_ids == _last_mismatched_ids: + return + _last_mismatched_ids = mismatched_ids + if mismatched_ids.is_empty(): + _drift_banner.visible = false + return + var names: Array[String] = [] + for id in mismatched_ids: + names.append(ClientConfigurator.client_display_name(id)) + ## Active server URL is already shown on the WS:/HTTP: line above the + ## Clients section, so it doesn't need to repeat here. Lead with the + ## client names — that's the only thing the user can act on. + var verb := "needs" if mismatched_ids.size() == 1 else "need" + _drift_label.text = "%s %s to be reconfigured." % [", ".join(names), verb] + _drift_banner.visible = true + + +func _on_reconfigure_mismatched() -> void: + ## Re-Configure every client whose URL is currently stale. Iterates the + ## cached list from the most recent sweep instead of re-running + ## `check_status` per row (saves ~18 filesystem reads per click). The + ## trailing `_refresh_all_client_statuses()` re-sweeps anyway, so any + ## entries the user manually fixed between sweep and click get re-counted + ## as CONFIGURED there. + for client_id in _last_mismatched_ids: + if _client_rows.has(client_id): + _on_configure_client(client_id) + _refresh_all_client_statuses() + + +## Arm the one-shot post-update repin (see `_pending_post_update_repin`). +## Called by plugin.gd when it drains a `status == "success"` self-update +## marker, i.e. exactly once per completed update. `from_version` is the +## plugin version the update replaced — required by the pin-only gate +## below; an empty value (marker from a pre-gate runner) arms nothing, so +## those updates keep the manual drift-banner path. +func notify_self_update_success(from_version: String = "") -> void: + if from_version.strip_edges().is_empty(): + return + _post_update_from_version = from_version.strip_edges() + _pending_post_update_repin = true + + +## Consume `_pending_post_update_repin` on the first completed status sweep +## that could actually observe drift. Runs from `_finalize_completed_refresh` +## AFTER `_refresh_clients_summary()` has rebuilt `_last_mismatched_ids` +## from the sweep that just landed. +## +## Blast-radius gate: only entries whose SOLE drift is the old version pin +## are repinned (`entry_drift_is_version_pin_only`). A mismatched entry can +## also mean "points at a different editor's ports" — this dock ran inside +## a side project with custom ports, or the user hand-tuned the entry — and +## auto-rewriting those hijacks every AI client on the machine to THIS +## editor's ports (observed live: the self-update smoke fixture on port +## 18000 repinned 21 real client configs). Those stay on the drift banner's +## human click. +func _maybe_auto_repin_after_update() -> void: + if not _pending_post_update_repin: + return + ## While the server is INCOMPATIBLE (post-update stale-occupant recovery + ## still in flight) every row reads ERROR, not CONFIGURED_MISMATCH — a + ## consume here would see an empty mismatch list and drop the repin on + ## the floor. Stay pending for the sweep that lands after recovery. + if _server_blocks_client_health(): + return + if ClientRefreshStateScript.should_disable_client_actions(_refresh_state): + return + _pending_post_update_repin = false + var from_version := _post_update_from_version + _post_update_from_version = "" + if _last_mismatched_ids.is_empty(): + return + var launch_context := ClientConfigurator.capture_launch_context() + var pin_only: Array[String] = [] + for client_id in _last_mismatched_ids: + if _entry_drift_is_version_pin_only(String(client_id), from_version, launch_context): + pin_only.append(String(client_id)) + if pin_only.is_empty(): + print( + "MCP | self-update complete — no client entry drifts by version pin alone; leaving %d drifted config(s) to the Reconfigure banner" + % _last_mismatched_ids.size() + ) + return + print( + "MCP | self-update complete — repinning %d client config(s) from v%s to v%s" + % [pin_only.size(), from_version, ClientConfigurator.get_plugin_version()] + ) + for client_id in pin_only: + if _client_rows.has(client_id): + _on_configure_client(client_id) + _refresh_all_client_statuses() + + +## Instance seam over the static gate so the dock test suite can fake the +## per-client verdict without real config files on disk. +func _entry_drift_is_version_pin_only( + client_id: String, from_version: String, launch_context: Dictionary +) -> bool: + return ClientConfigurator.entry_drift_is_version_pin_only( + client_id, from_version, launch_context + ) + + +func _apply_row_status( + client_id: String, + status: Client.Status, + error_msg: String = "", + installed_override: Variant = null, +) -> void: + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + row["status"] = status + var dot: ColorRect = row["dot"] + var configure_btn: Button = row["configure_btn"] + var remove_btn: Button = row["remove_btn"] + var name_label: Label = row["name_label"] + var base_name := ClientConfigurator.client_display_name(client_id) + _refresh_client_config_file_buttons(client_id) + match status: + Client.Status.CONFIGURED: + dot.color = Color.GREEN + configure_btn.text = "Reconfigure" + remove_btn.visible = true + ## `error_msg` doubles as a detail slot on the green path: a + ## successful configure passes the sweep note (#877). Transient by + ## design — the next status refresh re-applies CONFIGURED with no + ## detail, so the row settles back to its plain name. + name_label.text = ( + "%s (%s)" % [base_name, error_msg] if not error_msg.is_empty() else base_name + ) + Client.Status.NOT_CONFIGURED: + dot.color = COLOR_MUTED + configure_btn.text = "Configure" + remove_btn.visible = false + var installed: bool = installed_override if installed_override != null else ClientConfigurator.is_installed(client_id) + name_label.text = base_name if installed else "%s (not detected)" % base_name + Client.Status.CONFIGURED_MISMATCH: + ## Amber matches the dock-level drift banner so a glance at the + ## row + the banner read as the same condition. + dot.color = COLOR_AMBER + configure_btn.text = "Reconfigure" + remove_btn.visible = true + ## Drift is usually a stale URL, but a `{scope}` client can also be + ## registered in a scope the user did not select (#872), and + ## "URL out of date" would be a wrong description of that. Prefer + ## the probe's own words whenever it supplied any. + name_label.text = ( + "%s (%s)" % [base_name, error_msg] + if not error_msg.is_empty() + else "%s (URL out of date)" % base_name + ) + _: + dot.color = Color.RED + configure_btn.text = "Retry" + remove_btn.visible = false + name_label.text = "%s — %s" % [base_name, error_msg] if not error_msg.is_empty() else base_name + + +func _refresh_client_config_file_buttons(client_id: String) -> void: + var row: Dictionary = _client_rows.get(client_id, {}) + if row.is_empty(): + return + # Re-resolve on every refresh so the Open/Reveal buttons follow the entry + # when it lands in (or moves to) a higher-precedence merge tier (codex F3). + # F-3-4: switched from `effective_config_path` to the authoritative facade + # so multi-project-tier cases resolve to the LATEST tier (matching F2 + # status semantics) instead of failing closed to `path_template`. + row["config_path"] = ClientConfigurator.effective_authoritative_path(client_id) + var config_path := String(row["config_path"]) + var has_path := not config_path.is_empty() + var open_config_btn: Button = row["open_config_btn"] + var reveal_btn: Button = row["reveal_btn"] + open_config_btn.visible = has_path + reveal_btn.visible = has_path + open_config_btn.disabled = not has_path + reveal_btn.disabled = not has_path + if has_path: + open_config_btn.tooltip_text = "Open config file:\n%s" % config_path + reveal_btn.tooltip_text = "Reveal in folder:\n%s" % config_path.get_base_dir() + else: + open_config_btn.tooltip_text = "" + reveal_btn.tooltip_text = "" + + +# --- Update check & self-update --- + +## Tolerates a null manager so test fixtures that build the dock without +## `_build_ui()` don't false-positive on the worker-spawn gate. +func _is_self_update_in_progress() -> bool: + return _update_manager != null and bool(_update_manager.is_install_in_flight()) + + +func _on_update_pressed() -> void: + if _update_manager != null: + _update_manager.start_install() + + +func _on_update_check_result(result: Dictionary) -> void: + _update_label.text = String(result.get("label_text", "")) + _update_banner.visible = true + + +## Apply only the keys present so the manager can ship partial updates +## (e.g. button-text-only during the download phase) without clobbering +## banner state. +func _on_install_state_changed(state: Dictionary) -> void: + if state.has("button_text") and _update_btn != null: + _update_btn.text = String(state["button_text"]) + if state.has("button_disabled") and _update_btn != null: + _update_btn.disabled = bool(state["button_disabled"]) + if state.has("label_text") and _update_label != null: + _update_label.text = String(state["label_text"]) + if state.has("banner_visible") and _update_banner != null: + _update_banner.visible = bool(state["banner_visible"]) + if String(state.get("outcome", "")) == "success" and _update_label != null: + ## Visual confirmation for successful terminal update states. + _update_label.add_theme_color_override("font_color", Color.GREEN) diff --git a/addons/godot_ai/mcp_dock.gd.uid b/addons/godot_ai/mcp_dock.gd.uid new file mode 100644 index 0000000..5868719 --- /dev/null +++ b/addons/godot_ai/mcp_dock.gd.uid @@ -0,0 +1 @@ +uid://b8yknttdjanm5 diff --git a/addons/godot_ai/plugin.cfg b/addons/godot_ai/plugin.cfg new file mode 100644 index 0000000..ff997ab --- /dev/null +++ b/addons/godot_ai/plugin.cfg @@ -0,0 +1,7 @@ +[plugin] + +name="Godot AI" +description="MCP server and AI tools for Godot" +author="Godot AI" +version="3.2.4" +script="plugin.gd" diff --git a/addons/godot_ai/plugin.gd b/addons/godot_ai/plugin.gd new file mode 100644 index 0000000..db0de5c --- /dev/null +++ b/addons/godot_ai/plugin.gd @@ -0,0 +1,2144 @@ +@tool +extends EditorPlugin + +const GAME_HELPER_AUTOLOAD_NAME := "_mcp_game_helper" +const GAME_HELPER_AUTOLOAD_PATH := "res://addons/godot_ai/runtime/game_helper.gd" + +## Editor-process Logger subclass — captures parse errors, @tool runtime +## errors, and push_error/push_warning so the LLM can read them via +## `logs_read(source="editor")`. +const EditorLogger := preload("res://addons/godot_ai/runtime/editor_logger.gd") + +## EditorSettings keys used to remember which server process the plugin +## spawned — survives editor restarts, lets a later editor session adopt +## and manage a server it didn't spawn itself. See #135. +const MANAGED_SERVER_PID_SETTING := "godot_ai/managed_server_pid" +const MANAGED_SERVER_VERSION_SETTING := "godot_ai/managed_server_version" +const MANAGED_SERVER_WS_PORT_SETTING := "godot_ai/managed_server_ws_port" +## Per-launch WS handshake auth token (#690), generated at spawn and handed +## to the server via the GODOT_AI_WS_TOKEN spawn env. Persisted alongside +## the managed-server record so a reloaded plugin instance adopting the +## same server keeps authenticating; cleared with the rest of the record. +const MANAGED_SERVER_WS_TOKEN_SETTING := "godot_ai/managed_server_ws_token" +## keep_server_on_exit (#800): records whether the managed server was +## launched with the keep-alive env opt-outs, so a later session adopting +## the survivor routes its own editor exit through detach too. The live +## setting can't answer that — it may have changed since the spawn. +const MANAGED_SERVER_KEEP_ALIVE_SETTING := "godot_ai/managed_server_keep_alive" +const UPDATE_RELOAD_RUNNER_SCRIPT := preload("res://addons/godot_ai/update_reload_runner.gd") + +## Server lifecycle + port discovery extracted from this file (#297 PR 5). +## State enums + version-check seam extracted in PR 6 (#297). Plugin.gd +## keeps thin shims so the dock and characterization tests see an +## unchanged public surface; spawn-machinery state now lives in the +## lifecycle manager. +const ServerLifecycleManager := preload("res://addons/godot_ai/utils/server_lifecycle.gd") +const PortResolver := preload("res://addons/godot_ai/utils/port_resolver.gd") +const ServerStateScript := preload("res://addons/godot_ai/utils/mcp_server_state.gd") + +## Plugin-class scripts used by this file. The script-local preload aliases +## are ordinary dependency shorthand and keep construction sites compact. +## They are not the self-update safety boundary; #398 was stale Script-object +## content from a mixed old/new snapshot, fixed by the runner's single-phase +## write-before-scan model. +const Connection := preload("res://addons/godot_ai/connection.gd") +const Dispatcher := preload("res://addons/godot_ai/dispatcher.gd") +const Telemetry := preload("res://addons/godot_ai/telemetry.gd") +const LogBuffer := preload("res://addons/godot_ai/utils/log_buffer.gd") +const GameLogBuffer := preload("res://addons/godot_ai/utils/game_log_buffer.gd") +const EditorLogBuffer := preload("res://addons/godot_ai/utils/editor_log_buffer.gd") +const SurfacedErrorTracker := preload("res://addons/godot_ai/utils/surfaced_error_tracker.gd") +const Dock := preload("res://addons/godot_ai/mcp_dock.gd") +const DebuggerPlugin := preload("res://addons/godot_ai/debugger/mcp_debugger_plugin.gd") +const VisionRoutingScript := preload("res://addons/godot_ai/vision_routing.gd") +const ExportPlugin := preload("res://addons/godot_ai/export/mcp_export_plugin.gd") +const ClientConfigurator := preload("res://addons/godot_ai/client_configurator.gd") +const WindowsPortReservation := preload("res://addons/godot_ai/utils/windows_port_reservation.gd") +const McpToolRegistry := preload("res://addons/godot_ai/custom_tools/mcp_tool_registry.gd") +const McpServiceLocator := preload("res://addons/godot_ai/custom_tools/mcp_service_locator.gd") + +## Handlers are intentionally NOT preloaded here (#736). The old +## `const X := preload("res://addons/godot_ai/handlers/...")` block pulled +## every handler — and everything handlers preload — into plugin.gd's +## compile closure, so Godot parsed/compiled ~119 addon scripts before the +## first instruction of _enter_tree ran. GDScript has no cross-restart +## compile cache, so that stalled "Initializing plugins" on every editor +## boot and every plugin re-enable. Handlers are now registered by script +## path via McpDispatcher.register_lazy_handler / register_lazy and are +## load()ed at the first dispatch of one of their commands. +## +## Handlers remain preload-style scripts with no `class_name` so they don't +## pollute the project-wide global scope (#253): a user project that happens +## to define its own `InputHandler`, `SceneHandler`, etc. would otherwise +## hard-error on plugin enable. +const HANDLERS_DIR := "res://addons/godot_ai/handlers/" + +## The Python server writes its own PID here on startup (passed as +## `--pid-file`) and unlinks on clean exit. Deterministic replacement +## for scraping `netstat -ano` to find the port owner — especially on +## Windows where `OS.kill` on the uvx launcher doesn't take the Python +## child with it, and the scrape was the only path to the real PID. +## See issue for #154-era Windows update friction. +## Re-export of PortResolver.SERVER_PID_FILE so the spawn flags, the +## resolver, and characterization tests share one source of truth. +const SERVER_PID_FILE := PortResolver.SERVER_PID_FILE + +## How long we watch the spawned server for early exit once it has PROVEN it +## started — i.e. published its pid-file. If the process is still alive when +## this expires, we stop watching. Mid-session crashes after this point get +## caught by the WebSocket disconnect flow. +const SERVER_WATCH_MS := 30 * 1000 +## Watch ceiling for a spawn that has NOT yet published its pid-file (#896). +## +## The short window above justifies itself with "mid-session crashes surface +## via WebSocket disconnect" — which is only true for a server that got far +## enough to be connected to. A cold `uvx` spawn on a slow link can still be +## resolving and downloading its ~67-package environment at 30s, having proven +## nothing; stopping the watch there means a launcher that dies at 45s is never +## observed, `_diagnose_spawn_fast_exit` never runs (it is only reachable from +## inside the watch), and the plugin redials forever while the dock shows a +## bare "Disconnected". +## +## Sized to cover that download. Independent of any pre-warm: this window has +## to hold even when nothing warmed the cache first. +const SERVER_COLD_START_WATCH_MS := 180 * 1000 +## Python's import graph (FastMCP + Rich + uvicorn) plus the pid-file write +## take a beat on cold starts, especially on Windows. Hold off on declaring +## a spawn a crash until this window elapses so the watch loop has time to +## observe either the pid-file (dev venv) or the port listening (uvx). +const SPAWN_GRACE_MS := 5 * 1000 +## Windows only (#797). A uv-created venv launches the real server under a +## different PID than the one `OS.create_process` returns, and that watched PID +## has been seen dying on a healthy boot while the server was still starting +## and had not written its pid-file yet. Past SPAWN_GRACE_MS that reads as +## "server exited" and only the crash-survivor adoption path rescues the +## session. While no pid-file has appeared we keep watching until this longer +## window closes, rather than calling a handoff an exit. Sized to cover a cold +## uvx resolve on top of the launcher hop, and kept well under SERVER_WATCH_MS +## so a genuinely dead Windows spawn is still diagnosed inside the watch rather +## than falling off the end of it. +const SPAWN_HANDOFF_MS := 15 * 1000 +const SERVER_STATUS_PATH := "/godot-ai/status" +const SERVER_STATUS_PROBE_TIMEOUT_MS := 800 +const STARTUP_TRACE_COUNTER_NAMES := [ + "powershell", + "netstat", + "netsh", + "lsof", + "http_status_probe", + "server_command_discovery", +] + +## Untyped on purpose — see policy below. Type fences move to handler `_init` +## sites that take typed parameters. +## +## Self-update field and load-surface policy: plugin entry-load fields that +## survive reload stay untyped. Typed fields against plugin-defined classes +## were the #242 / #244 crash class: Godot can reparse a long-lived script +## while its old field storage and the new type shape disagree. Static-var +## initializers are the most dangerous form because they execute at +## script-load; a top-level typed Dictionary/Array storage change can fail +## before `_enter_tree` runs. +## +## The mitigation is two-part: +## (1) Field declarations are untyped (this block). +## (2) Construction and static access use local names declared at the top +## of the file (e.g. `Connection`, `Dispatcher`, `LogBuffer`, +## `ClientConfigurator`, `WindowsPortReservation`, ...), which keeps +## this entry script's load surface explicit and reviewable. +## +## Constructors, constants, and static methods on `Mcp*` classes are not the +## self-update safety metric under the single-phase runner. The old syntactic +## lint counted bare `Mcp*.MEMBER` references, but #398 was caused by the +## runner scanning a mixed old/new snapshot and reusing stale Script-object +## content. Bare names and preload aliases can both be parsed against stale +## content under an old two-phase runner; from the fixed runner onward the +## full v(N+1) snapshot is written before the scan. In short: preload aliases +## are not the self-update safety metric. +## +## `tests/unit/test_plugin_self_update_safety.py` locks this wording in. +## +var _connection +var _dispatcher +var _telemetry +var _log_buffer +var _game_log_buffer +var _editor_log_buffer +var _surfaced_error_tracker +var _editor_logger: Logger +var _dock +var _debugger_plugin +var _vision_routing +var _export_plugin +var _custom_tool_registry +var _custom_tool_service_locator +## Spawn / stop / adopt orchestration plus state machine; allocated in +## `_init` so test fixtures (which never enter the tree) can drive +## `_start_server`. Owns `_server_pid`, `_server_state`, the version- +## check seam, and the adoption-confirmation deadline — see +## `utils/server_lifecycle.gd`. +var _lifecycle +static var _server_started_this_session := false # guard against re-entrant spawns +static var _resolved_ws_port := ClientConfigurator.DEFAULT_WS_PORT +## True once a startup walk has published a port via `_set_resolved_ws_port` +## this editor session. Gates the `_enter_tree` pre-resolution seed: a fresh +## session seeds `_resolved_ws_port` from the configured EditorSettings +## value, but a plugin reload must keep the prior instance's published +## resolution, which can legitimately differ from the configured value +## (Windows-reservation remap, adopted-server record). +static var _ws_port_resolution_published := false +## Per-launch WS handshake auth token (#690). Static for the same reason as +## _resolved_ws_port: a plugin reload in the same editor session adopts the +## server the previous instance spawned, and must keep its token. Empty +## when this editor never spawned a token-carrying server (dev servers, +## fresh installs) — the handshake then omits the field. +static var _ws_auth_token := "" + +## Server-watch timer lives on the plugin because it's a Node — the +## manager is RefCounted and can't host children. +var _server_watch_timer: Timer = null +var _headless_disabled := false +var _startup_trace_enabled := false +var _startup_trace_start_ms := 0 +var _startup_trace_last_ms := 0 +var _startup_trace_counters: Dictionary = {} +## Startup-path probes can now run on a worker thread (#678); the trace +## counters they bump are shared with the main thread, so serialize. +var _startup_trace_mutex := Mutex.new() +var _startup_trace_netsh_start_count := 0 + + +func _init() -> void: + _lifecycle = ServerLifecycleManager.new(self) + + +func _enter_tree() -> void: + _startup_trace_begin() + + ## `_process` is only used by the adoption-confirmation watcher; keep + ## it off until `_watch_for_adoption_confirmation` arms it, so the + ## plugin has zero per-frame cost in the common case. + set_process(false) + + ## #740: register the export plugin BEFORE the headless guard so + ## `godot --headless --export-*` runs strip the game-helper autoload + ## from exported packs too — CI export pipelines are headless. The + ## export plugin is inert outside exports: no server, no sockets. + _export_plugin = ExportPlugin.new() + add_export_plugin(_export_plugin) + + if _mcp_disabled_for_headless_launch(): + _headless_disabled = true + print("MCP | plugin disabled in headless mode") + return + + ## Self-update extracts over the live addon and doesn't prune files that + ## disappeared from the new ZIP. Remove obsolete Logger-loader quarantine + ## files/folders once so upgraders match a fresh install. + _cleanup_legacy_logger_scripts() + + ## Register port overrides before spawn so `http_port()` / `ws_port()` + ## return the user's configured values (if any) when `_start_server` + ## builds the CLI args. + ClientConfigurator.ensure_settings_registered() + _startup_trace_phase("settings_registered") + + ## With the startup walk's blocking port resolution deferred to a worker + ## (#678), the Connection below dials before `_set_resolved_ws_port` + ## publishes. Seed the pre-resolution port from the configured + ## EditorSettings value (a cheap main-thread read, not a blocking probe) + ## so the first dial honors a `godot_ai/ws_port` override — without this + ## it targeted the compile-time default and the override only took + ## effect on the 1s retry. + _resolved_ws_port = _startup_ws_port_seed( + _ws_port_resolution_published, + _resolved_ws_port, + ClientConfigurator.ws_port(), + ) + + ## #691: pre-warm the env snapshot on the main thread before any worker + ## exists, so worker-thread env reads (dock refresh/action workers, the + ## #678 startup walk's discovery worker) serve from the snapshot and can + ## never race the spawn window's setenv/unsetenv around + ## OS.create_process. + ClientConfigurator.warm_env_snapshot() + + _log_buffer = LogBuffer.new() + ## Apply the persisted dock "Log" toggle before anything logs through the + ## buffer. Without this the choice only took effect after a manual toggle + ## and reset to noisy on every editor restart (#626). + _log_buffer.enabled = McpSettings.mcp_logging_enabled() + ## #678: in the real editor, run the startup path's blocking probes and + ## kill-drain waits off the main thread so a contended port can't freeze + ## plugin init/reload. Set here (not _init) so test fixtures — which + ## extend this plugin but never enter the tree — keep the synchronous + ## default and can call-then-assert. + _lifecycle.defer_blocking_work = true + ## A completed self-update means the user's Update click already + ## authorized replacing the previous-version backend. Armed BEFORE the + ## startup walk (a peek, not a drain — `_flush_pending_self_update_telemetry` + ## below still owns the read-and-clear) so the walk can weak-proof-kill + ## the stale server an attach bridge kept alive, and bounded retries + ## absorb the bridge-respawn port race, instead of latching INCOMPATIBLE + ## and waiting for a manual recovery click. + if _pending_self_update_succeeded(): + _lifecycle.authorize_stale_recovery() + _start_server() + _startup_trace_phase("server_start") + + _game_log_buffer = GameLogBuffer.new() + _editor_log_buffer = EditorLogBuffer.new() + _surfaced_error_tracker = SurfacedErrorTracker.new(_editor_log_buffer, _game_log_buffer) + _attach_editor_logger() + _dispatcher = Dispatcher.new(_log_buffer, _surfaced_error_tracker) + _dispatcher.mcp_logging = _log_buffer.enabled + _startup_trace_phase("core_objects") + + _connection = Connection.new() + _connection.log_buffer = _log_buffer + _connection.surfaced_error_tracker = _surfaced_error_tracker + _connection.ws_port = _resolved_ws_port + ## Restore the token before the first connect: after an editor restart + ## the static is empty but the managed-server record still names the + ## token the running server was spawned with (#690). A fresh spawn later + ## overwrites both via _set_ws_auth_token. + if _ws_auth_token.is_empty(): + _ws_auth_token = str(_read_managed_server_record().get("ws_token", "")) + _connection.auth_token = _ws_auth_token + ## Pause-depth restore boundary (#712): the dispatcher rebalances any + ## pause_processing level a crashed handler leaked. + _dispatcher.pause_target = _connection + _connection.connect_blocked = _lifecycle.is_connection_blocked() + _connection.connect_block_reason = _lifecycle.get_status_dict().get("message", "") + if ( + not _lifecycle.is_connection_blocked() + and not ServerStateScript.is_terminal_diagnosis(_lifecycle.get_state()) + ): + _arm_server_version_check() + ## Replay the custom-tool catalog on (re)connect so tools registered + ## before the initial connection or during a disconnect window reach + ## the server — send_event silently drops while _connected is false. + _connection.connection_state_changed.connect(_on_connection_state_changed) + + _telemetry = Telemetry.new(_connection) + + _debugger_plugin = DebuggerPlugin.new(_log_buffer, _game_log_buffer, _editor_log_buffer, _surfaced_error_tracker) + _vision_routing = VisionRoutingScript.new() + _vision_routing.log_buffer = _log_buffer + _debugger_plugin.vision_routing = _vision_routing + add_debugger_plugin(_debugger_plugin) + _connection.debugger_plugin = _debugger_plugin + _ensure_game_helper_autoload() + + ## Lazy handler registration (#736): declare each handler's script path + ## and constructor args, then map every command to (handler_key, method). + ## The dispatcher load()s + constructs a handler at the first dispatch of + ## one of its commands and caches the instance, so this block is the + ## authoritative command list without pulling any handler script into the + ## boot-time compile closure. Constructor args are captured now (they are + ## all plugin-lifetime objects) and released by _dispatcher.clear() in + ## _exit_tree. + var undo := get_undo_redo() + _dispatcher.register_lazy_handler("editor", HANDLERS_DIR + "editor_handler.gd", [_log_buffer, _connection, _debugger_plugin, _game_log_buffer, _editor_log_buffer, null, _surfaced_error_tracker, _vision_routing]) + _dispatcher.register_lazy_handler("scene", HANDLERS_DIR + "scene_handler.gd", [_connection]) + _dispatcher.register_lazy_handler("node", HANDLERS_DIR + "node_handler.gd", [undo]) + _dispatcher.register_lazy_handler("project", HANDLERS_DIR + "project_handler.gd", [_connection, _debugger_plugin, _editor_log_buffer]) + _dispatcher.register_lazy_handler( + "client", + HANDLERS_DIR + "client_handler.gd", + [_connection, ClientConfigurator.capture_launch_context()], + ) + _dispatcher.register_lazy_handler("script", HANDLERS_DIR + "script_handler.gd", [undo, _connection]) + _dispatcher.register_lazy_handler("resource", HANDLERS_DIR + "resource_handler.gd", [undo, _connection]) + _dispatcher.register_lazy_handler("api", HANDLERS_DIR + "api_handler.gd", []) + _dispatcher.register_lazy_handler("filesystem", HANDLERS_DIR + "filesystem_handler.gd", [_connection]) + _dispatcher.register_lazy_handler("signal", HANDLERS_DIR + "signal_handler.gd", [undo]) + _dispatcher.register_lazy_handler("autoload", HANDLERS_DIR + "autoload_handler.gd", []) + _dispatcher.register_lazy_handler("input", HANDLERS_DIR + "input_handler.gd", []) + _dispatcher.register_lazy_handler("test", HANDLERS_DIR + "test_handler.gd", [undo, _log_buffer, _dispatcher, _connection]) + _dispatcher.register_lazy_handler("batch", HANDLERS_DIR + "batch_handler.gd", [_dispatcher, undo]) + _dispatcher.register_lazy_handler("ui", HANDLERS_DIR + "ui_handler.gd", [undo]) + _dispatcher.register_lazy_handler("theme", HANDLERS_DIR + "theme_handler.gd", [undo, _connection]) + _dispatcher.register_lazy_handler("animation", HANDLERS_DIR + "animation_handler.gd", [undo]) + _dispatcher.register_lazy_handler("material", HANDLERS_DIR + "material_handler.gd", [undo, _connection]) + _dispatcher.register_lazy_handler("particle", HANDLERS_DIR + "particle_handler.gd", [undo]) + _dispatcher.register_lazy_handler("camera", HANDLERS_DIR + "camera_handler.gd", [undo]) + _dispatcher.register_lazy_handler("audio", HANDLERS_DIR + "audio_handler.gd", [undo]) + _dispatcher.register_lazy_handler("physics_shape", HANDLERS_DIR + "physics_shape_handler.gd", [undo]) + _dispatcher.register_lazy_handler("environment", HANDLERS_DIR + "environment_handler.gd", [undo, _connection]) + _dispatcher.register_lazy_handler("texture", HANDLERS_DIR + "texture_handler.gd", [undo, _connection]) + _dispatcher.register_lazy_handler("curve", HANDLERS_DIR + "curve_handler.gd", [undo, _connection]) + _dispatcher.register_lazy_handler("control_draw_recipe", HANDLERS_DIR + "control_draw_recipe_handler.gd", [undo]) + _dispatcher.register_lazy_handler("tilemap", HANDLERS_DIR + "tilemap_handler.gd", [undo]) + _dispatcher.register_lazy_handler("tileset", HANDLERS_DIR + "tileset_handler.gd", []) + _dispatcher.register_lazy_handler("gridmap", HANDLERS_DIR + "gridmap_handler.gd", [undo]) + _dispatcher.register_lazy_handler("csg", HANDLERS_DIR + "csg_handler.gd", [undo]) + + _dispatcher.register_lazy("get_editor_state", "editor", &"get_editor_state") + _dispatcher.register_lazy("get_scene_tree", "scene", &"get_scene_tree") + _dispatcher.register_lazy("get_open_scenes", "scene", &"get_open_scenes") + _dispatcher.register_lazy("find_nodes", "scene", &"find_nodes") + _dispatcher.register_lazy("create_scene", "scene", &"create_scene") + _dispatcher.register_lazy("open_scene", "scene", &"open_scene") + _dispatcher.register_lazy("save_scene", "scene", &"save_scene") + _dispatcher.register_lazy("save_scene_as", "scene", &"save_scene_as") + _dispatcher.register_lazy("get_selection", "editor", &"get_selection") + _dispatcher.register_lazy("create_node", "node", &"create_node") + _dispatcher.register_lazy("delete_node", "node", &"delete_node") + _dispatcher.register_lazy("reparent_node", "node", &"reparent_node") + _dispatcher.register_lazy("set_property", "node", &"set_property") + _dispatcher.register_lazy("rename_node", "node", &"rename_node") + _dispatcher.register_lazy("duplicate_node", "node", &"duplicate_node") + _dispatcher.register_lazy("move_node", "node", &"move_node") + _dispatcher.register_lazy("add_to_group", "node", &"add_to_group") + _dispatcher.register_lazy("remove_from_group", "node", &"remove_from_group") + _dispatcher.register_lazy("set_selection", "node", &"set_selection") + _dispatcher.register_lazy("get_node_properties", "node", &"get_node_properties") + _dispatcher.register_lazy("get_children", "node", &"get_children") + _dispatcher.register_lazy("get_groups", "node", &"get_groups") + _dispatcher.register_lazy("get_logs", "editor", &"get_logs") + _dispatcher.register_lazy("clear_logs", "editor", &"clear_logs") + _dispatcher.register_lazy("take_screenshot", "editor", &"take_screenshot") + _dispatcher.register_lazy("get_performance_monitors", "editor", &"get_performance_monitors") + _dispatcher.register_lazy("reload_plugin", "editor", &"reload_plugin") + _dispatcher.register_lazy("quit_editor", "editor", &"quit_editor") + _dispatcher.register_lazy("game_eval", "editor", &"game_eval") + _dispatcher.register_lazy("game_command", "editor", &"game_command") + _dispatcher.register_lazy("get_project_setting", "project", &"get_project_setting") + _dispatcher.register_lazy("set_project_setting", "project", &"set_project_setting") + _dispatcher.register_lazy("run_project", "project", &"run_project") + _dispatcher.register_lazy("stop_project", "project", &"stop_project") + _dispatcher.register_lazy("search_filesystem", "project", &"search_filesystem") + _dispatcher.register_lazy("configure_client", "client", &"configure_client") + _dispatcher.register_lazy("remove_client", "client", &"remove_client") + _dispatcher.register_lazy("check_client_status", "client", &"check_client_status") + _dispatcher.register_lazy("create_script", "script", &"create_script") + _dispatcher.register_lazy("patch_script", "script", &"patch_script") + _dispatcher.register_lazy("read_script", "script", &"read_script") + _dispatcher.register_lazy("attach_script", "script", &"attach_script") + _dispatcher.register_lazy("detach_script", "script", &"detach_script") + _dispatcher.register_lazy("find_symbols", "script", &"find_symbols") + _dispatcher.register_lazy("search_resources", "resource", &"search_resources") + _dispatcher.register_lazy("load_resource", "resource", &"load_resource") + _dispatcher.register_lazy("assign_resource", "resource", &"assign_resource") + _dispatcher.register_lazy("create_resource", "resource", &"create_resource") + _dispatcher.register_lazy("get_resource_info", "resource", &"get_resource_info") + _dispatcher.register_lazy("get_class_info", "api", &"get_class_info") + _dispatcher.register_lazy("read_file", "filesystem", &"read_file") + _dispatcher.register_lazy("write_file", "filesystem", &"write_file") + _dispatcher.register_lazy("reimport", "filesystem", &"reimport") + _dispatcher.register_lazy("scan_filesystem", "filesystem", &"scan_filesystem") + _dispatcher.register_lazy("list_signals", "signal", &"list_signals") + _dispatcher.register_lazy("connect_signal", "signal", &"connect_signal") + _dispatcher.register_lazy("disconnect_signal", "signal", &"disconnect_signal") + _dispatcher.register_lazy("list_autoloads", "autoload", &"list_autoloads") + _dispatcher.register_lazy("add_autoload", "autoload", &"add_autoload") + _dispatcher.register_lazy("remove_autoload", "autoload", &"remove_autoload") + _dispatcher.register_lazy("list_actions", "input", &"list_actions") + _dispatcher.register_lazy("add_action", "input", &"add_action") + _dispatcher.register_lazy("ensure_action", "input", &"ensure_action") + _dispatcher.register_lazy("remove_action", "input", &"remove_action") + _dispatcher.register_lazy("bind_event", "input", &"bind_event") + _dispatcher.register_lazy("ensure_binding", "input", &"ensure_binding") + _dispatcher.register_lazy("run_tests", "test", &"run_tests") + _dispatcher.register_lazy("get_test_results", "test", &"get_test_results") + _dispatcher.register_lazy("batch_execute", "batch", &"batch_execute") + _dispatcher.register_lazy("set_anchor_preset", "ui", &"set_anchor_preset") + _dispatcher.register_lazy("set_text", "ui", &"set_text") + _dispatcher.register_lazy("build_layout", "ui", &"build_layout") + _dispatcher.register_lazy("create_theme", "theme", &"create_theme") + _dispatcher.register_lazy("theme_set_color", "theme", &"set_color") + _dispatcher.register_lazy("theme_set_constant", "theme", &"set_constant") + _dispatcher.register_lazy("theme_set_font_size", "theme", &"set_font_size") + _dispatcher.register_lazy("theme_set_stylebox_flat", "theme", &"set_stylebox_flat") + _dispatcher.register_lazy("apply_theme", "theme", &"apply_theme") + _dispatcher.register_lazy("animation_player_create", "animation", &"create_player") + _dispatcher.register_lazy("animation_create", "animation", &"create_animation") + _dispatcher.register_lazy("animation_add_property_track", "animation", &"add_property_track") + _dispatcher.register_lazy("animation_add_method_track", "animation", &"add_method_track") + _dispatcher.register_lazy("animation_set_autoplay", "animation", &"set_autoplay") + _dispatcher.register_lazy("animation_play", "animation", &"play") + _dispatcher.register_lazy("animation_stop", "animation", &"stop") + _dispatcher.register_lazy("animation_list", "animation", &"list_animations") + _dispatcher.register_lazy("animation_get", "animation", &"get_animation") + _dispatcher.register_lazy("animation_create_simple", "animation", &"create_simple") + _dispatcher.register_lazy("animation_delete", "animation", &"delete_animation") + _dispatcher.register_lazy("animation_validate", "animation", &"validate_animation") + _dispatcher.register_lazy("animation_preset_fade", "animation", &"preset_fade") + _dispatcher.register_lazy("animation_preset_slide", "animation", &"preset_slide") + _dispatcher.register_lazy("animation_preset_shake", "animation", &"preset_shake") + _dispatcher.register_lazy("animation_preset_pulse", "animation", &"preset_pulse") + _dispatcher.register_lazy("material_create", "material", &"create_material") + _dispatcher.register_lazy("material_set_param", "material", &"set_param") + _dispatcher.register_lazy("material_set_shader_param", "material", &"set_shader_param") + _dispatcher.register_lazy("material_get", "material", &"get_material") + _dispatcher.register_lazy("material_list", "material", &"list_materials") + _dispatcher.register_lazy("material_assign", "material", &"assign_material") + _dispatcher.register_lazy("material_apply_to_node", "material", &"apply_to_node") + _dispatcher.register_lazy("material_apply_preset", "material", &"apply_preset") + _dispatcher.register_lazy("particle_create", "particle", &"create_particle") + _dispatcher.register_lazy("particle_set_main", "particle", &"set_main") + _dispatcher.register_lazy("particle_set_process", "particle", &"set_process") + _dispatcher.register_lazy("particle_set_draw_pass", "particle", &"set_draw_pass") + _dispatcher.register_lazy("particle_restart", "particle", &"restart_particle") + _dispatcher.register_lazy("particle_get", "particle", &"get_particle") + _dispatcher.register_lazy("particle_apply_preset", "particle", &"apply_preset") + _dispatcher.register_lazy("camera_create", "camera", &"create_camera") + _dispatcher.register_lazy("camera_configure", "camera", &"configure") + _dispatcher.register_lazy("camera_set_limits_2d", "camera", &"set_limits_2d") + _dispatcher.register_lazy("camera_set_damping_2d", "camera", &"set_damping_2d") + _dispatcher.register_lazy("camera_follow_2d", "camera", &"follow_2d") + _dispatcher.register_lazy("camera_get", "camera", &"get_camera") + _dispatcher.register_lazy("camera_list", "camera", &"list_cameras") + _dispatcher.register_lazy("camera_apply_preset", "camera", &"apply_preset") + _dispatcher.register_lazy("audio_player_create", "audio", &"create_player") + _dispatcher.register_lazy("audio_player_set_stream", "audio", &"set_stream") + _dispatcher.register_lazy("audio_player_set_playback", "audio", &"set_playback") + _dispatcher.register_lazy("audio_play", "audio", &"play") + _dispatcher.register_lazy("audio_stop", "audio", &"stop") + _dispatcher.register_lazy("audio_list", "audio", &"list_streams") + _dispatcher.register_lazy("physics_shape_autofit", "physics_shape", &"autofit") + _dispatcher.register_lazy("environment_create", "environment", &"create_environment") + _dispatcher.register_lazy("gradient_texture_create", "texture", &"create_gradient_texture") + _dispatcher.register_lazy("noise_texture_create", "texture", &"create_noise_texture") + _dispatcher.register_lazy("curve_set_points", "curve", &"set_points") + _dispatcher.register_lazy("control_draw_recipe", "control_draw_recipe", &"control_draw_recipe") + _dispatcher.register_lazy("tilemap_set_cell", "tilemap", &"set_cell") + _dispatcher.register_lazy("tilemap_set_cells_rect", "tilemap", &"set_cells_rect") + _dispatcher.register_lazy("tilemap_clear", "tilemap", &"clear_layer") + _dispatcher.register_lazy("tilemap_get_cells", "tilemap", &"get_used_cells") + _dispatcher.register_lazy("tileset_get_atlas_tiles", "tileset", &"get_atlas_tiles") + _dispatcher.register_lazy("tileset_get_atlas_image", "tileset", &"get_atlas_image") + _dispatcher.register_lazy("gridmap_set_item", "gridmap", &"set_item") + _dispatcher.register_lazy("gridmap_fill", "gridmap", &"fill") + _dispatcher.register_lazy("gridmap_clear", "gridmap", &"clear_layer") + _dispatcher.register_lazy("gridmap_get_used_cells", "gridmap", &"get_used_cells") + _dispatcher.register_lazy("gridmap_list_library_items", "gridmap", &"list_library_items") + _dispatcher.register_lazy("csg_create", "csg", &"create") + _dispatcher.register_lazy("csg_set_operation", "csg", &"set_operation") + + _connection.dispatcher = _dispatcher + add_child(_connection) + _startup_trace_phase("handlers_registered") + + # Custom tool registry + _custom_tool_service_locator = McpServiceLocator.new() + _custom_tool_service_locator.setup(_connection, _log_buffer) + _custom_tool_registry = McpToolRegistry.new() + _custom_tool_registry.setup(_dispatcher, _custom_tool_service_locator) + _custom_tool_registry.tools_changed.connect(_on_custom_tools_changed) + _custom_tool_registry.mark_ready() + _startup_trace_phase("custom_tools_ready") + + # Dock panel + _dock = Dock.new() + _dock.vision_routing = _vision_routing + _dock.name = "Godot AI" + _dock.setup(_connection, _log_buffer, self) + add_control_to_dock(DOCK_SLOT_RIGHT_BL, _dock) + _startup_trace_phase("dock_attached") + + _log_buffer.log("plugin loaded") + if _telemetry != null: + _telemetry.record_dock_startup() + _flush_pending_self_update_telemetry() + _telemetry.flush_pending_plugin_reload() + ## The startup-trace 'done' line is stamped by _start_server after the + ## (possibly suspended) walk completes — not here (#682 review). + + +## Public wrapper around the dev-server-toggle telemetry emit. Lets the +## dock (or any other caller) record without reaching into ``_telemetry`` +## directly — keeps the plugin's internal field encapsulated. The dev +## server is a Python subprocess unrelated to the plugin's own +## lifecycle, so emission can be synchronous (no EditorSettings persist +## dance like ``plugin_reload`` / ``self_update``). +func record_dev_server_toggle(action: String) -> void: + if _telemetry == null: + return + _telemetry.record_dev_server_toggle(action) + + +## Non-draining read of the runner's pending self-update marker. Peeked +## before `_start_server` (the drain in `_flush_pending_self_update_telemetry` +## runs later, after the dock attaches) so the startup walk knows an update +## just completed. Only a `status == "success"` marker counts: a failed +## install left the OLD plugin version enabled, and killing a same-version +## backend is not this path's business. +func _pending_self_update_succeeded() -> bool: + var settings := EditorInterface.get_editor_settings() + if settings == null: + return false + var key := UPDATE_RELOAD_RUNNER_SCRIPT.PENDING_SELF_UPDATE_TELEMETRY_KEY + if not settings.has_setting(key): + return false + var raw := str(settings.get_setting(key)) + if raw.is_empty(): + return false + var parsed = JSON.parse_string(raw) + if typeof(parsed) != TYPE_DICTIONARY: + return false + return str(parsed.get("status", "")) == "success" + + +## Drain any self_update event written by `update_reload_runner` during the +## previous disable -> enable window. +func _flush_pending_self_update_telemetry() -> void: + var key := UPDATE_RELOAD_RUNNER_SCRIPT.PENDING_SELF_UPDATE_TELEMETRY_KEY + var parsed = Telemetry._drain_editor_setting_dict(key) + if parsed == null: + return + var status := str(parsed.get("status", "unknown")) + var error := str(parsed.get("error", "")) + ## Positional args: GDScript doesn't support keyword args in calls + ## (unlike Python). from/to versions ride the marker since the repin + ## gate landed; markers written by older runners simply lack them. + var from_version := str(parsed.get("from_version", "")) + var to_version := str(parsed.get("to_version", "")) + _telemetry.record_self_update(status, from_version, to_version, error) + ## After a successful update, previously-configured client entries still + ## pin the old server version; arm the dock's one-shot auto-repin so its + ## first healthy status sweep rewrites them without the user having to + ## click through the drift banner. The dock repins ONLY entries whose + ## sole drift is the old version pin — it needs `from_version` to render + ## that comparison, so a marker from an older runner (no version fields) + ## arms nothing and the drift banner stays the manual path. `has_method` + ## (not a typed call): the dock script is one of the files the update + ## just overwrote, and the untyped-reference convention applies across + ## that boundary. + if status == "success" and _dock != null and _dock.has_method("notify_self_update_success"): + _dock.notify_self_update_success(from_version) + + + + +func _exit_tree() -> void: + ## Registered before the headless guard in _enter_tree, so it must be + ## removed before the headless early-return here too. + if _export_plugin != null: + remove_export_plugin(_export_plugin) + _export_plugin = null + + if _headless_disabled: + _server_started_this_session = false + _headless_disabled = false + return + + if _custom_tool_registry != null: + _custom_tool_registry.clear() + _custom_tool_registry = null + + _custom_tool_service_locator = null + + ## Outer-to-inner teardown. Dispatcher Callables hold RefCounted handlers + ## alive past the point where Godot reloads their class_name scripts — the + ## first post-reload call into a typed-array-holding handler (e.g. + ## McpGameLogBuffer._storage) then SIGSEGVs against a stale class descriptor. + ## See issue #46. + + # Stop inbound work first so _process can't enqueue new commands or + # null-deref log_buffer on the next tick mid-teardown. + if _connection: + _connection.teardown() + + # Drop the dispatcher's Callables AND its lazily-constructed handler + # instances (#736: handlers live in the dispatcher's cache now). Handler + # destructors run here, while their scripts are still loaded. + if _dispatcher: + _dispatcher.clear() + if _vision_routing: + _vision_routing.shutdown() + _vision_routing = null + + if _dock: + remove_control_from_docks(_dock) + _dock.queue_free() + _dock = null + if _connection: + _connection.queue_free() + _connection = null + if _debugger_plugin: + remove_debugger_plugin(_debugger_plugin) + _debugger_plugin = null + + ## Detach the editor logger BEFORE nulling the buffer. After remove_logger + ## returns, Godot guarantees no further virtual calls — so the logger's + ## next access to `_buffer` (if any in flight) lands on a still-live + ## ref-counted buffer, not a freed one. + _detach_editor_logger() + + _dispatcher = null + _log_buffer = null + _game_log_buffer = null + _editor_log_buffer = null + _surfaced_error_tracker = null + + ## keep_server_on_exit (#800): the manager routes on the spawn-time + ## keep-alive flag (persisted in the managed-server record), NOT the + ## live setting — detach leaves the server for the next session (or a + ## same-session disable/enable cycle) to adopt. Explicit stops (dock + ## Restart, update reload) still kill via _stop_server. + _lifecycle.teardown_for_editor_exit() + ## Symmetric with prepare_for_update_reload: the static guard persists + ## across disable/enable within a single editor session, so the re-enabled + ## plugin instance's _start_server would short-circuit and never respawn. + ## Pre-#159 this was masked — the old kill path usually left Python alive + ## and the new instance adopted it on port 8000. Now that _stop_server is + ## deterministic, nothing is left to adopt and the reload hangs. + _server_started_this_session = false + print("MCP | plugin unloaded") + + +## Attach editor_logger.gd as a Godot logger so editor-process script +## errors (parse errors, @tool runtime errors, EditorPlugin errors, +## push_error/push_warning) flow into _editor_log_buffer for +## logs_read(source="editor"). +## +## Limitation called out in the issue: parse errors fired *before* the +## plugin's _enter_tree (e.g. during the editor's initial filesystem +## scan, or for scripts that fail on first project open) happen before +## add_logger is called and are not captured. There's no public API to +## drain the editor's already-emitted error history; rescanning the +## file would re-emit them but at the cost of disrupting the user's +## editing state, so we accept the gap. +func _attach_editor_logger() -> void: + _editor_logger = EditorLogger.new(_editor_log_buffer) + OS.add_logger(_editor_logger) + + +## Remove old Logger-quarantine artifacts left by extract-over-live +## self-update. Idempotent: existence-guarded, so it's a no-op on fresh +## installs and symlinked dev checkouts. +func _cleanup_legacy_logger_scripts() -> void: + var legacy_files := [ + "res://addons/godot_ai/runtime/logger_loader.gd", + "res://addons/godot_ai/runtime/logger_loader.gd.uid", + "res://addons/godot_ai/testing/script_error_capture_loader.gd", + "res://addons/godot_ai/testing/script_error_capture_loader.gd.uid", + ] + for res_path in legacy_files: + if FileAccess.file_exists(res_path): + DirAccess.remove_absolute(ProjectSettings.globalize_path(res_path)) + var legacy_dirs := [ + "res://addons/godot_ai/runtime/loggers", + "res://addons/godot_ai/testing/loggers", + ] + for res_path in legacy_dirs: + var absolute := ProjectSettings.globalize_path(res_path) + if DirAccess.dir_exists_absolute(absolute): + _remove_dir_recursive_absolute(absolute) + + +static func _remove_dir_recursive_absolute(path: String) -> void: + var dir := DirAccess.open(path) + if dir == null: + return + dir.list_dir_begin() + var name := dir.get_next() + while not name.is_empty(): + var child := path.path_join(name) + if dir.current_is_dir(): + _remove_dir_recursive_absolute(child) + else: + DirAccess.remove_absolute(child) + name = dir.get_next() + dir.list_dir_end() + DirAccess.remove_absolute(path) + + +func _detach_editor_logger() -> void: + if _editor_logger != null: + OS.remove_logger(_editor_logger) + _editor_logger = null + + +## Register the game-side autoload on plugin enable. Runs the helper inside +## the game process so the editor-side debugger plugin can request +## framebuffer captures over EngineDebugger messages. Removed on +## _disable_plugin so disabling the plugin leaves project.godot clean. +func _enable_plugin() -> void: + if _mcp_disabled_for_headless_launch(): + return + _ensure_game_helper_autoload() + + +static func _mcp_disabled_for_headless_launch() -> bool: + return _mcp_disabled_for_headless( + OS.get_cmdline_args(), + DisplayServer.get_name(), + OS.get_environment("GODOT_AI_ALLOW_HEADLESS") + ) + + +static func _mcp_disabled_for_headless(args: PackedStringArray, display_name: String, allow_value: String) -> bool: + if McpSettings.truthy(allow_value): + return false + return _args_request_headless(args) or display_name.to_lower() == "headless" + + +static func _args_request_headless(args: PackedStringArray) -> bool: + for i in range(args.size()): + var arg := args[i] + if arg == "--headless": + return true + if arg == "--display-driver" and i + 1 < args.size() and args[i + 1] == "headless": + return true + if arg.begins_with("--display-driver=") and arg.get_slice("=", 1) == "headless": + return true + return false + + + + +func _disable_plugin() -> void: + var key := "autoload/" + GAME_HELPER_AUTOLOAD_NAME + if not ProjectSettings.has_setting(key): + return + ProjectSettings.clear(key) + ProjectSettings.save() + + +func _ensure_game_helper_autoload() -> void: + ## Write the autoload directly to ProjectSettings and save immediately. + ## EditorPlugin.add_autoload_singleton only mutates in-memory settings — + ## the on-disk project.godot is only persisted when the editor saves + ## (e.g. on quit). CI spawns the game subprocess before any save fires, + ## so the child process never sees the autoload and the capture times + ## out. Mirror AutoloadHandler's pattern: set_setting + save(). + var key := "autoload/" + GAME_HELPER_AUTOLOAD_NAME + var value := "*" + GAME_HELPER_AUTOLOAD_PATH # "*" prefix = singleton + if ProjectSettings.get_setting(key, "") == value: + return ## already registered with the right target + ProjectSettings.set_setting(key, value) + ProjectSettings.set_initial_value(key, "") + ProjectSettings.set_as_basic(key, true) + var err := ProjectSettings.save() + if err != OK: + push_warning("MCP: failed to save project.godot after registering %s autoload (error %d)" + % [GAME_HELPER_AUTOLOAD_NAME, err]) + + +func _startup_trace_begin() -> void: + _startup_trace_enabled = ClientConfigurator.startup_trace_enabled() + if not _startup_trace_enabled: + return + _startup_trace_start_ms = Time.get_ticks_msec() + _startup_trace_last_ms = _startup_trace_start_ms + _startup_trace_netsh_start_count = WindowsPortReservation.netsh_query_count() + _startup_trace_counters.clear() + for counter in STARTUP_TRACE_COUNTER_NAMES: + _startup_trace_counters[counter] = 0 + print( + "MCP startup trace | begin platform=%s http_port=%d ws_port=%d" + % [ + OS.get_name(), + ClientConfigurator.http_port(), + ClientConfigurator.ws_port(), + ] + ) + + +func _startup_trace_count(counter: String, amount: int = 1) -> void: + if not _startup_trace_enabled: + return + _startup_trace_mutex.lock() + _startup_trace_counters[counter] = int(_startup_trace_counters.get(counter, 0)) + amount + _startup_trace_mutex.unlock() + + +func _startup_trace_phase(name: String) -> void: + if not _startup_trace_enabled: + return + var now := Time.get_ticks_msec() + print( + "MCP startup trace | phase=%s delta_ms=%d total_ms=%d" + % [name, now - _startup_trace_last_ms, now - _startup_trace_start_ms] + ) + _startup_trace_last_ms = now + + +func _startup_trace_finish(path: String) -> void: + if not _startup_trace_enabled: + return + var now := Time.get_ticks_msec() + ## Same lock as _startup_trace_count — a worker probe may still be + ## bumping counters while this reads/writes the shared dictionary. + _startup_trace_mutex.lock() + _startup_trace_counters["netsh"] = ( + WindowsPortReservation.netsh_query_count() - _startup_trace_netsh_start_count + ) + var counters_snapshot: Dictionary = _startup_trace_counters.duplicate() + _startup_trace_mutex.unlock() + print( + "MCP startup trace | done path=%s total_ms=%d counters=%s" + % [path, now - _startup_trace_start_ms, str(counters_snapshot)] + ) + + +func _start_server() -> void: + ## Fire-and-forget: the walk is a coroutine in production (#678). Its + ## completion continuation must NOT live in this method — a reload can + ## free this plugin while the walk is suspended, and resuming a freed + ## Node's coroutine errors out. The manager calls + ## `_finish_startup_trace_after_walk` on walk completion instead, + ## guarded by is_instance_valid. + _lifecycle.start_server() + + +## Called by the lifecycle manager when the (possibly suspended) startup +## walk completes — the point where the real startup outcome is known, so +## the trace 'done' line reports the true contended-port path and duration +## instead of a pre-walk placeholder (#682 review). +func _finish_startup_trace_after_walk() -> void: + var startup_path: String = str(_lifecycle.get_startup_path()) + _startup_trace_finish(startup_path if not startup_path.is_empty() else "loaded") + + +## Test-fixture shim — characterization tests in test_plugin_lifecycle +## reach for this instance method directly. Delegates to the manager's +## state-owning copy. +func _set_incompatible_server(live: Dictionary, expected_version: String, port: int) -> void: + _lifecycle._set_incompatible_server(live, expected_version, port) + + +## Static shim — kept on the plugin class because the characterization +## tests assert against `GodotAiPlugin._incompatible_server_message`. +## Implementation moved to ServerLifecycleManager. +static func _incompatible_server_message( + live: Dictionary, + expected_version: String, + port: int, + expected_ws_port: int +) -> String: + return ServerLifecycleManager._incompatible_server_message( + live, expected_version, port, expected_ws_port + ) + + +static func _server_version_compatibility( + actual_version: String, expected_version: String +) -> Dictionary: + return ServerLifecycleManager._server_version_compatibility( + actual_version, expected_version + ) + + +static func _server_status_compatibility( + actual_version: String, + expected_version: String, + actual_ws_port: int, + expected_ws_port: int, +) -> Dictionary: + return ServerLifecycleManager._server_status_compatibility( + actual_version, expected_version, actual_ws_port, expected_ws_port + ) + + +static func _managed_record_has_version_drift(record_version: String, current_version: String) -> bool: + return ServerLifecycleManager._managed_record_has_version_drift(record_version, current_version) + + +static func _probe_live_server_status(port: int, timeout_ms: int = SERVER_STATUS_PROBE_TIMEOUT_MS) -> Dictionary: + var result := { + "reachable": false, + "version": "", + "name": "", + "ws_port": 0, + "status_code": 0, + "error": "", + } + var client := HTTPClient.new() + var err := client.connect_to_host("127.0.0.1", port) + if err != OK: + result["error"] = "connect_%d" % err + return result + var deadline := Time.get_ticks_msec() + timeout_ms + while client.get_status() == HTTPClient.STATUS_RESOLVING or client.get_status() == HTTPClient.STATUS_CONNECTING: + client.poll() + if Time.get_ticks_msec() >= deadline: + result["error"] = "connect_timeout" + return result + OS.delay_msec(10) + if client.get_status() != HTTPClient.STATUS_CONNECTED: + result["error"] = "connect_status_%d" % client.get_status() + return result + err = client.request(HTTPClient.METHOD_GET, SERVER_STATUS_PATH, ["Accept: application/json"]) + if err != OK: + result["error"] = "request_%d" % err + return result + var body := PackedByteArray() + while true: + var status := client.get_status() + if status == HTTPClient.STATUS_REQUESTING: + client.poll() + elif status == HTTPClient.STATUS_BODY: + client.poll() + var chunk := client.read_response_body_chunk() + if chunk.size() > 0: + body.append_array(chunk) + elif status == HTTPClient.STATUS_CONNECTED: + break + else: + result["error"] = "response_status_%d" % status + return result + if Time.get_ticks_msec() >= deadline: + result["error"] = "response_timeout" + return result + OS.delay_msec(10) + var response_code := client.get_response_code() + result["status_code"] = response_code + if response_code != 200: + result["error"] = "http_%d" % response_code + return result + var parsed = JSON.parse_string(body.get_string_from_utf8()) + if not (parsed is Dictionary): + result["error"] = "invalid_json" + return result + result.merge(_project_status_payload(parsed), true) + return result + + +## Project a parsed `/godot-ai/status` body into the probe's result shape. +## +## Extracted from the probe so it can be tested against a real payload. The +## probe is a whitelist — a field the server publishes does not reach callers +## unless it is copied here — and that is silent: the consumer just sees a +## missing key. #824's lease check shipped reading `active_lease_count` while +## this projection dropped it, so the branch was dead on every platform, and +## the tests could not see it because they hand-built the result dict this +## function is supposed to produce. Add new fields here, and cover them with a +## projection test rather than a fabricated `live_status`. +static func _project_status_payload(parsed: Dictionary) -> Dictionary: + var projected := { + "reachable": true, + "name": str(parsed.get("name", "")), + "version": _extract_server_version(parsed), + "ws_port": int(parsed.get("ws_port", 0)), + ## `package_path` was added in v2.4.4 (#416) so the dock's + ## "Incompatible server" banner can name the source of a version + ## skew. Older servers omit it; treat the missing field as "". + "package_path": str(parsed.get("package_path", "")), + } + ## #824: advisory attach-lease count, consumed by teardown to decide + ## detach-vs-kill. Absent stays absent rather than defaulting to 0, so + ## `ServerLifecycleManager.active_lease_count` keeps distinguishing "backend + ## too old to publish this" from "backend reports zero leases" — both stop + ## the server, but only one of them is a compatibility statement. + ## Anything that is not a finite whole number is dropped, for the same + ## reason the value is clamped downstream: a malformed count must not read + ## as occupancy and keep a server alive. Godot parses every JSON number as + ## a float, so the whole-number test is what distinguishes a real count + ## from junk — truncating 1.5 to 1 would manufacture a held lease. + var raw: Variant = parsed.get("active_lease_count") + if raw is int or raw is float: + var numeric := float(raw) + if is_finite(numeric) and numeric == floor(numeric): + projected["active_lease_count"] = int(numeric) + return projected + + +func _probe_live_server_status_for_port(port: int) -> Dictionary: + _startup_trace_count("http_status_probe") + return _probe_live_server_status(port) + + +static func _extract_server_version(payload: Dictionary) -> String: + var version := str(payload.get("server_version", "")) + if version.is_empty(): + version = str(payload.get("version", "")) + return version + + +static func _live_status_identifies_godot_ai(live: Dictionary) -> bool: + return ServerLifecycleManager._live_status_identifies_godot_ai(live) + + +func _verified_status_version(live: Dictionary) -> String: + if not ServerLifecycleManager._live_status_identifies_godot_ai(live): + return "" + return str(live.get("version", "")) + + +func _verified_status_ws_port(live: Dictionary) -> int: + if not ServerLifecycleManager._live_status_identifies_godot_ai(live): + return 0 + return int(live.get("ws_port", 0)) + + +func _refresh_dock_client_statuses() -> bool: + if _dock == null: + return false + if not _dock.has_method("_refresh_all_client_statuses"): + return false + _dock.call("_refresh_all_client_statuses") + return true + + +## Test-fixture shim — characterization tests in test_plugin_lifecycle +## still drive the first-writer-wins terminal-diagnosis behaviour through +## this method. Delegates to the manager's `set_terminal_diagnosis` +## (which preserves the same first-writer-wins contract). +func _set_spawn_state(state: int) -> void: + _lifecycle.set_terminal_diagnosis(state) + + +## Arm the one-shot connection watcher. Called from `_start_server`'s +## FOREIGN_PORT branch: we flagged the diagnostic preemptively assuming +## the port holder doesn't speak MCP, but if it turns out to be another +## editor's server our WebSocket will open and we need to retract the +## diagnostic. +## +## We intentionally poll `_connection.is_connected` from `_process` +## instead of wiring a new signal on McpConnection. A signal added in the +## same release as a new consumer would be another shape-coupled update: +## old two-phase runners can parse the consumer while the McpConnection +## Script object still reflects v(N). Polling only reads `is_connected` +## (present on every shipped McpConnection), so old-runner upgrade windows +## do not depend on a same-release signal addition. +## +## The watch self-disarms after SPAWN_GRACE_MS so per-frame cost drops +## back to zero if it is ever armed by a legacy adoption path. +func _watch_for_adoption_confirmation() -> void: + _lifecycle.arm_adoption_watch() + _update_process_enabled() + + +func _arm_server_version_check() -> void: + ## `arm_version_check` resolves an empty expected via the plugin + ## version, so we can pass the raw field value through. + _lifecycle.arm_version_check(_connection, str(_lifecycle._server_expected_version)) + _update_process_enabled() + + +func _update_process_enabled() -> void: + if _lifecycle == null: + set_process(false) + return + set_process( + _lifecycle.get_adoption_watch_deadline_ms() > 0 + or _lifecycle.is_awaiting_server_version() + ) + + +func _process(_delta: float) -> void: + ## Guard: during script-reload / dual-plugin enable races `_lifecycle` + ## can be null while process is still armed — spam would otherwise flood + ## the Output dock every frame. + if _lifecycle == null: + set_process(false) + return + var now := Time.get_ticks_msec() + var version_check = _lifecycle.get_version_check() + if version_check != null: + version_check.tick(now) + _lifecycle.tick_adoption_watch(now) + _update_process_enabled() + + +## A WebSocket opening only proves the occupant speaks enough of the editor +## protocol to accept a session. Compatibility is decided by the server +## version in `handshake_ack`, so this only arms that check. +func _on_connection_established() -> void: + if _lifecycle.get_state() == ServerStateScript.FOREIGN_PORT: + _arm_server_version_check() + + +## Test-fixture shim — characterization tests poke the verified path +## directly. Delegates to the version-check seam; the manager resolves +## an empty expected version via `_resolve_expected_version`. +func _on_server_version_verified(version: String) -> void: + _lifecycle.handle_server_version_verified( + str(_lifecycle._server_expected_version), version + ) + _update_process_enabled() + + +## Test-fixture shim — same shape as `_on_server_version_verified`. +func _on_server_version_unverified() -> void: + _lifecycle.handle_server_version_unverified( + str(_lifecycle._server_expected_version) + ) + _update_process_enabled() + + +## Start a 1s-tick timer that watches the spawned server through its cold-start +## window, then for SERVER_WATCH_MS after pid-file publication. If the process +## dies inside the active window we drain the captured pipes and mark the server +## as crashed so the dock can surface what went wrong. After the window expires +## we close the pipes so they don't pin file descriptors or fill their kernel +## buffers. See #146 and #896. +func _start_server_watch() -> void: + _stop_server_watch() + _server_watch_timer = Timer.new() + _server_watch_timer.wait_time = 1.0 + _server_watch_timer.one_shot = false + _server_watch_timer.timeout.connect(_check_server_health) + add_child(_server_watch_timer) + _server_watch_timer.start() + + +func _stop_server_watch() -> void: + if _server_watch_timer != null: + _server_watch_timer.stop() + _server_watch_timer.queue_free() + _server_watch_timer = null + + +func _check_server_health() -> void: + _lifecycle.check_server_health() + + +## True when the first spawn looks like a stale-uvx-index failure and we +## haven't already retried. Fail signal: launcher process already declared +## dead by the caller, pid-file was never written (Python never got to +## argparse), and we're on the uvx tier (the only tier where `--refresh` +## means anything). Bug #172 — after a fresh PyPI publish, uvx's local +## index metadata keeps saying the new version doesn't exist for ~10 min, +## which cascaded into an infinite reconnect loop pre-#171. Retry-at-spawn +## catches every entry path (Update, Reload Plugin, Reconnect, editor +## restart, crash recovery) — unlike the older Update-only precheck. +func _should_retry_with_refresh() -> bool: + return _retry_with_refresh_allowed( + _lifecycle._refresh_retried, + ClientConfigurator.get_server_launch_mode(), + _read_pid_file(), + ) + + +## Pure decision helper — environment-state readers stay in the instance +## method above, the logic lives here so tests can drive the three inputs +## directly without spoofing static caches or pid-files on disk. +static func _retry_with_refresh_allowed(already_retried: bool, launch_mode: String, pid_from_file: int) -> bool: + return ( + not already_retried + and launch_mode == "uvx" + and pid_from_file == 0 + ) + + +func _respawn_with_refresh() -> void: + _lifecycle.respawn_with_refresh() + + +## Snapshot of the server-spawn outcome for the dock. +## +## `state` is one of the `McpServerState.*` int constants; the dock owns +## the UI copy per state via its own `_crash_body_for_state`. `exit_ms` +## is only meaningful for `CRASHED`. +func get_server_status() -> Dictionary: + return _lifecycle.get_status_dict() + + +## Diagnostic accessor for the dock's ownership label. Positive = a PID this +## plugin instance spawned (or re-acquired via the managed record); -1 = an +## adopted external/attach-owned backend. Display only — adoption transfers +## end-of-life responsibility, so this value is never kill proof (#669). +func get_server_pid() -> int: + return _lifecycle.get_server_pid() + + +func get_resolved_ws_port() -> int: + return _resolved_ws_port + + +func _set_resolved_ws_port(port: int) -> void: + _ws_port_resolution_published = true + _resolved_ws_port = port + if _connection != null: + _connection.ws_port = port + + +## Pure decision helper — environment-state reads (the published flag, the +## EditorSettings port) stay in `_enter_tree`; the logic lives here so tests +## can drive the three inputs directly without mutating the shared statics. +static func _startup_ws_port_seed( + resolution_published: bool, + session_ws_port: int, + configured_ws_port: int +) -> int: + return session_ws_port if resolution_published else configured_ws_port + + +func _resolve_ws_port() -> int: + return PortResolver.resolve_ws_port( + ClientConfigurator.ws_port(), + ClientConfigurator.MAX_PORT, + _log_buffer, + ) + + +## Test-compat shim — characterization tests call this static directly. +static func _resolved_ws_port_for_existing_server( + record_ws_port: int, + record_version: String, + current_version: String, + fresh_resolved: int +) -> int: + return PortResolver.resolved_ws_port_for_existing_server( + record_ws_port, + record_version, + current_version, + fresh_resolved, + ) + + +static func _resolve_ws_port_from_output( + configured_port: int, + netsh_output: String, + span: int = 2048 +) -> int: + return PortResolver.resolve_ws_port_from_output( + configured_port, + netsh_output, + ClientConfigurator.MAX_PORT, + span, + ) + + +## Plugin-level shim around the resolver — keeps the startup-trace +## counter wiring and the `_ProofPlugin` override hook on the plugin. +## The scrape takes `_startup_trace_count` directly so the counter names +## track the scraper that actually ran (Windows can fall through netstat +## → PowerShell; the fallback used to hide under the `netstat` count). +func _is_port_in_use(port: int) -> bool: + if PortResolver.can_bind_local_port(port): + ## POSIX can still have an IPv6 wildcard listener on this port + ## even when an IPv4 loopback bind succeeds. Confirm through + ## lsof so startup and kill-path discovery agree. + if OS.get_name() != "Windows": + return PortResolver.is_port_in_use_via_scrape(port, _startup_trace_count) + return false + return PortResolver.is_port_in_use_via_scrape(port, _startup_trace_count) + + +## Pass `_startup_trace_count` so the resolver bumps the right counter +## per scraper that actually ran (Windows can fall through netstat → +## PowerShell — counting both unconditionally would over-report). +func _find_pid_on_port(port: int) -> int: + return PortResolver.find_pid_on_port(port, _startup_trace_count) + + +func _find_all_pids_on_port(port: int) -> Array[int]: + return PortResolver.find_all_pids_on_port(port, _startup_trace_count) + + +static func _execute_windows_powershell(script: String, output: Array) -> int: + return PortResolver.execute_windows_powershell(script, output) + + +static func _windows_listener_pids_from_execute_result(exit_code: int, output: Array) -> Array[int]: + return PortResolver.windows_listener_pids_from_execute_result(exit_code, output) + + +static func _windows_listener_execute_result_in_use(exit_code: int, output: Array) -> bool: + return PortResolver.windows_listener_execute_result_in_use(exit_code, output) + + +static func _parse_lsof_pids(raw: String) -> Array[int]: + return PortResolver.parse_lsof_pids(raw) + + +static func _parse_pid_lines(raw: String) -> Array[int]: + return PortResolver.parse_pid_lines(raw) + + +## Find the managed server PID deterministically: prefer the pid-file +## the Python server writes on startup (see runtime_info.py), fall back +## to scraping `netstat -ano` / `lsof` only when the file is missing or +## stale. This is the replacement for raw port-scraping: on Windows the +## uvx launcher PID doesn't cover the Python child, and netstat parsing +## is fragile. +## +## Returns 0 when no server can be identified. +func _find_managed_pid(port: int) -> int: + var pid := _read_pid_file() + if pid > 0 and _pid_alive(pid): + return pid + return _find_pid_on_port(port) + + +## `live` is the result of a prior `_probe_live_server_status_for_port` +## call that the caller already has on hand. When non-empty it short- +## circuits the internal probe at the bottom of this helper, so a single +## `_start_server` invocation that probes once at the top can thread the +## same snapshot through compatibility check + recovery without paying +## for a second ~500 ms localhost HTTPClient poll loop. Default `{}` +## preserves the historical behavior for callers outside the spawn flow +## (`can_recover_incompatible_server`, the dock's UI buttons), where a +## fresh probe is the right thing. +## `record_override`: a managed-server record snapshot the caller already +## read. Non-empty skips the internal `_read_managed_server_record()` — +## required when this helper runs on a worker thread (#678), because the +## record lives in EditorSettings, which is main-thread-only. `{}` keeps +## the historical read-it-here behavior for synchronous callers +## (`_read_managed_server_record` never returns a bare `{}`, so the +## sentinel is unambiguous). +func _evaluate_strong_port_occupant_proof(port: int, live: Dictionary = {}, record_override: Dictionary = {}) -> Dictionary: + var result := {"proof": "", "pids": []} + var listener_pids := _find_all_pids_on_port(port) + if listener_pids.is_empty(): + return result + + var record: Dictionary = record_override if not record_override.is_empty() else _read_managed_server_record() + var record_pid := int(record.get("pid", 0)) + var record_version := str(record.get("version", "")) + + if record_pid > 1 and record_pid != OS.get_process_id(): + ## Brand-verify the recorded PID before trusting it as a kill target. + ## A recorded PID can outlive the server it named and be recycled by + ## the kernel for an unrelated process that happens to bind the same + ## port — without the cmdline brand gate (the same one the + ## `pidfile_listener` branch enforces) that process could be killed. + ## See #525. + if ( + listener_pids.has(record_pid) + and _pid_alive_for_proof(record_pid) + and _pid_cmdline_is_godot_ai_for_proof(record_pid) + ): + return {"proof": "managed_record", "pids": [record_pid]} + + var legacy_targets := _legacy_pidfile_kill_targets(port, listener_pids) + if not legacy_targets.is_empty(): + return {"proof": "pidfile_listener", "pids": legacy_targets} + + var current_live: Dictionary = live if not live.is_empty() else _probe_live_server_status_for_port(port) + if ( + _live_status_identifies_godot_ai(current_live) + and not record_version.is_empty() + and str(current_live.get("version", "")) == record_version + ): + ## Brand-check every listener before returning it as a kill target + ## (#686): the /godot-ai/status match proves *a* godot-ai server owns + ## the port, but `listener_pids` is a raw scrape that can include an + ## unrelated process sharing the port number (e.g. a ::1-only + ## listener lsof reports alongside our IPv4 one). The other two tiers + ## brand-check every target (#525); this tier feeds the fully + ## automatic start_server drift-kill path, so it must too. + var branded_listeners: Array[int] = [] + for pid in listener_pids: + var listener_pid := int(pid) + if _pid_cmdline_is_godot_ai_for_proof(listener_pid): + branded_listeners.append(listener_pid) + if not branded_listeners.is_empty(): + return {"proof": "status_matches_record", "pids": branded_listeners} + + return result + + +## See `_evaluate_strong_port_occupant_proof` for the `live` and +## `record_override` contracts. Threads both through the strong-proof +## delegate so neither helper probes when the caller already knows the +## port-owner status, and so callers running this on a worker thread +## (#712) can inject the EditorSettings record read on the main thread. +func _evaluate_recovery_port_occupant_proof( + port: int, live: Dictionary = {}, record_override: Dictionary = {} +) -> Dictionary: + var proof := _evaluate_strong_port_occupant_proof(port, live, record_override) + if not str(proof.get("proof", "")).is_empty(): + return proof + + var current_live: Dictionary = live if not live.is_empty() else _probe_live_server_status_for_port(port) + if _live_status_identifies_godot_ai(current_live): + return {"proof": "status_name", "pids": _find_all_pids_on_port(port)} + + return {"proof": "", "pids": []} + + +## Seam over the static pre-warm so lifecycle recovery flows can fire it +## through the host (`_host._prewarm_server_package(...)`) and test stubs +## can record the call instead of spawning a real uvx process. Worker-safe: +## the static touches only CliFinder (mutex-guarded) and OS.create_process. +func _prewarm_server_package(version: String) -> int: + return ClientConfigurator.prewarm_server_package(version) + + +func _recover_strong_port_occupant(port: int, wait_s: float, pre_kill_live: Dictionary = {}) -> bool: + ## `await` because the manager method is a coroutine in production + ## (#678); with `defer_blocking_work` off it completes synchronously + ## and this await is a pass-through. + return await _lifecycle.recover_strong_port_occupant(port, wait_s, pre_kill_live) + + +func _legacy_pidfile_kill_targets(_port: int, listener_pids: Array[int]) -> Array[int]: + var targets: Array[int] = [] + var pidfile_pid := _read_pid_file_for_proof() + if pidfile_pid <= 1 or pidfile_pid == OS.get_process_id(): + return targets + ## An alive, branded pid-file PID is sufficient ownership proof. Under + ## `uvicorn --reload` the reloader writes the pid-file but a child worker + ## binds the port, so `listener_pids` never contains the reloader PID. + ## Requiring `listener_pids.has(pidfile_pid)` here used to silently skip + ## the kill path for the entire reload-shaped server family. The branded + ## listener loop below still does the per-PID brand check so we never + ## kill an unrelated process that happens to share the port. + if not _pid_alive_for_proof(pidfile_pid) or not _pid_cmdline_is_godot_ai_for_proof(pidfile_pid): + return targets + + for pid in listener_pids: + if pid <= 1 or pid == OS.get_process_id(): + continue + ## Reuse the brand result already proven above when this listener is + ## the same PID as the pidfile — saves a parent-chain walk and a + ## shell-out (PowerShell on Windows, /proc on Linux, ps on macOS) per + ## startup proof evaluation. + if pid == pidfile_pid or _pid_cmdline_is_godot_ai_for_proof(pid): + targets.append(pid) + ## Also kill the reloader/launcher itself when it isn't already a listener. + ## Without this, `--reload` workers would be killed but their parent would + ## immediately respawn a replacement and the port would never free. + if not targets.has(pidfile_pid): + targets.append(pidfile_pid) + return targets + + +func _read_pid_file_for_proof() -> int: + return _read_pid_file() + + +func _pid_alive_for_proof(pid: int) -> bool: + return _pid_alive(pid) + + +func _pid_cmdline_is_godot_ai_for_proof(pid: int) -> bool: + return _pid_cmdline_is_godot_ai(pid) + + +static func _parse_windows_netstat_pid(stdout: String, port: int) -> int: + return PortResolver.parse_windows_netstat_pid(stdout, port) + + +static func _parse_windows_netstat_pids(stdout: String, port: int) -> Array[int]: + return PortResolver.parse_windows_netstat_pids(stdout, port) + + +static func _parse_windows_netstat_listening(stdout: String, port: int) -> bool: + return PortResolver.parse_windows_netstat_listening(stdout, port) + + +static func _split_on_whitespace(s: String) -> PackedStringArray: + return PortResolver.split_on_whitespace(s) + + +static func _read_pid_file() -> int: + return PortResolver.read_pid_file() + + +static func _clear_pid_file() -> void: + PortResolver.clear_pid_file() + + +func _stop_server() -> void: + _lifecycle.stop_server() + + + + +## Clear the managed-server record and pid-file only if `port` is free. +## Returns true when state was cleared. Extracted from `_stop_server` so +## the "preserve on failed kill" contract is independently testable. +func _finalize_stop_if_port_free(port: int) -> bool: + if _is_port_in_use(port): + return false + _clear_managed_server_record() + _clear_pid_file() + return true + + +## Shared tail of the server CLI: transport, ports, and `--pid-file`. Both +## the initial spawn in `_start_server` and the `--refresh` retry in +## `_respawn_with_refresh` go through here so a new flag added in one place +## can't silently drop out of the other. +static func _build_server_flags(port: int, ws_port: int) -> Array[String]: + var flags: Array[String] = [] + flags.assign([ + "--transport", "streamable-http", + "--port", str(port), + "--ws-port", str(ws_port), + "--pid-file", ProjectSettings.globalize_path(SERVER_PID_FILE), + ]) + ## Append `--exclude-domains` only when the user has actually picked at + ## least one domain to drop. Skipping the empty case keeps spawns + ## compatible with older (pre-1.4.2) servers that don't know the flag — + ## relevant during staggered plugin/server upgrades in user-mode installs. + var excluded := ClientConfigurator.excluded_domains() + if not excluded.is_empty(): + flags.append("--exclude-domains") + flags.append(excluded) + ## LAN opt-in (#507, server core #421): pass `--allow-host` only when the + ## developer-mode Settings tab named at least one CIDR / bare IP. Skipping + ## the empty case keeps the default spawn byte-for-byte identical and + ## compatible with older servers that don't know the flag — same pattern + ## as `--exclude-domains` above. + var allow_hosts := ClientConfigurator.allow_hosts() + if not allow_hosts.is_empty(): + flags.append("--allow-host") + flags.append(allow_hosts) + return flags + + +## Returns true only when we can prove `pid`'s command line carries the +## `godot-ai` brand AND a server flag (`--pid-file` / `--transport`). Used by +## automatic kill paths (`_legacy_pidfile_kill_targets`) so a stale pidfile +## whose PID has been recycled by an unrelated listener can't hand us a +## kill target. If the OS lookup fails or returns an empty cmdline we +## conservatively return false — better to surface incompatible-server and +## let the user click Restart than to kill the wrong process. +func _pid_cmdline_is_godot_ai(pid: int) -> bool: + ## Walks up the parent chain so a uvicorn `--reload` worker whose + ## cmdline is just `multiprocessing.spawn` still matches when its + ## parent reloader carries the godot_ai brand. Bound the walk so a + ## hypothetical loop or runaway PPID can't stall the editor. + var current := pid + for _i in range(5): + if current <= 1: + return false + var cmd := "" + if OS.get_name() == "Windows": + cmd = _windows_pid_commandline(current) + else: + cmd = _posix_pid_commandline(current) + if _commandline_is_godot_ai_server(cmd): + return true + current = _pid_parent(current) + return false + + +func _pid_parent(pid: int) -> int: + if pid <= 1: + return 0 + if OS.get_name() == "Windows": + var output: Array = [] + var script := ( + "Get-CimInstance Win32_Process -Filter 'ProcessId = %d' | " + + "Select-Object -ExpandProperty ParentProcessId" + ) % pid + _startup_trace_count("powershell") + if _execute_windows_powershell(script, output) != 0 or output.is_empty(): + return 0 + return int(str(output[0]).strip_edges()) + var output_posix: Array = [] + if OS.execute("ps", ["-o", "ppid=", "-p", str(pid)], output_posix, true) != 0 or output_posix.is_empty(): + return 0 + return int(str(output_posix[0]).strip_edges()) + + +static func _commandline_is_godot_ai_server(cmd: String) -> bool: + if cmd.is_empty(): + return false + var lower := cmd.to_lower() + ## The server is invoked with `--pid-file /godot_ai_server.pid`, + ## so the path itself contains "godot_ai". A naive substring brand + ## search would falsely match an unrelated process whose cmdline + ## happens to reference a similarly-named pidfile path. Strip the + ## value (but leave the bare flag for the has_flag check) before + ## brand matching. + var brand_search := _strip_pidfile_value(lower) + var has_brand := brand_search.find("godot-ai") >= 0 or brand_search.find("godot_ai") >= 0 + var has_flag := lower.find("--pid-file") >= 0 or lower.find("--transport") >= 0 + return has_brand and has_flag + + +static func _strip_pidfile_value(cmd: String) -> String: + var rx := RegEx.new() + ## Match `--pid-file=` and `--pid-file `; keep the bare + ## flag so the flag-presence check still succeeds for a real server. + if rx.compile("--pid-file(?:=|\\s+)\\S+") != OK: + return cmd + return rx.sub(cmd, "--pid-file ", true) + + +func _windows_pid_commandline(pid: int) -> String: + var output: Array = [] + var script := ( + "Get-CimInstance Win32_Process -Filter 'ProcessId = %d' | " + + "Select-Object -ExpandProperty CommandLine" + ) % pid + _startup_trace_count("powershell") + var exit_code := _execute_windows_powershell(script, output) + if exit_code != 0 or output.is_empty(): + return "" + return str(output[0]) + + +## POSIX command-line lookup. Linux exposes `/proc//cmdline` as +## NUL-separated argv — read it directly so we avoid a `ps` fork on Linux +## and get the full argv rather than the truncated/quoted form some `ps` +## builds emit. Falls back to `ps -ww -p -o args=` on macOS / *BSD, +## which lack a Linux-style `/proc//cmdline`. Returns "" on failure +## so callers conservatively reject the PID rather than killing it blind. +func _posix_pid_commandline(pid: int) -> String: + var proc_path := "/proc/%d/cmdline" % pid + if FileAccess.file_exists(proc_path): + var f := FileAccess.open(proc_path, FileAccess.READ) + if f != null: + ## procfs pseudo-files report length 0 (the kernel generates + ## content on read). `get_length()` therefore returns 0 and + ## `get_buffer(0)` reads nothing. Read in chunks until EOF + ## instead. Cap at ARG_MAX-class bound so a hypothetically + ## misbehaving file can never stall the editor frame. + var bytes := PackedByteArray() + var max_bytes := 1 << 20 # 1 MiB + while bytes.size() < max_bytes: + var chunk := f.get_buffer(4096) + if chunk.is_empty(): + break + bytes.append_array(chunk) + if f.eof_reached(): + break + f.close() + ## /proc cmdline is NUL-separated argv; convert NULs to spaces + ## so the substring fingerprint matches the same way it does on + ## the Windows path. Empty (kernel threads, exited processes) + ## bubbles up as "" via the strip below. + for i in range(bytes.size()): + if bytes[i] == 0: + bytes[i] = 0x20 + return bytes.get_string_from_utf8().strip_edges() + ## `-ww` removes ps's column-width truncation so trailing flags like + ## --pid-file / --transport aren't dropped from the args= field. + ## Both procps (Linux) and BSD ps (macOS / *BSD) accept the + ## double-w form. + var output: Array = [] + var exit_code := OS.execute("ps", ["-ww", "-p", str(pid), "-o", "args="], output, true) + if exit_code != 0 or output.is_empty(): + return "" + return str(output[0]).strip_edges() + + +## True if the given PID corresponds to a live (non-zombie) process. +## POSIX uses `ps -o stat=` (see inline comment for the zombie rationale); +## Windows uses `tasklist`. Called by `_start_server` to distinguish a live +## managed server that outlived its editor from a stale EditorSettings +## record, and by `_check_server_health` to detect a fast-failing launcher. +static func _pid_alive(pid: int) -> bool: + return PortResolver.pid_alive(pid) + + +## Calls `_is_port_in_use` (not `PortResolver.wait_for_port_free`) so +## `_ProofPlugin` overrides keep driving the loop. +func _wait_for_port_free(port: int, timeout_s: float) -> void: + var deadline := Time.get_ticks_msec() + int(timeout_s * 1000.0) + while _is_port_in_use(port): + if Time.get_ticks_msec() >= deadline: + push_warning("MCP | port %d still in use after %.1fs — proceeding anyway" % [port, timeout_s]) + return + OS.delay_msec(100) + + +func _read_managed_server_record() -> Dictionary: + var es := EditorInterface.get_editor_settings() + if es == null: + return {"pid": 0, "version": "", "ws_port": 0, "ws_token": "", "keep_alive": false} + var pid: int = 0 + if es.has_setting(MANAGED_SERVER_PID_SETTING): + pid = int(es.get_setting(MANAGED_SERVER_PID_SETTING)) + var version: String = "" + if es.has_setting(MANAGED_SERVER_VERSION_SETTING): + version = str(es.get_setting(MANAGED_SERVER_VERSION_SETTING)) + var ws_port: int = 0 + if es.has_setting(MANAGED_SERVER_WS_PORT_SETTING): + ws_port = int(es.get_setting(MANAGED_SERVER_WS_PORT_SETTING)) + var ws_token: String = "" + if es.has_setting(MANAGED_SERVER_WS_TOKEN_SETTING): + ws_token = str(es.get_setting(MANAGED_SERVER_WS_TOKEN_SETTING)) + var keep_alive := false + if es.has_setting(MANAGED_SERVER_KEEP_ALIVE_SETTING): + keep_alive = bool(es.get_setting(MANAGED_SERVER_KEEP_ALIVE_SETTING)) + return { + "pid": pid, + "version": version, + "ws_port": ws_port, + "ws_token": ws_token, + "keep_alive": keep_alive, + } + + +func _write_managed_server_record(pid: int, version: String, keep_alive: bool = false) -> void: + var es := EditorInterface.get_editor_settings() + if es == null: + return + es.set_setting(MANAGED_SERVER_PID_SETTING, pid) + es.set_setting(MANAGED_SERVER_VERSION_SETTING, version) + es.set_setting(MANAGED_SERVER_WS_PORT_SETTING, _resolved_ws_port) + es.set_setting(MANAGED_SERVER_WS_TOKEN_SETTING, _ws_auth_token) + es.set_setting(MANAGED_SERVER_KEEP_ALIVE_SETTING, keep_alive) + + +## Keep the in-memory token, the connection's handshake field, and (via the +## next _write_managed_server_record) the persisted record in one place so +## the three can't drift. Empty token = "send no auth_token field". +func _set_ws_auth_token(token: String) -> void: + _ws_auth_token = token + if _connection != null: + _connection.auth_token = token + + +func _clear_managed_server_record() -> void: + ## Drop the in-memory token together with the persisted one: a cleared + ## record means "no managed server", and a surviving static would make + ## the next handshake send a stale token — the exact present-but-wrong + ## shape a newer spawned server rejects with 4003. (Runs before the + ## es == null early return on purpose: the in-memory scrub must not + ## depend on EditorSettings being available.) + _set_ws_auth_token("") + var es := EditorInterface.get_editor_settings() + if es == null: + return + if es.has_setting(MANAGED_SERVER_PID_SETTING): + es.set_setting(MANAGED_SERVER_PID_SETTING, 0) + if es.has_setting(MANAGED_SERVER_VERSION_SETTING): + es.set_setting(MANAGED_SERVER_VERSION_SETTING, "") + if es.has_setting(MANAGED_SERVER_WS_PORT_SETTING): + es.set_setting(MANAGED_SERVER_WS_PORT_SETTING, 0) + if es.has_setting(MANAGED_SERVER_WS_TOKEN_SETTING): + es.set_setting(MANAGED_SERVER_WS_TOKEN_SETTING, "") + if es.has_setting(MANAGED_SERVER_KEEP_ALIVE_SETTING): + es.set_setting(MANAGED_SERVER_KEEP_ALIVE_SETTING, false) + + +func prepare_for_update_reload() -> void: + if _dispatcher != null: + # Stop accepting handler work and hand any live status worker to its + # frame-polled teardown coroutine. _exit_tree() calls clear() again; the + # second call is intentionally inert because the caches are empty. + _dispatcher.clear() + _lifecycle.prepare_for_update_reload() + + +func _adopt_compatible_server( + record_version: String, + current_version: String, + owner: int, + record_owns_listener: bool = false +) -> String: + return _lifecycle.adopt_compatible_server( + record_version, + current_version, + owner, + record_owns_listener + ) + + +static func _compatible_adoption_log_message( + owner_label: String, + owned_pid: int, + observed_owner_pid: int, + live_version: String, + live_ws_port: int, + current_version: String +) -> String: + if owner_label == "managed": + return "MCP | adopted managed server (PID %d, live v%s, WS %d, plugin v%s)" % [ + owned_pid, + live_version, + live_ws_port, + current_version + ] + return "MCP | adopted external server owner_pid=%d (live v%s, WS %d, plugin v%s)" % [ + observed_owner_pid, + live_version, + live_ws_port, + current_version + ] + + +## Hand the self-update over to a tiny runner that is not owned by this +## EditorPlugin. The runner keeps the editor process alive, but disables this +## plugin before extracting/scanning the new scripts so every plugin-owned +## instance tears down on pre-update bytecode and pre-update field storage. +func install_downloaded_update(zip_path: String, temp_dir: String, source_dock: Control) -> void: + prepare_for_update_reload() + + var detached_dock = null + if _dock != null and is_instance_valid(_dock): + detached_dock = _dock + remove_control_from_docks(_dock) + _dock = null + elif source_dock != null and is_instance_valid(source_dock): + detached_dock = source_dock + remove_control_from_docks(source_dock) + + var runner = UPDATE_RELOAD_RUNNER_SCRIPT.new() + var parent: Node = EditorInterface.get_base_control() + if parent == null: + parent = get_tree().root + parent.add_child(runner) + runner.start(zip_path, temp_dir, detached_dock) + + +func can_recover_incompatible_server() -> bool: + return _lifecycle.can_recover_incompatible_server() + + +func _resume_connection_after_recovery() -> void: + if _connection == null: + return + var state: int = _lifecycle.get_state() + if ( + _lifecycle.is_connection_blocked() + or ( + state != ServerStateScript.SPAWNING + and state != ServerStateScript.READY + ) + ): + return + _connection.connect_blocked = false + _connection.connect_block_reason = "" + _connection.server_version = "" + _connection.set_process(true) + _arm_server_version_check() + + +func recover_incompatible_server(user_initiated: bool = true, stale_version: String = "") -> bool: + ## A user's click (the dock's Restart) authorizes the bounded + ## stale-occupant retry for this episode, so a bridge respawning the old + ## version and winning the post-kill bind race gets re-killed + ## automatically instead of dead-ending the click in a terminal state. + ## The automatic triggers (post-update handshake mismatch, fast-exit + ## re-walk) call with `user_initiated=false` and only SPEND from the + ## already-authorized budget — re-arming there would unbound the + ## kill/respawn loop against a persistent respawner. + if user_initiated: + _lifecycle.authorize_stale_recovery() + ## `await` because the manager's recovery is a coroutine in production + ## (#678): `_resume_connection_after_recovery` gates on the post-walk + ## state, so it must not run until the respawn walk has completed. With + ## `defer_blocking_work` off this completes synchronously. + if not await _lifecycle.recover_incompatible_server(stale_version): + return false + _resume_connection_after_recovery() + return true + + +## Kill whichever process is holding `http_port()` right now — by resolving +## the port-owning PID via pid-file / netstat / lsof, independent of whether +## we ever set the manager's `_server_pid` — then clear ownership state +## and respawn via the lifecycle manager. The dock's version-mismatch +## banner wires here when the plugin adopted a foreign server whose +## `server_version` drifts from the current plugin version. +func force_restart_server() -> void: + _lifecycle.force_restart_server() + + +## Single entry point for the dock's primary "Restart Dev Server" button. +## The user clicking Restart is explicit consent to take over the HTTP port, +## so this is aggressive: any PID holding the port gets killed (managed, +## branded-dev, or orphan multiprocessing.spawn workers whose parent died +## so brand detection misses them). After the port frees we spawn a fresh +## --reload dev server. Returns true if a kill happened, false if the port +## was already free and we just spawned. +func force_restart_or_start_dev_server() -> bool: + var port := ClientConfigurator.http_port() + var killed := false + if has_managed_server(): + _lifecycle.reset_for_force_restart() + if _is_port_in_use(port): + _kill_processes_and_windows_spawn_children(_find_all_pids_on_port(port)) + killed = true + if killed: + ## OS.kill returns synchronously but uvicorn's listener can take + ## longer to release the port. Without this wait, start_dev_server's + ## fixed 500ms timer races the old shutdown and the new --reload + ## spawn fails to bind. + _wait_for_port_free(port, 5.0) + start_dev_server() + return killed + + +func start_dev_server() -> void: + ## Start a dev server with --reload that survives plugin reloads. + ## Kills any managed server first, waits for the port to free, then spawns. + ## + ## PYTHONPATH handling: when `res://` sits inside a checkout that owns a + ## `src/godot_ai/` (root repo or a git worktree), prepend that `src/` to + ## PYTHONPATH so `import godot_ai` and uvicorn's `reload_dirs` both pick + ## up *this* tree's source rather than the root repo's editable install. + ## On the root repo the path matches the installed package, so this is a + ## no-op; in a worktree it's what makes `--reload` actually watch the + ## worktree's Python. See #84. + _stop_server() + get_tree().create_timer(0.5).timeout.connect(func(): + var server_cmd := ClientConfigurator.get_server_command() + if server_cmd.is_empty(): + push_warning("MCP | could not find server command for dev server") + return + + var cmd: String = server_cmd[0] + _set_resolved_ws_port(_resolve_ws_port()) + var inner_args: Array[String] = [] + inner_args.assign(server_cmd.slice(1)) + inner_args.append_array([ + "--transport", "streamable-http", + "--port", str(ClientConfigurator.http_port()), + "--ws-port", str(_resolved_ws_port), + "--reload", + ]) + + var worktree_src := ClientConfigurator.find_worktree_src_dir(ProjectSettings.globalize_path("res://")) + var prev_pythonpath := OS.get_environment("PYTHONPATH") + if not worktree_src.is_empty(): + var sep := ";" if OS.get_name() == "Windows" else ":" + var new_pp := worktree_src if prev_pythonpath.is_empty() else worktree_src + sep + prev_pythonpath + OS.set_environment("PYTHONPATH", new_pp) + + var injected_telemetry: bool = _lifecycle._inject_telemetry_env() + var pid := OS.create_process(cmd, inner_args) + if injected_telemetry: + OS.unset_environment("GODOT_AI_DISABLE_TELEMETRY") + + ## Restore PYTHONPATH immediately — the spawned child has already + ## copied the env, so the editor's own process state returns to + ## baseline. Leaving it set would leak to any later OS.create_process + ## from unrelated paths. + if not worktree_src.is_empty(): + if prev_pythonpath.is_empty(): + OS.unset_environment("PYTHONPATH") + else: + OS.set_environment("PYTHONPATH", prev_pythonpath) + + if pid > 0: + ## Match `server_lifecycle.gd::start_server`'s log wording — + ## "prefix" since we prepended to any pre-existing PYTHONPATH, + ## not replaced it. See #429 review. + var suffix := " (PYTHONPATH prefix=%s)" % worktree_src if not worktree_src.is_empty() else "" + print("MCP | started dev server with --reload (PID %d): %s %s%s" % [pid, cmd, " ".join(inner_args), suffix]) + else: + push_warning("MCP | failed to start dev server") + ) + + +func stop_dev_server() -> void: + ## Stop any server running on the HTTP port (by port, not PID). + ## Used for dev servers whose PID we don't track across reloads. + if _lifecycle.get_server_pid() > 0: + # We have a managed server — use normal stop + _stop_server() + return + ## A suspended startup walk holds pre-kill probe results; without this + ## it can resume against the listener we are about to kill and adopt a + ## dead server. + _lifecycle._invalidate_async_startup() + var port := ClientConfigurator.http_port() + var candidates: Array[int] = [] + for pid in _find_all_pids_on_port(port): + var candidate := int(pid) + if _pid_cmdline_is_godot_ai(candidate): + candidates.append(candidate) + var killed := _kill_processes_and_windows_spawn_children(candidates) + if not killed.is_empty(): + print("MCP | stopped dev server on port %d" % port) + + +## `verify_brand`: re-check `pid_alive` + the godot-ai cmdline brand +## immediately before the kill (#686). Pass true when the proof that +## nominated `pids` was evaluated in an earlier scheduling window (e.g. +## `recover_strong_port_occupant`'s proof runs in one `_run_blocking` task +## and the kill in a second, with main-thread frames in between) — a branded +## target that exits in that gap can have its PID recycled to an innocent +## process. Default false preserves the intentionally-unbranded call sites +## (the dock's explicit-consent Restart button, orphan spawn workers whose +## parent died so brand detection misses them). +func _kill_processes_and_windows_spawn_children(pids: Array[int], verify_brand: bool = false) -> Array[int]: + var unique: Array[int] = [] + for pid in pids: + if pid <= 0 or unique.has(pid): + continue + if verify_brand and not (_pid_alive_for_proof(pid) and _pid_cmdline_is_godot_ai_for_proof(pid)): + continue + unique.append(pid) + if OS.get_name() == "Windows": + for child_pid in _find_windows_spawn_children(unique): + if not unique.has(child_pid): + unique.append(child_pid) + var killed: Array[int] = [] + for pid in unique: + if OS.get_name() == "Windows": + var output: Array = [] + var exit_code := OS.execute("taskkill", ["/PID", str(pid), "/T", "/F"], output, true) + if exit_code == 0 or not _pid_alive(pid): + killed.append(pid) + else: + ## Mirror the Windows branch: only report the PID as killed if + ## the kill succeeded or the process is verifiably gone. + if OS.kill(pid) == OK or not _pid_alive(pid): + killed.append(pid) + return killed + + +func _find_windows_spawn_children(parent_pids: Array[int]) -> Array[int]: + if parent_pids.is_empty(): + var empty: Array[int] = [] + return empty + var found: Array[int] = [] + for parent_pid in parent_pids: + var output: Array = [] + var script := ( + "Get-CimInstance Win32_Process | " + + "Where-Object { $_.CommandLine -like '*spawn_main(parent_pid=%d*' } | " + + "ForEach-Object { $_.ProcessId }" + ) % parent_pid + _startup_trace_count("powershell") + var exit_code := _execute_windows_powershell(script, output) + if exit_code != 0 or output.is_empty(): + continue + for pid in _parse_pid_lines(str(output[0])): + if not found.has(pid): + found.append(pid) + return found + + +func is_dev_server_running() -> bool: + ## Returns true if a branded dev server is running on the HTTP port + ## that we didn't start as managed. + if _lifecycle.get_server_pid() > 0: + return false + for pid in _find_all_pids_on_port(ClientConfigurator.http_port()): + if _pid_cmdline_is_godot_ai(int(pid)): + return true + return false + + +func has_managed_server() -> bool: + ## Returns true if the plugin is currently managing a server process it spawned. + return _lifecycle.has_managed_server() + + +func can_restart_managed_server() -> bool: + ## Restart is allowed only when we have ownership proof. A live PID + ## means this plugin spawned/adopted a managed server; a non-empty + ## managed record is the cross-session proof used by the drift branch. + return _lifecycle.can_restart_managed_server() + + +func _on_custom_tools_changed() -> void: + if _connection == null: + push_warning("MCP | connection isn't established") + return + var tool_list: Array[Dictionary] = [] + ## Send all definitions plus their state: the server hides disabled tools + ## from fresh tools/list responses but retains a callable tombstone so a + ## client using a cached promoted name receives CUSTOM_TOOL_DISABLED. + for spec in _custom_tool_registry.all(): + tool_list.append({ + "name": spec.name, + "description": spec.description, + "params_schema": spec.params_schema, + "source": spec.source, + "deferred": spec.deferred, + "timeout_ms": spec.timeout_ms, + "requires_writable": spec.requires_writable, + "undoable": spec.undoable, + "promoted": spec.promoted, + "enabled": _custom_tool_registry.is_tool_enabled(spec.name) + }) + _connection.send_event("custom_tools_changed", {"tools": tool_list}) + + +## On (re)connect, replay the current custom-tool catalog so tools +## registered before the initial connection or during a disconnect +## window reach the server. send_event silently drops while +## _connected is false (connection.gd::_send_json), so without this +## replay those tools only surface on the next registry mutation. +func _on_connection_state_changed(is_open: bool) -> void: + if is_open and _custom_tool_registry != null: + _on_custom_tools_changed() diff --git a/addons/godot_ai/plugin.gd.uid b/addons/godot_ai/plugin.gd.uid new file mode 100644 index 0000000..4c550dd --- /dev/null +++ b/addons/godot_ai/plugin.gd.uid @@ -0,0 +1 @@ +uid://d3ui3yx6vdigl diff --git a/addons/godot_ai/runtime/draw_recipe.gd b/addons/godot_ai/runtime/draw_recipe.gd new file mode 100644 index 0000000..8204bd7 --- /dev/null +++ b/addons/godot_ai/runtime/draw_recipe.gd @@ -0,0 +1,86 @@ +@tool +extends Control + +## Runtime helper attached by control_draw_recipe. +## Reads an array of op dicts from node metadata under key "_ops" and dispatches +## each to a CanvasItem draw call in _draw(). The ops list is set by the handler +## via set_meta; this script is deterministic — re-setting meta + queue_redraw +## is enough to update the visuals. + +const META_KEY := "_ops" + + +func _ready() -> void: + queue_redraw() + + +func _draw() -> void: + if not has_meta(META_KEY): + return + var ops: Variant = get_meta(META_KEY) + if typeof(ops) != TYPE_ARRAY: + return + for op in ops: + if typeof(op) != TYPE_DICTIONARY: + continue + match op.get("draw", ""): + "line": + draw_line( + op.from, + op.to, + op.color, + float(op.get("width", 1.0)), + bool(op.get("antialiased", false)) + ) + "rect": + # Godot warns if `width` is passed when `filled` is true — + # width has no effect on filled rects. Split the call so we + # only pass width when stroking an outline. + var filled := bool(op.get("filled", true)) + if filled: + draw_rect(op.rect, op.color, true) + else: + draw_rect( + op.rect, + op.color, + false, + float(op.get("width", 1.0)) + ) + "arc": + draw_arc( + op.center, + float(op.radius), + float(op.start_angle), + float(op.end_angle), + int(op.get("point_count", 32)), + op.color, + float(op.get("width", 1.0)), + bool(op.get("antialiased", false)) + ) + "circle": + draw_circle(op.center, float(op.radius), op.color) + "polyline": + draw_polyline( + op.points, + op.color, + float(op.get("width", 1.0)), + bool(op.get("antialiased", false)) + ) + "polygon": + var colors: PackedColorArray = ( + op.colors if op.has("colors") else PackedColorArray([op.color]) + ) + draw_polygon(op.points, colors) + "string": + var font: Font = get_theme_default_font() + if font == null: + continue + draw_string( + font, + op.position, + str(op.text), + int(op.get("align", HORIZONTAL_ALIGNMENT_LEFT)), + float(op.get("max_width", -1.0)), + int(op.get("font_size", 16)), + op.color + ) diff --git a/addons/godot_ai/runtime/draw_recipe.gd.uid b/addons/godot_ai/runtime/draw_recipe.gd.uid new file mode 100644 index 0000000..5de2df2 --- /dev/null +++ b/addons/godot_ai/runtime/draw_recipe.gd.uid @@ -0,0 +1 @@ +uid://da3fqfqv6gtgm diff --git a/addons/godot_ai/runtime/editor_logger.gd b/addons/godot_ai/runtime/editor_logger.gd new file mode 100644 index 0000000..2d19daa --- /dev/null +++ b/addons/godot_ai/runtime/editor_logger.gd @@ -0,0 +1,139 @@ +@tool +extends Logger + +## Editor-process Logger subclass. +## +## NOTE: deliberately no `class_name`. Registered from plugin.gd::_enter_tree +## so we can intercept editor-process script errors — parse errors, @tool +## runtime errors, EditorPlugin errors, push_error/push_warning — and surface +## them via `logs_read(source="editor")`. Without this, the LLM sees nothing +## in `logs_read` while the same errors show in red lines in Godot's Output +## panel. +## +## Why only `_log_error` and not `_log_message`: +## `_log_message(msg, error)` covers print() and printerr(), which is the +## firehose path — running editors print thousands of internal info lines +## a session. The issue (#231) explicitly asks to filter so the buffer +## isn't drowned. Errors and warnings flow through `_log_error` (parse +## errors, push_error/push_warning, runtime errors), which is what +## debugging callers actually need. If we discover @tool printerr() is a +## valuable source later, _log_message can be added behind the same filter. +## +## Logger virtuals can be called from any thread (e.g. async script +## loaders push parse errors off the main thread). McpEditorLogBuffer is +## mutex-protected so we can append directly without an intermediate queue. + +const ADDON_PATH_MARKER := "/addons/godot_ai/" + +## Resolve McpLogBacktrace by path, not by the `McpLogBacktrace` class_name. +## A bare class_name reference depends on the global class-name table being populated +## at compile time, which isn't guaranteed on a cold editor enable mid-scan. +## `const preload` resolves at compile time independent of the registry — +## matches game_logger.gd's deliberate choice for the same reason. +const _LogBacktrace := preload("res://addons/godot_ai/utils/log_backtrace.gd") + +## Constructor-injected so the hot path doesn't need a per-call null check. +var _buffer + + +func _init(buffer = null) -> void: + _buffer = buffer + + +func _log_error( + function: String, + file: String, + line: int, + code: String, + rationale: String, + _editor_notify: bool, + error_type: int, + script_backtraces: Array, +) -> void: + if _buffer == null: + return + ## Cheap reject for the firehose: when `file` is already non-user (the + ## bulk of editor-internal C++ chatter), there's no backtrace to remap + ## from, and the message doesn't name a project resource, the resolved + ## path can only stay non-user — drop without paying for resolve_error's + ## call frame + dict allocation. + var message := rationale if not rationale.is_empty() else code + var message_res_path := _extract_user_res_path(message) + if not _is_user_script(file) and script_backtraces.is_empty() and message_res_path.is_empty(): + return + var resolved := _LogBacktrace.resolve_error( + function, file, line, code, rationale, error_type, script_backtraces, + ) + if not _is_user_script(resolved.path): + if message_res_path.is_empty(): + return + resolved.path = message_res_path + resolved.line = 0 + resolved.function = function + _update_resolved_details(resolved) + if _is_in_godot_ai_addon(resolved.path): + return + if not message_res_path.is_empty() and _is_in_godot_ai_addon(message_res_path): + return + var details: Dictionary = resolved.get("details", {}) + _buffer.append(resolved.level, resolved.message, resolved.path, resolved.line, resolved.function, details) + + +static func _update_resolved_details(resolved: Dictionary) -> void: + var details: Dictionary = resolved.get("details", {}) + if details.is_empty(): + return + details["resolved"] = { + "path": resolved.get("path", ""), + "line": resolved.get("line", 0), + "function": resolved.get("function", ""), + } + resolved["details"] = details + + +## Predicate broken out so tests can drive the path-filter logic without +## constructing real Logger calls. +static func _is_user_script(path: String) -> bool: + if path.is_empty(): + return false + ## Match .gd / .cs (case-insensitively to handle .GD on case-insensitive + ## filesystems). C# scripts compile elsewhere but the parser path can + ## still surface .cs files for assembly load failures. + var lower := path.to_lower() + return lower.ends_with(".gd") or lower.ends_with(".cs") + + +## Path-substring check works for both `res://addons/godot_ai/foo.gd` and +## globalized absolute paths (`/Users/.../addons/godot_ai/foo.gd`) that +## Godot can also report depending on where the error originated. +static func _is_in_godot_ai_addon(path: String) -> bool: + if path.begins_with("res://addons/godot_ai/"): + return true + return path.find(ADDON_PATH_MARKER) >= 0 + + +## Some engine-origin errors have no ScriptBacktrace even though they are +## project-relevant, notably ResourceLoader failures: +## `Failed loading resource: res://does/not/exist.tres.`. Capture these by +## extracting a named `res://` path from the message while keeping editor +## internals and this addon's own resources filtered. +static func _extract_user_res_path(message: String) -> String: + var start := message.find("res://") + if start < 0: + return "" + var end := message.length() + var quote_end := message.find("'", start) + if quote_end >= 0: + end = mini(end, quote_end) + quote_end = message.find("\"", start) + if quote_end >= 0: + end = mini(end, quote_end) + quote_end = message.find("`", start) + if quote_end >= 0: + end = mini(end, quote_end) + var path := message.substr(start, end - start).strip_edges() + while not path.is_empty() and path.substr(path.length() - 1, 1) in [".", ",", ";", ":", ")"]: + path = path.substr(0, path.length() - 1) + if path.is_empty() or _is_in_godot_ai_addon(path): + return "" + return path diff --git a/addons/godot_ai/runtime/editor_logger.gd.uid b/addons/godot_ai/runtime/editor_logger.gd.uid new file mode 100644 index 0000000..9db6035 --- /dev/null +++ b/addons/godot_ai/runtime/editor_logger.gd.uid @@ -0,0 +1 @@ +uid://cxfregddqj5b8 diff --git a/addons/godot_ai/runtime/game_helper.gd b/addons/godot_ai/runtime/game_helper.gd new file mode 100644 index 0000000..ff4fb4e --- /dev/null +++ b/addons/godot_ai/runtime/game_helper.gd @@ -0,0 +1,1317 @@ +extends Node + +## Godot AI MCP — game-process helper. +## +## Registered as an autoload by plugin.gd when the Godot AI plugin is enabled. +## Runs in the running game process (separate from the editor) so the plugin +## can request the game's framebuffer over the editor-debugger channel. +## +## The editor never has direct access to the game's pixels: even when "Embed +## Game Mode" is on, the game is still a separate OS child process whose +## window is reparented into the editor via Win32 SetParent / X11 +## XReparentWindow / macOS remote layer (Godot PR godotengine/godot#99010). +## So viewport-texture capture on the editor side never contains game pixels. +## This autoload solves that by replying to "mcp:take_screenshot" debug +## messages with a PNG of Viewport.get_texture() from inside the game. +## +## No-ops in the editor (Engine.is_editor_hint) and silently sits idle +## when the debugger channel is inactive (e.g. exported release builds) +## — register_message_capture is safe to call either way, it's +## send_message that requires an active channel. + +const CAPTURE_PREFIX := "mcp" +## Cap per-frame flush so a runaway print loop can't blow the debugger's +## packet budget in a single send. Surplus stays queued for the next frame. +const FLUSH_BATCH_LIMIT := 200 +## How long take_screenshot waits for the game's first real presentation +## before reading the viewport texture back. The "mcp" capture registers in +## this autoload's _ready(), which runs BEFORE the main scene enters the tree +## and before the renderer has presented anything — so a request arriving +## right after mcp:hello would otherwise read back the clear-color +## framebuffer (observed as a uniform RGB(77,77,77) PNG on GitHub's +## GPU-less paravirtualized macOS runners, where the first present lags +## seconds behind boot). MUST stay below the editor-side reply timer +## (DEFAULT_TIMEOUT_SEC = 8.0 in debugger/mcp_debugger_plugin.gd) so a +## game that genuinely can't render falls through to the existing +## texture/image error replies before the editor gives up with its +## generic timeout. +const FIRST_FRAME_WAIT_SEC := 6.0 +## #777: how long the main loop can go without ticking _process before +## _handle_take_screenshot treats it as frozen and commits a synchronous +## stale-frame capture instead of awaiting frames that will never come. +## A backgrounded/minimized play-in-editor game stops iterating its main +## loop entirely, so any real threshold works; 1s keeps a merely-slow game +## (heavy frame, low FPS) on the fresh-frame await path. +const MAIN_LOOP_STALL_MSEC := 1000 +## How long frames_drawn can stay flat before _handle_take_screenshot treats +## rendering as suppressed and commits the synchronous stale-frame capture. +## On Windows, minimizing the game window freezes frame presentation but NOT +## the main loop — _process keeps ticking, so the MAIN_LOOP_STALL_MSEC beacon +## never trips and every capture used to burn the full FIRST_FRAME_WAIT_SEC +## await before replying stale (issue #794 smoke, item 1b). Larger than the +## loop threshold so a heavy-but-rendering game (~1 FPS frame gaps) stays on +## the fresh-frame await path; a sub-0.7 FPS game that trips this still gets +## an honestly stale-flagged image immediately instead of a 6s wait. +const RENDER_STALL_MSEC := 1500 + +const GameLogger := preload("res://addons/godot_ai/runtime/game_logger.gd") +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") +## Shared with the editor-side copy in editor_handler.gd (#716). Preload by +## path, not class_name: this autoload runs in the game process and must not +## depend on the editor's global-class cache being warm. +const ScreenshotEncode := preload("res://addons/godot_ai/utils/screenshot_encode.gd") + +var _registered := false +## Captures game-process print, warning, and error output for the editor. +var _logger: Logger +var _logger_attached := false +## Entries drained from the logger but not yet sent over the debugger +## channel. Holds the tail of one drain() so we can bleed it out across +## frames at FLUSH_BATCH_LIMIT per frame rather than blasting the whole +## queue in a single _process tick. +var _pending_outbound: Array = [] +## #490: in-flight evals, keyed by request_id (multiple deferred game_evals +## can run at once). Each entry: {node:Node, token:String, baseline:int}. +## `token` names this eval's unique wrapper function so a runtime error is +## attributed only to the eval that actually raised it — not an unrelated +## background game error, and not a sibling overlapping eval. `baseline` is the +## logger's script-error seq just before this eval ran. The editor's eval_check +## probe (and #488's in-flight poll loop, when the game is focused) consult +## these to report a runtime error that aborted execute() before the reply. +var _inflight_evals: Dictionary = {} +var _eval_token_counter: int = 0 +## #777: last time _process ran, in ticks msec. The debugger message capture +## stays live while a backgrounded game's main loop is frozen, so this is how +## _handle_take_screenshot (running inside that capture) detects the freeze +## synchronously. -1 until the first tick. +var _last_loop_tick_msec: int = -1 +## Rendering-freeze beacon for the Windows-minimize state (#794 smoke, 1b): +## the frames_drawn value last observed in _process, and when it last +## advanced. -1 until the first observed advance, so a booting or +## render-less game (frames_drawn stuck at 0) can never read as +## render-stalled and keeps the fresh-frame await path's error replies. +var _last_frames_drawn_seen: int = -1 +var _last_frames_advance_msec: int = -1 +## #859: test/diagnostic seam for the synchronous eval liveness reply. The +## debugger capture remains callable while the game loop is parked, so the +## reply reports whether the _process beacon is actually advancing rather +## than merely proving that the capture was registered once. +var _last_eval_liveness_reply: Dictionary = {} + + +func _ready() -> void: + ## Only run in the game process, not in the editor. Use is_editor_hint + ## — NOT OS.has_feature("editor"), which is a BUILD-config check + ## (TOOLS_ENABLED) and returns true in the game subprocess too because + ## the game is spawned with the same editor binary. is_editor_hint is + ## the runtime-context check: true only inside the editor GUI, false + ## in play-from-editor. The earlier has_feature check was causing us + ## to skip registration in the game and time out every capture. + if Engine.is_editor_hint(): + return + ## Keep ticking while the tree is paused: _process both ferries game logs + ## and timestamps main-loop liveness for the stalled-loop screenshot + ## fallback (#777). A paused game still iterates its loop and renders, and + ## must not be misread as frozen. + process_mode = Node.PROCESS_MODE_ALWAYS + ## register_message_capture is safe to call before the debugger + ## handshake completes; the capture sits until a message arrives. + EngineDebugger.register_message_capture(CAPTURE_PREFIX, _on_debug_message) + _registered = true + ## Capture print() / printerr() / push_error() / push_warning() and + ## ferry them to the editor in mcp:log_batch messages flushed from + ## _process. + _logger = GameLogger.new() + OS.add_logger(_logger) + _logger_attached = true + ## Routed to the editor's Output panel via Godot's remote-stdout + ## forwarder — handy when diagnosing why capture timed out. + print("[godot_ai game_helper] registered mcp capture (debugger active=%s, logger=%s)" + % [EngineDebugger.is_active(), _logger_attached]) + ## Boot beacon so the editor side can confirm the autoload ran even + ## if no screenshot was ever requested. + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:hello", []) + + +func _process(_delta: float) -> void: + ## #777: liveness beacon for _handle_take_screenshot's stalled-loop check. + ## Recorded before the early returns below so the signal stays truthful + ## even when the logger or debugger channel is unavailable. + _last_loop_tick_msec = Time.get_ticks_msec() + ## Rendering beacon: on Windows a minimized game keeps ticking _process + ## while presentation stops, so frames_drawn stagnation — not loop + ## silence — is the observable freeze signal there (#794 smoke, 1b). + var frames_now := Engine.get_frames_drawn() + if frames_now != _last_frames_drawn_seen: + _last_frames_drawn_seen = frames_now + _last_frames_advance_msec = _last_loop_tick_msec + ## Drain the logger queue on the main thread (Logger virtuals can fire + ## from any thread; EngineDebugger.send_message is only safe from main). + ## Send at most one FLUSH_BATCH_LIMIT-sized batch per frame so a runaway + ## print loop can't stall the game by shoving thousands of entries + ## through the debugger packet path in a single tick. Surplus stays in + ## `_pending_outbound` and bleeds out across subsequent frames. + if not _logger_attached or _logger == null: + return + if not EngineDebugger.is_active(): + return + if _pending_outbound.is_empty(): + if not _logger.has_pending(): + return + _pending_outbound = _logger.drain() + var batch := _pending_outbound.slice(0, FLUSH_BATCH_LIMIT) + _pending_outbound = _pending_outbound.slice(FLUSH_BATCH_LIMIT) + EngineDebugger.send_message("mcp:log_batch", [batch]) + + +func _exit_tree() -> void: + if _registered: + EngineDebugger.unregister_message_capture(CAPTURE_PREFIX) + _registered = false + if _logger_attached and _logger != null: + OS.remove_logger(_logger) + _logger_attached = false + _logger = null + + +## Dispatched for messages prefixed "mcp:" on the debugger channel. +## Godot passes the full message ("mcp:take_screenshot") to the capture +## callable; trim defensively so tests can still call the helper with either +## form. +func _on_debug_message(message: String, data: Array) -> bool: + var action := message.trim_prefix("mcp:") + match action: + "take_screenshot": + _handle_take_screenshot(data) + return true + "eval_liveness": + _reply_eval_liveness(data) + return true + "eval": + _handle_eval(data) + return true + "eval_check": + _handle_eval_check(data) + return true + "game_command": + _handle_game_command(data) + return true + return false + + +## #859: answer from the debugger capture without awaiting a game frame. The +## capture can still run while a backgrounded/frozen game's main loop cannot, +## so the _process beacon is the liveness signal that matters for game_eval. +func _reply_eval_liveness(data: Array) -> void: + var request_id: String = data[0] if data.size() > 0 else "" + var loop_live := not _main_loop_appears_stalled() + _last_eval_liveness_reply = {"request_id": request_id, "loop_live": loop_live} + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:eval_liveness_response", [request_id, loop_live]) + + +func _handle_take_screenshot(data: Array) -> void: + var request_id: String = data[0] if data.size() > 0 else "" + var max_resolution: int = int(data[1]) if data.size() > 1 else 0 + + var tree := get_tree() + var viewport := tree.root if tree != null else null + if viewport == null: + _reply_error(request_id, "No game root viewport available") + return + + ## #777: this function runs inside the debugger message capture, which + ## stays live even when a backgrounded/minimized play-in-editor game has + ## frozen its main loop. In that state awaiting `process_frame` parks + ## this coroutine forever — no reply is ever sent, and the game side + ## cannot self-timeout because timers need the same frozen loop. Commit a + ## synchronous capture of the last rendered frame instead: stale, but a + ## real image, flagged as such in the reply. Only fall through to the + ## fresh-frame awaits when the loop is demonstrably alive. + if _should_capture_stale_sync( + _main_loop_appears_stalled(), + _rendering_appears_stalled(), + tree.current_scene != null, + Engine.get_frames_drawn() + ): + _capture_and_reply(request_id, viewport, max_resolution, Engine.get_frames_drawn()) + return + + ## Wait (bounded — see FIRST_FRAME_WAIT_SEC) until the main scene is in + ## the tree and at least one frame has been drawn after this request, so + ## the readback never precedes the first real present. Past the deadline, + ## fall through anyway: current_scene stays null under a custom main + ## loop, and frames_drawn never advances in a render-less game — both + ## are handled by the texture/image error replies below. + var deadline := Time.get_ticks_msec() + int(FIRST_FRAME_WAIT_SEC * 1000.0) + while tree.current_scene == null and Time.get_ticks_msec() < deadline: + await tree.process_frame + var frames_at_request := Engine.get_frames_drawn() + while Engine.get_frames_drawn() <= frames_at_request and Time.get_ticks_msec() < deadline: + await tree.process_frame + + _capture_and_reply(request_id, viewport, max_resolution, frames_at_request) + + +## #777: pure decision for the synchronous stale-frame path. Sync capture is +## only worth committing when awaiting can't produce a fresh frame — the main +## loop is frozen (macOS/suspend), or the loop still ticks but presentation +## is suppressed (Windows minimize, #794 smoke 1b) — AND the viewport +## plausibly holds a real frame: the main scene is in the tree and at least +## one frame was presented. Without those, the stale readback would be the +## boot clear-color framebuffer — worse than the honest timeout. +static func _should_capture_stale_sync( + loop_stalled: bool, render_stalled: bool, has_current_scene: bool, frames_drawn: int +) -> bool: + return (loop_stalled or render_stalled) and has_current_scene and frames_drawn > 0 + + +## #777: true when _process hasn't ticked within MAIN_LOOP_STALL_MSEC — +## i.e. the main loop is frozen (backgrounded window) or has never run. +func _main_loop_appears_stalled() -> bool: + ## The hello→probe round trip normally follows at least one _process tick. + ## Treat the never-ticked sentinel as stalled defensively rather than + ## dispatching an eval into a game whose main loop has not started. + if _last_loop_tick_msec < 0: + return true + return Time.get_ticks_msec() - _last_loop_tick_msec > MAIN_LOOP_STALL_MSEC + + +## True when frames_drawn has sat flat past RENDER_STALL_MSEC while _process +## kept ticking — Windows minimize suppresses presentation without freezing +## the loop, so the loop beacon alone misses it (#794 smoke, 1b). False until +## the first observed frame advance: a game that has never presented has no +## trustworthy frame to return, and must fall through to the await path's +## texture/image error replies instead. +func _rendering_appears_stalled() -> bool: + if _last_frames_advance_msec < 0: + return false + return Time.get_ticks_msec() - _last_frames_advance_msec > RENDER_STALL_MSEC + + +## Read back the viewport texture and reply — fully synchronous, so it is +## safe to call from the debugger capture while the main loop is frozen. +## `frames_at_request` is Engine.get_frames_drawn() at request receipt: if no +## further frame was drawn by capture time, the image predates the request +## and the reply is flagged stale. +func _capture_and_reply( + request_id: String, viewport: Viewport, max_resolution: int, frames_at_request: int +) -> void: + var texture := viewport.get_texture() + if texture == null: + _reply_error(request_id, "Root viewport has no texture (headless?)") + return + + var image := texture.get_image() + if image == null or image.is_empty(): + _reply_error(request_id, "Captured an empty image from game viewport") + return + + var encoded: Dictionary = ScreenshotEncode.downscale_and_encode(image, max_resolution) + var frames_drawn := Engine.get_frames_drawn() + var stale := frames_drawn <= frames_at_request + + _last_screenshot_reply = { + "kind": "response", + "request_id": request_id, + "frames_drawn": frames_drawn, + "stale": stale, + "width": encoded.width, + "height": encoded.height, + } + if EngineDebugger.is_active(): + ## Fields 7+8 are new in #777; older editors read the first six and + ## ignore the rest. + EngineDebugger.send_message("mcp:screenshot_response", [ + request_id, + encoded.base64, + encoded.width, + encoded.height, + encoded.original_width, + encoded.original_height, + frames_drawn, + stale, + ]) + + +## Testing seam: the last screenshot reply (response or error), recorded +## before hitting the EngineDebugger channel (inactive in the editor-side +## test harness). Mirrors _last_eval_reply. +var _last_screenshot_reply: Dictionary = {} + + +func _reply_error(request_id: String, message: String) -> void: + _last_screenshot_reply = {"kind": "error", "request_id": request_id, "message": message} + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:screenshot_error", [request_id, message]) + + +## --- game_command: curated runtime inspection and input --- + +func _handle_game_command(data: Array) -> void: + var request_id: String = data[0] if data.size() > 0 else "" + var op: String = data[1] if data.size() > 1 else "" + var params_json: String = data[2] if data.size() > 2 else "{}" + + if request_id.is_empty(): + return + if op.is_empty(): + _reply_game_command_error(request_id, "No op provided") + return + + var json := JSON.new() + var parse_err := json.parse(params_json) + if parse_err != OK or not (json.data is Dictionary): + _reply_game_command_error(request_id, "Invalid params JSON") + return + + var result: Dictionary + match op: + "get_scene_tree": + result = _game_get_scene_tree(json.data) + "get_node_info": + result = _game_get_node_info(json.data) + "get_ui_elements": + result = _game_get_ui_elements(json.data) + "input_key": + result = _game_input_key(json.data) + "input_mouse": + result = _game_input_mouse(json.data) + "input_gamepad": + result = _game_input_gamepad(json.data) + "input_action": + result = _game_input_action(json.data) + "input_state": + result = _game_input_state(json.data) + "input_sequence": + ## Async: steps frames and replies itself (deferred), so bail out + ## before the synchronous send below — same shape as the eval and + ## screenshot capture paths. + _run_input_sequence(request_id, json.data) + return + _: + _reply_game_command_error(request_id, "Unknown game op: %s" % op) + return + + result["source"] = "game" + result["op"] = op + EngineDebugger.send_message("mcp:game_command_response", + [request_id, JSON.stringify(_variant_to_json(result))]) + + +func _reply_game_command_error(request_id: String, message: String) -> void: + EngineDebugger.send_message("mcp:game_command_error", [request_id, message]) + + +func _game_get_scene_tree(params: Dictionary) -> Dictionary: + var depth := maxi(0, int(params.get("depth", 10))) + var root := _resolve_runtime_node(str(params.get("root_path", ""))) + if root == null: + return {"root": "", "nodes": [], "total_count": 0, "not_found": params.get("root_path", "")} + + var nodes: Array[Dictionary] = [] + _collect_runtime_nodes(root, 0, depth, nodes) + return { + "root": _runtime_path(root), + "nodes": nodes, + "total_count": nodes.size(), + } + + +func _collect_runtime_nodes(node: Node, current_depth: int, max_depth: int, out: Array[Dictionary]) -> void: + out.append({ + "name": node.name, + "type": node.get_class(), + "path": _runtime_path(node), + "children_count": node.get_child_count(), + }) + if current_depth >= max_depth: + return + for child in node.get_children(): + if child is Node: + _collect_runtime_nodes(child, current_depth + 1, max_depth, out) + + +func _game_get_node_info(params: Dictionary) -> Dictionary: + var path := str(params.get("path", "")) + var node := _resolve_runtime_node(path) + if node == null: + return {"path": path, "found": false} + + var info := { + "path": _runtime_path(node), + "name": node.name, + "type": node.get_class(), + "children_count": node.get_child_count(), + "groups": node.get_groups(), + "found": true, + } + if bool(params.get("include_properties", true)): + info["properties"] = _runtime_node_properties(node) + return info + + +func _game_get_ui_elements(params: Dictionary) -> Dictionary: + var max_depth := maxi(0, int(params.get("max_depth", 10))) + var include_hidden := bool(params.get("include_hidden", false)) + var include_disabled := bool(params.get("include_disabled", true)) + var root_path := str(params.get("root_path", "")) + var root := _resolve_runtime_node(root_path) + if root == null: + return {"root": "", "elements": [], "total_count": 0, "not_found": root_path} + + var elements: Array[Dictionary] = [] + _collect_ui_elements(root, 0, max_depth, include_hidden, include_disabled, elements) + return { + "root": _runtime_path(root), + "elements": elements, + "total_count": elements.size(), + } + + +func _collect_ui_elements( + node: Node, + current_depth: int, + max_depth: int, + include_hidden: bool, + include_disabled: bool, + out: Array[Dictionary] +) -> void: + if node is Control: + var control := node as Control + var visible := _control_visible_in_tree(control) + var disabled := _control_disabled(control) + if (include_hidden or visible) and (include_disabled or not disabled): + out.append(_ui_element_info(control, visible, disabled)) + + if current_depth >= max_depth: + return + for child in node.get_children(): + if child is Node: + _collect_ui_elements( + child, + current_depth + 1, + max_depth, + include_hidden, + include_disabled, + out + ) + + +func _ui_element_info(control: Control, visible: bool, disabled: bool) -> Dictionary: + var info := { + "path": _runtime_path(control), + "name": control.name, + "type": control.get_class(), + "visible": visible, + "disabled": disabled, + "rect": _variant_to_json(control.get_rect()), + "global_rect": _variant_to_json(control.get_global_rect()), + } + if _object_has_property(control, "text"): + info["text"] = str(control.get("text")) + return info + + +func _control_disabled(control: Control) -> bool: + if _object_has_property(control, "disabled"): + return bool(control.get("disabled")) + return false + + +func _control_visible_in_tree(control: Control) -> bool: + if not control.visible: + return false + var parent := control.get_parent() + while parent != null: + if parent is CanvasItem and not (parent as CanvasItem).visible: + return false + parent = parent.get_parent() + if Engine.is_editor_hint(): + return true + return control.is_visible_in_tree() + + +static var _property_name_cache: Dictionary = {} + + +func _object_has_property(obj: Object, property_name: String) -> bool: + var key := _property_cache_key(obj) + if not _property_name_cache.has(key): + var names := {} + for prop in obj.get_property_list(): + names[str(prop.get("name", ""))] = true + _property_name_cache[key] = names + return (_property_name_cache[key] as Dictionary).has(property_name) + + +func _property_cache_key(obj: Object) -> String: + var script = obj.get_script() + if script == null: + return obj.get_class() + var script_id := str(script.get_instance_id()) + if not script.resource_path.is_empty(): + script_id = script.resource_path + return "%s:%s" % [obj.get_class(), script_id] + + +func _runtime_node_properties(node: Node) -> Dictionary: + var props := {} + for p in node.get_property_list(): + var name := str(p.get("name", "")) + var usage := int(p.get("usage", 0)) + if name.is_empty() or (usage & PROPERTY_USAGE_EDITOR) == 0: + continue + props[name] = _variant_to_json(node.get(name)) + return props + + +func _resolve_runtime_node(path: String) -> Node: + var scene_root := _current_scene_root() + if scene_root == null: + return null + if path.is_empty() or path == "/": + return scene_root + + if path.begins_with("/root/"): + return get_tree().root.get_node_or_null(path.trim_prefix("/root/")) + + var scene_path := path.trim_prefix("/") + if scene_path == str(scene_root.name): + return scene_root + var prefix := str(scene_root.name) + "/" + if scene_path.begins_with(prefix): + scene_path = scene_path.substr(prefix.length()) + return scene_root.get_node_or_null(scene_path) + + +func _runtime_path(node: Node) -> String: + var scene_root := _current_scene_root() + if scene_root == null: + return str(node.get_path()) + if node == scene_root: + return "/" + str(scene_root.name) + return "/" + str(scene_root.name) + "/" + str(scene_root.get_path_to(node)) + + +func _current_scene_root() -> Node: + var tree := get_tree() + if tree == null: + return null + var scene_root := tree.current_scene + if scene_root == null and Engine.is_editor_hint(): + # Look the editor singleton up by name rather than referencing the bare + # `EditorInterface` identifier: that identifier is compiled out of export + # templates, so the GDScript parser rejects it ("Identifier + # "EditorInterface" not declared in the current scope") in an exported + # build even though `Engine.is_editor_hint()` would never run it there. + # That parse failure stops this autoload from loading in every export. + var editor := Engine.get_singleton(&"EditorInterface") + if editor: + scene_root = editor.get_edited_scene_root() + return scene_root + + +func _game_input_key(params: Dictionary) -> Dictionary: + var key_name := str(params.get("key", "")) + var keycode := OS.find_keycode_from_string(key_name) + if keycode == KEY_NONE: + return {"sent": false, "error": "Unknown key: %s" % key_name} + var ev := InputEventKey.new() + ev.keycode = keycode + ev.physical_keycode = keycode + ev.pressed = bool(params.get("pressed", true)) + ev.echo = bool(params.get("echo", false)) + Input.parse_input_event(ev) + return {"sent": true, "key": key_name, "pressed": ev.pressed} + + +func _game_input_mouse(params: Dictionary) -> Dictionary: + var event := str(params.get("event", "button")) + var pos_result := _resolve_mouse_position(params.get("position")) + if pos_result.has("error"): + return {"sent": false, "event": event, "error": pos_result.error} + var pos: Vector2 = pos_result.position + match event: + "motion": + var motion := InputEventMouseMotion.new() + motion.position = pos + motion.global_position = pos + Input.parse_input_event(motion) + return {"sent": true, "event": "motion", "position": _variant_to_json(pos)} + "button": + var button_event := InputEventMouseButton.new() + button_event.position = pos + button_event.global_position = pos + button_event.button_index = _mouse_button_index(str(params.get("button", "left"))) + button_event.pressed = bool(params.get("pressed", true)) + Input.parse_input_event(button_event) + return { + "sent": true, + "event": "button", + "button": params.get("button", "left"), + "pressed": button_event.pressed, + "position": _variant_to_json(pos), + } + return {"sent": false, "error": "Invalid mouse event: %s" % event} + + +func _game_input_gamepad(params: Dictionary) -> Dictionary: + var device := int(params.get("device", 0)) + var control := str(params.get("control", "button")) + match control: + "button": + var button := InputEventJoypadButton.new() + button.device = device + button.button_index = int(params.get("index", 0)) + button.pressed = bool(params.get("pressed", true)) + Input.parse_input_event(button) + return {"sent": true, "control": "button", "device": device, "index": button.button_index, "pressed": button.pressed} + "axis": + var axis := InputEventJoypadMotion.new() + axis.device = device + axis.axis = int(params.get("index", 0)) + axis.axis_value = float(params.get("value", 0.0)) + Input.parse_input_event(axis) + return {"sent": true, "control": "axis", "device": device, "index": axis.axis, "value": axis.axis_value} + return {"sent": false, "error": "Invalid gamepad control: %s" % control} + + +func _game_input_action(params: Dictionary) -> Dictionary: + var action := str(params.get("action", "")) + if action.is_empty(): + return {"sent": false, "error": "Missing action"} + if not InputMap.has_action(action): + return {"sent": false, "action": action, "error": "Unknown action: %s" % action} + var pressed := bool(params.get("pressed", true)) + var strength := clampf(float(params.get("strength", 1.0)), 0.0, 1.0) + if pressed: + Input.action_press(action, strength) + else: + Input.action_release(action) + return { + "sent": true, + "action": action, + "pressed": pressed, + "strength": strength, + "delivery": "action_state", + } + + +func _game_input_state(params: Dictionary) -> Dictionary: + var actions: Array = params.get("actions", []) + if actions.is_empty(): + actions = InputMap.get_actions() + var states := {} + for action in actions: + var name := str(action) + states[name] = Input.is_action_pressed(name) + return {"actions": states} + + +## --- input_sequence: frame-timed action timeline (deferred) --- +## +## Per-step round-trips can't hit a target frame — network jitter lands each +## input on whatever frame its reply happens to arrive on, so a jump arc or a +## timed combo is unreproducible (#814). input_sequence takes the whole +## timeline in one call and drives it game-side, applying each step's action on +## its scheduled frame, then replies once (deferred). Frame count (not ms) is +## the timing basis: it's what reproduces identically across runs. + +## Hard caps mirrored by the server-side schema (see game handlers). The game +## side re-checks them so a malformed direct message can't park the coroutine +## on an unbounded await; the server rejects the same cases up front with a +## clearer error. +## +## The frame cap bounds the sequence in *frames*, which is a wall-clock time +## only at a given FPS: 600 frames is ~10s at 60fps but longer under load or on +## a throttled runner. It is not sized to the ~30s deferred budget +## (editor_handler.INPUT_SEQUENCE_TIMEOUT_SEC) — the two are independent +## safeguards. If a genuinely slow run exceeds the budget, the dispatcher +## returns a clean DEFERRED_TIMEOUT rather than hanging, so the cap can stay a +## simple frame count. +const MAX_SEQUENCE_STEPS := 256 +const MAX_SEQUENCE_FRAMES := 600 + +## Testing seam: the last input_sequence reply (response or error), recorded +## before the EngineDebugger channel (inactive in the editor-side test +## harness). Mirrors _last_screenshot_reply / _last_eval_reply. +var _last_game_command_reply: Dictionary = {} + +## Testing seam: overrides the per-frame wait in _run_input_sequence. Left +## invalid in production (real `process_frame` awaits). A test sets it to a +## synchronously-returning Callable so the multi-frame loop runs to completion +## in one call — the editor test runner invokes tests synchronously and never +## pumps `process_frame`, so a real frame-await would suspend and record zero +## assertions. Timing itself (one frame per step) is engine-guaranteed; this +## seam covers the scheduling/application/reply logic layered on top. +var _frame_waiter: Callable = Callable() + + +## Validate + normalize an input_sequence request. Pure (no engine state), so +## the ordering/cap/shape rules are unit-testable without a running game. +## Returns {"error": String} or {"steps": Array, "end_frame": int}. +func _plan_input_sequence(params: Dictionary) -> Dictionary: + var raw_steps: Variant = params.get("steps", null) + if not (raw_steps is Array): + return {"error": "steps must be an array"} + var steps_arr: Array = raw_steps + if steps_arr.is_empty(): + return {"error": "steps must not be empty"} + if steps_arr.size() > MAX_SEQUENCE_STEPS: + return {"error": "steps exceeds cap of %d (got %d)" % [MAX_SEQUENCE_STEPS, steps_arr.size()]} + + ## Validate field *kinds* rather than coercing them: the server already + ## rejects bad shapes, but this planner is also the backstop for a + ## malformed direct debugger message, so it must not silently turn + ## pressed="false" into true or at_frame="oops" into 0. _is_number accepts + ## int or float (JSON round-trips whole numbers as either) but not bool or + ## string, so this stays consistent with the server without tripping on + ## JSON's number typing. + var settle_raw: Variant = params.get("settle_frames", 0) + if not _is_number(settle_raw): + return {"error": "settle_frames must be a number"} + var settle_frames := int(settle_raw) + if settle_frames < 0: + return {"error": "settle_frames must be >= 0"} + + var normalized: Array = [] + var prev_frame := -1 + for i in steps_arr.size(): + var raw: Variant = steps_arr[i] + if not (raw is Dictionary): + return {"error": "steps[%d] must be an object" % i} + var step: Dictionary = raw + if not (step.get("action", "") is String) or str(step.get("action", "")).is_empty(): + return {"error": "steps[%d].action is required" % i} + var action: String = step["action"] + var at_frame_raw: Variant = step.get("at_frame", 0) + if not _is_number(at_frame_raw): + return {"error": "steps[%d].at_frame must be a number" % i} + var at_frame := int(at_frame_raw) + if at_frame < 0: + return {"error": "steps[%d].at_frame must be >= 0" % i} + if at_frame < prev_frame: + return {"error": "steps must be ordered by at_frame (steps[%d]=%d < previous %d)" % [i, at_frame, prev_frame]} + prev_frame = at_frame + var pressed_raw: Variant = step.get("pressed", true) + if not (pressed_raw is bool): + return {"error": "steps[%d].pressed must be a boolean" % i} + var strength_raw: Variant = step.get("strength", 1.0) + if not _is_number(strength_raw): + return {"error": "steps[%d].strength must be a number" % i} + normalized.append({ + "at_frame": at_frame, + "action": action, + "pressed": pressed_raw, + "strength": clampf(float(strength_raw), 0.0, 1.0), + }) + + var end_frame: int = int(normalized[-1]["at_frame"]) + settle_frames + if end_frame > MAX_SEQUENCE_FRAMES: + return {"error": "sequence spans %d frames, exceeds cap of %d" % [end_frame, MAX_SEQUENCE_FRAMES]} + return {"steps": normalized, "end_frame": end_frame} + + +## Async: apply each step's action on its scheduled frame, awaiting one +## process_frame per frame, then reply (deferred). Bails out before applying +## anything if the plan is invalid or any action is unknown to the running +## game's InputMap — a half-applied timeline leaves inputs in an undefined +## state, so it's all-or-nothing on the pre-checks. +func _run_input_sequence(request_id: String, params: Dictionary) -> void: + var plan := _plan_input_sequence(params) + if plan.has("error"): + _reply_input_sequence_error(request_id, plan["error"]) + return + + var steps: Array = plan["steps"] + var end_frame: int = plan["end_frame"] + + ## Resolve action names against the *game's* InputMap up front — the server + ## can't see it, so this is the first place unknown actions surface. + for step in steps: + if not InputMap.has_action(step["action"]): + _reply_input_sequence_error(request_id, "Unknown action: %s" % step["action"]) + return + + var tree := get_tree() + if tree == null: + _reply_input_sequence_error(request_id, "No SceneTree available for input sequence") + return + + var applied: Array = [] + var step_i := 0 + for f in range(0, end_frame + 1): + while step_i < steps.size() and int(steps[step_i]["at_frame"]) == f: + var step: Dictionary = steps[step_i] + _game_input_action(step) + applied.append({"at_frame": f, "action": step["action"], "pressed": step["pressed"]}) + step_i += 1 + if f < end_frame: + if _frame_waiter.is_valid(): + await _frame_waiter.call() + else: + await tree.process_frame + + _reply_input_sequence_ok(request_id, { + "completed": true, + "steps_applied": applied.size(), + "frames_elapsed": end_frame, + "applied": applied, + "actions_pressed_at_end": _actions_pressed_at_end(steps), + }) + + +## Distinct actions the sequence touched that are still held at the end, so the +## caller knows what it must release (a press with no matching release leaves +## the action stuck on across the next frames). +func _actions_pressed_at_end(steps: Array) -> Array: + var seen := {} + var pressed: Array = [] + for step in steps: + var action: String = step["action"] + if seen.has(action): + continue + seen[action] = true + if Input.is_action_pressed(action): + pressed.append(action) + return pressed + + +func _reply_input_sequence_ok(request_id: String, result: Dictionary) -> void: + result["source"] = "game" + result["op"] = "input_sequence" + _last_game_command_reply = {"kind": "response", "op": "input_sequence", "result": result} + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:game_command_response", + [request_id, JSON.stringify(_variant_to_json(result))]) + + +func _reply_input_sequence_error(request_id: String, message: String) -> void: + _last_game_command_reply = {"kind": "error", "op": "input_sequence", "message": message} + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:game_command_error", [request_id, message]) + + +## Resolve a mouse-position param. Absent (null, or an empty {}) falls back to +## the live cursor position — a deliberate default. A present but wrong-shaped +## value is rejected instead of silently substituting the cursor, which +## previously hid caller bugs (#635). Accepts a {x, y} dict or an [x, y] array; +## returns {position: Vector2} or {error: String}. +func _resolve_mouse_position(value: Variant) -> Dictionary: + var viewport := get_viewport() + var fallback := viewport.get_mouse_position() if viewport != null else Vector2.ZERO + if value == null: + return {"position": fallback} + if value is Dictionary: + var dict: Dictionary = value + if dict.is_empty(): + return {"position": fallback} + # A non-empty dict that carries neither coordinate is a caller mistake, + # not "use the default" — reject rather than silently substitute. + if not dict.has("x") and not dict.has("y"): + return {"error": "position object must have an 'x' and/or 'y' key (got keys %s)" % str(dict.keys())} + var x_val: Variant = dict.get("x", fallback.x) + var y_val: Variant = dict.get("y", fallback.y) + if not _is_number(x_val) or not _is_number(y_val): + return {"error": "position x/y must be numbers (got x=%s, y=%s)" % [type_string(typeof(x_val)), type_string(typeof(y_val))]} + return {"position": Vector2(float(x_val), float(y_val))} + if value is Array: + var arr: Array = value + if arr.size() != 2: + return {"error": "position array must be [x, y] (got %d elements)" % arr.size()} + if not _is_number(arr[0]) or not _is_number(arr[1]): + return {"error": "position array elements must be numbers (got [%s, %s])" % [type_string(typeof(arr[0])), type_string(typeof(arr[1]))]} + return {"position": Vector2(float(arr[0]), float(arr[1]))} + return {"error": "position must be a {x, y} object or [x, y] array (got %s)" % type_string(typeof(value))} + + +func _is_number(v: Variant) -> bool: + return typeof(v) == TYPE_INT or typeof(v) == TYPE_FLOAT + + +func _mouse_button_index(name: String) -> int: + match name: + "right": + return MOUSE_BUTTON_RIGHT + "middle": + return MOUSE_BUTTON_MIDDLE + "wheel_up": + return MOUSE_BUTTON_WHEEL_UP + "wheel_down": + return MOUSE_BUTTON_WHEEL_DOWN + return MOUSE_BUTTON_LEFT + + +## --- game_eval: execute arbitrary GDScript in the running game --- + +## Wall-clock ceiling for a single game_eval. Evaluated code that awaits +## something which never completes (a signal that never fires, a timer on a +## paused tree) would otherwise pin the request open until the dispatcher's +## 15s deferred budget / the server's 15s command timeout fires it as an +## opaque INTERNAL_ERROR — with the temp eval Node leaked into the tree. +## Bounding it here lets us free the node and reply with an actionable +## message instead. See hi-godot/godot-ai#487. +## +## TIMEOUT ORDERING — load-bearing across three files: this value MUST stay +## below the editor-side fallback timer in +## `debugger/mcp_debugger_plugin.gd::request_game_eval` (`timeout_sec`, +## default 10.0), which in turn stays below the dispatcher's `game_eval` +## budget in `dispatcher.gd` (15000 ms). So: game 8s < editor 10s < +## dispatcher 15s. Only this game-side guard emits the specific +## "Eval exceeded 8s" message (both it and the editor backstop now carry the +## EVAL_HUNG code, #518, but the editor's message can't name the cause). +## Raise this at/above the editor timer (or drop that timer below this) and +## the less specific editor message wins the race, silently losing the +## diagnostic this fix exists to provide. The cross-file contract is enforced +## by tests/unit/test_game_eval_timeout_ordering.py. +## +## NOTE: this catches a hung `await`, not a CPU-bound loop with no `await` — +## a tight `while true:` with no yield blocks the main thread, so nothing +## (including this poll) runs until it yields. That case is out of scope. +const EVAL_TIMEOUT_SEC := 8.0 + + +func _handle_eval(data: Array) -> void: + var request_id: String = data[0] if data.size() > 0 else "" + var code: String = data[1] if data.size() > 1 else "" + + if code.is_empty(): + _reply_eval_error(request_id, "No code provided") + return + + ## Wrap user code in an execute() coroutine (so it can `await` internally) + ## whose inner function is uniquely named per eval. A runtime error's + ## backtrace then carries `_mcp_run_`, letting us attribute it to + ## THIS eval — not an unrelated background game error, and not a sibling + ## overlapping eval. (#490) + _eval_token_counter += 1 + var token := str(_eval_token_counter) + var run_fn := "_mcp_run_%s" % token + var script_source := ( + "extends Node\n" + + "func execute():\n" + + "\treturn await %s()\n\n" % run_fn + + "func %s():\n" % run_fn + + _indent_eval_code(code) + ) + + ## Snapshot the logger's script-error seq BEFORE running so we only attribute + ## errors raised by this eval. In a debug build a parse error aborts reload() + ## and a runtime error aborts execute() — either way this function may never + ## reach its reply: the editor infers a compile error from the missing + ## mcp:eval_compiled beacon, and a runtime error is reported (via the + ## eval_check probe / the in-flight poll loop) once a logged error past this + ## baseline carries this eval's token. + var baseline: int = _logger.script_error_seq() if _logger != null else 0 + + var script: GDScript = GDScript.new() + script.source_code = script_source + ## #490: ack BEFORE reload(). A parse error aborts this function at reload() + ## without a return code in a debug build, so this is our only chance to tell + ## the editor "received + about to compile." The editor uses that to tell a + ## real parse error (acked, never compiled) apart from a message it simply + ## hasn't serviced yet (never acked); see mcp_debugger_plugin._on_eval_grace. + EngineDebugger.send_message("mcp:eval_ack", [request_id]) + ## reload() ABORTS this function on a parse error in a debug build (it does + ## not return a non-OK code there), so the lines below only run when the + ## source compiled. Keep reload() INLINE — moving it behind a timer/await + ## poisons subsequent evals (#490). The err branch still matters for the + ## editor process (handler unit tests), where reload() does return. + var err: int = script.reload() + if err != OK: + _reply_eval_error(request_id, + "Failed to compile GDScript (error %d). Check syntax." % err) + return + + ## Compiled OK — tell the editor so its grace timer doesn't flag a compile + ## error and so it begins probing for a runtime error. + EngineDebugger.send_message("mcp:eval_compiled", [request_id]) + + var temp_node := Node.new() + temp_node.set_script(script) + temp_node.process_mode = Node.PROCESS_MODE_ALWAYS + add_child(temp_node) + + if not temp_node.has_method("execute"): + temp_node.queue_free() + _reply_eval_error(request_id, "Internal error: eval wrapper is missing execute().") + return + + ## Register in-flight BEFORE running: a runtime error aborts execute() (and + ## may unwind this function) before we could record it afterward, and the + ## editor probe / poll loop need the entry to attribute and report the error. + _inflight_evals[request_id] = {"node": temp_node, "token": token, "baseline": baseline} + + ## Drive execute() as a fire-and-forget coroutine that records its outcome + ## into `holder`, then poll frames until it finishes or the deadline passes + ## (#488's hung-await guard). A plain `await temp_node.execute()` has no + ## escape hatch: if user code never returns, we never reach the reply/cleanup + ## below and the request hangs with the node leaked. + var holder := {"done": false, "value": null, "abandoned": false} + _drive_eval(temp_node, holder) + + var tree := get_tree() + var deadline_ms := int(EVAL_TIMEOUT_SEC * 1000.0) + var start_ms := Time.get_ticks_msec() + while not holder["done"] and (Time.get_ticks_msec() - start_ms) < deadline_ms: + ## #490 focused fast path: a runtime error aborts _drive_eval (holder + ## never completes), so check each frame whether THIS eval's token now + ## appears in a logged error and report it immediately. (Backgrounded, + ## this loop is frozen and the editor probe does the same job.) + if _try_report_eval_runtime_error(request_id): + holder["abandoned"] = true + return + await tree.process_frame + + if not holder["done"]: + ## Past the 8s deadline. Disambiguate a runtime error (its token is in a + ## logged error) from a genuine hung await before the generic timeout. + holder["abandoned"] = true + if _try_report_eval_runtime_error(request_id): + return + _inflight_evals.erase(request_id) + if is_instance_valid(temp_node): + remove_child(temp_node) + _reply_eval_error(request_id, + ("Eval exceeded %ds and was aborted — the code likely awaits " + + "something that never completes (a signal that never fires, a timer on " + + "a paused tree) or loops forever. Check logs_read(source='game').") + % int(EVAL_TIMEOUT_SEC), + ErrorCodes.EVAL_HUNG) + return + + ## Clean finish. + _inflight_evals.erase(request_id) + temp_node.queue_free() + _reply_eval_response(request_id, holder["value"]) + + +## Run the compiled eval node's execute() and stash the result. Kept +## separate from _handle_eval so the latter can race it against a deadline +## via frame polling. If the eval was abandoned (timed out) before this +## resumes, drop the result and free the now-detached node — _handle_eval +## has already replied. +## +## RESIDUAL LEAK (accepted): if the awaited thing *never* fires, this +## coroutine never resumes, so the `node` it holds is detached (via +## _handle_eval's remove_child) but never freed — one orphaned Node per such +## timeout, for the game-process lifetime. GDScript has no way to cancel a +## suspended coroutine, so this is the best achievable in-process. It is still +## strictly better than the pre-#487 behavior, where the node leaked *into* +## the live tree and the request hung to the 15s ceiling. +func _drive_eval(node: Node, holder: Dictionary) -> void: + var value = await node.execute() + if holder.get("abandoned", false): + if is_instance_valid(node): + node.queue_free() + return + holder["value"] = value + holder["done"] = true + + +## #518: cap on the serialized eval result. Godot's remote-debugger TCP peer +## silently discards any single message over ~8 MiB, so a bigger reply never +## reaches the editor and the request rides to the 10s backstop as a phantom +## "hang". (Results over the editor↔server WebSocket buffer cap of 4 MiB fail +## there with their own explicit error; this game-side cap only needs to stay +## under the debugger peer's drop threshold to keep the failure visible.) +const EVAL_RESULT_MAX_BYTES := 6 * 1024 * 1024 + +## Testing seam: the last eval reply, recorded before hitting the +## EngineDebugger channel (inactive in the editor-side test harness). +var _last_eval_reply: Dictionary = {} + + +## `code` (optional) rides as a third payload element so the editor can map +## the reply to a specific error code instead of the generic INTERNAL_ERROR; +## the editor allowlists the value (see mcp_debugger_plugin._on_eval_error). +func _reply_eval_error(request_id: String, message: String, code: String = "") -> void: + _last_eval_reply = {"kind": "error", "request_id": request_id, + "message": message, "code": code} + var payload := [request_id, message] + if not code.is_empty(): + payload.append(code) + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:eval_error", payload) + + +func _reply_eval_response(request_id: String, value: Variant) -> void: + var serialized := JSON.stringify(_variant_to_json(value)) + var serialized_bytes := serialized.to_utf8_buffer().size() + if serialized_bytes > EVAL_RESULT_MAX_BYTES: + _reply_eval_error(request_id, + ("Eval result too large to return (%d bytes serialized, limit %d). " + + "Return a smaller slice instead — e.g. counts, node paths, or a " + + "truncated substring.") % [serialized_bytes, EVAL_RESULT_MAX_BYTES], + ErrorCodes.EVAL_RESULT_TOO_LARGE) + return + _last_eval_reply = {"kind": "response", "request_id": request_id} + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:eval_response", [request_id, serialized]) + + +## #490: if a logged script error past THIS eval's baseline carries its unique +## wrapper-function token, a runtime error aborted it before it could reply — +## report it with the real text + line. Returns true if it reported. Called +## from the editor's eval_check probe (the reliable path when a backgrounded +## game's idle loop is frozen — the debugger capture callback still runs) and +## from _handle_eval's poll loop (the focused fast path). Token + baseline +## matching means an unrelated background error, or a sibling overlapping +## eval's error, can never fail this request. +func _try_report_eval_runtime_error(request_id: String) -> bool: + if _logger == null: + return false + var entry = _inflight_evals.get(request_id) + if entry == null: + return false + var text: String = _logger.find_script_error_since( + int(entry["baseline"]), "_mcp_run_%s" % str(entry["token"])) + if text.is_empty(): + return false + _inflight_evals.erase(request_id) + var node: Node = entry["node"] + if node != null and is_instance_valid(node): + node.queue_free() + if EngineDebugger.is_active(): + EngineDebugger.send_message("mcp:eval_runtime_error", [request_id, text]) + return true + + +## #490: answer an editor eval_check probe. The editor polls this once the +## eval has compiled but not yet replied. This runs in the debugger capture +## callback, which stays live even when the backgrounded game's _process is +## frozen — so it's the reliable channel for reporting a runtime error that +## aborted the eval. Report if one is detected for this request, else stay +## silent (the editor keeps polling until the real reply or the hang timeout). +func _handle_eval_check(data: Array) -> void: + var request_id: String = data[0] if data.size() > 0 else "" + if request_id.is_empty(): + return + _try_report_eval_runtime_error(request_id) + + +func _indent_eval_code(code: String) -> String: + var lines: PackedStringArray = code.split("\n") + var out := "" + for line in lines: + out += "\t" + line + "\n" + return out + + +## Serialize any Godot Variant to a JSON-safe dictionary/array/primitive. +## Ported from godot-mcp's mcp_interaction_server.gd. +func _variant_to_json(value: Variant) -> Variant: + if value == null: + return null + if value is bool or value is int or value is float or value is String: + return value + if value is Vector2: + return {"x": value.x, "y": value.y} + if value is Vector3: + return {"x": value.x, "y": value.y, "z": value.z} + if value is Vector4: + return {"x": value.x, "y": value.y, "z": value.z, "w": value.w} + if value is Vector2i: + return {"x": value.x, "y": value.y} + if value is Vector3i: + return {"x": value.x, "y": value.y, "z": value.z} + if value is Vector4i: + return {"x": value.x, "y": value.y, "z": value.z, "w": value.w} + if value is Color: + return {"r": value.r, "g": value.g, "b": value.b, "a": value.a} + if value is Quaternion: + return {"x": value.x, "y": value.y, "z": value.z, "w": value.w} + if value is Basis: + return { + "x": _variant_to_json(value.x), + "y": _variant_to_json(value.y), + "z": _variant_to_json(value.z), + } + if value is Transform3D: + return { + "basis": _variant_to_json(value.basis), + "origin": _variant_to_json(value.origin), + } + if value is Transform2D: + return { + "x": _variant_to_json(value.x), + "y": _variant_to_json(value.y), + "origin": _variant_to_json(value.origin), + } + if value is Rect2: + return { + "position": _variant_to_json(value.position), + "size": _variant_to_json(value.size), + } + if value is Rect2i: + return { + "position": _variant_to_json(value.position), + "size": _variant_to_json(value.size), + } + if value is AABB: + return { + "position": _variant_to_json(value.position), + "size": _variant_to_json(value.size), + } + if value is NodePath or value is StringName: + return str(value) + if value is Plane: + return { + "normal": _variant_to_json(value.normal), + "d": value.d, + } + if value is Projection: + return { + "x": _variant_to_json(value.x), + "y": _variant_to_json(value.y), + "z": _variant_to_json(value.z), + "w": _variant_to_json(value.w), + } + ## Packed arrays + if value is PackedByteArray: + var arr: Array = [] + for item in value: arr.append(item) + return arr + if value is PackedInt32Array or value is PackedInt64Array: + var arr: Array = [] + for item in value: arr.append(item) + return arr + if value is PackedFloat32Array or value is PackedFloat64Array: + var arr: Array = [] + for item in value: arr.append(item) + return arr + if value is PackedStringArray: + var arr: Array = [] + for item in value: arr.append(item) + return arr + if value is PackedVector2Array: + var arr: Array = [] + for item in value: arr.append({"x": item.x, "y": item.y}) + return arr + if value is PackedVector3Array: + var arr: Array = [] + for item in value: arr.append({"x": item.x, "y": item.y, "z": item.z}) + return arr + if value is PackedVector4Array: + var arr: Array = [] + for item in value: arr.append({"x": item.x, "y": item.y, "z": item.z, "w": item.w}) + return arr + if value is PackedColorArray: + var arr: Array = [] + for item in value: arr.append({"r": item.r, "g": item.g, "b": item.b, "a": item.a}) + return arr + ## Generic arrays and dictionaries — recurse + if value is Array: + var arr: Array = [] + for item in value: + arr.append(_variant_to_json(item)) + return arr + if value is Dictionary: + var dict: Dictionary = {} + for key in value.keys(): + dict[str(key)] = _variant_to_json(value[key]) + return dict + ## Fallback: string representation + return str(value) diff --git a/addons/godot_ai/runtime/game_helper.gd.uid b/addons/godot_ai/runtime/game_helper.gd.uid new file mode 100644 index 0000000..7224a50 --- /dev/null +++ b/addons/godot_ai/runtime/game_helper.gd.uid @@ -0,0 +1 @@ +uid://gfybkdtsclti diff --git a/addons/godot_ai/runtime/game_logger.gd b/addons/godot_ai/runtime/game_logger.gd new file mode 100644 index 0000000..6384960 --- /dev/null +++ b/addons/godot_ai/runtime/game_logger.gd @@ -0,0 +1,142 @@ +@tool +extends Logger + +## Game-process Logger subclass. +## +## NOTE: deliberately no `class_name`. Registered from inside the running +## game so we can intercept print(), printerr(), push_error(), and +## push_warning() and ferry them back to the editor over the EngineDebugger +## channel — the same bridge PR #76 uses for screenshots. +## +## Logger virtuals can be called from any thread (e.g. async loaders push +## errors off the main thread). We accumulate into _pending under a Mutex +## and the host (game_helper.gd) flushes once per frame from the main +## thread, where EngineDebugger.send_message is safe to call. + +## `McpLogBacktrace` is published as a `class_name` on log_backtrace.gd, but a +## freshly-launched game subprocess (no prior editor scan; e.g. CI launching +## `--headless --path`) hits this autoload before the global class_name table +## is populated, and parsing this script fails with +## "Identifier 'McpLogBacktrace' not declared in the current scope". Using +## `const preload` resolves the path at parse time and is independent of the +## class_name registry — matches the project convention in CLAUDE.md +## ("Internals … skip class_name entirely and load via const preload"). +const _LogBacktrace := preload("res://addons/godot_ai/utils/log_backtrace.gd") + +var _pending: Array = [] +var _mutex := Mutex.new() +## #490: a monotonic sequence + a small ring of recent GDScript runtime +## (script-type) errors, each with its text AND the function names in its +## backtrace. game_helper uses this to attribute a runtime error to the +## *specific* eval that raised it: each eval's wrapper has a uniquely named +## inner function, and game_helper asks find_script_error_since() whether any +## error past its pre-eval baseline carries that function in its stack. This +## avoids failing an eval on an unrelated background game error that merely +## advanced a global counter, and keeps overlapping evals from cross- +## attributing. Gated on ERROR_TYPE_SCRIPT (2) so push_error()/push_warning() +## (types 0/1) never count. Mutex-guarded: _log_error can fire from any thread. +const _ERROR_TYPE_SCRIPT := 2 +const _MAX_RECENT_SCRIPT_ERRORS := 64 +var _script_error_seq: int = 0 +var _recent_script_errors: Array = [] + + +func _log_message(message: String, error: bool) -> void: + ## `error` is true for printerr(), false for print(). + var level := "error" if error else "info" + _append(level, message) + + +func _log_error( + function: String, + file: String, + line: int, + code: String, + rationale: String, + _editor_notify: bool, + error_type: int, + script_backtraces: Array, +) -> void: + ## EngineDebugger's payload shape is `[level, text]` — the source + ## location has nowhere structured to land for the game side, so we + ## inline it into `text`. editor_logger keeps the resolved fields + ## as structured columns instead. + var resolved := _LogBacktrace.resolve_error( + function, file, line, code, rationale, error_type, script_backtraces, + ) + var loc := "" + if not resolved.path.is_empty(): + loc = "%s:%d @ %s" % [resolved.path, resolved.line, resolved.function] if not resolved.function.is_empty() else "%s:%d" % [resolved.path, resolved.line] + var text: String = "%s (%s)" % [resolved.message, loc] if not loc.is_empty() else resolved.message + var details: Dictionary = resolved.get("details", {}) + _append(resolved.level, text, details) + if error_type == _ERROR_TYPE_SCRIPT: + ## Collect every function name in the first non-empty backtrace so + ## game_helper can match its eval's uniquely named wrapper function. + var funcs := PackedStringArray() + for bt: RefCounted in script_backtraces: + if bt != null and bt.get_frame_count() > 0: + for i: int in bt.get_frame_count(): + funcs.append(bt.get_frame_function(i)) + break + _mutex.lock() + _script_error_seq += 1 + _recent_script_errors.append({"seq": _script_error_seq, "text": text, "funcs": funcs}) + if _recent_script_errors.size() > _MAX_RECENT_SCRIPT_ERRORS: + _recent_script_errors.remove_at(0) + _mutex.unlock() + + +func _append(level: String, text: String, details: Dictionary = {}) -> void: + _mutex.lock() + if details.is_empty(): + _pending.append([level, text]) + else: + _pending.append([level, text, details.duplicate(true)]) + _mutex.unlock() + + +## Drain the pending queue and return entries as [[level, text], ...]. +## Called from the main thread by game_helper each frame. +func drain() -> Array: + _mutex.lock() + var out := _pending + _pending = [] + _mutex.unlock() + return out + + +func has_pending() -> bool: + _mutex.lock() + var any := not _pending.is_empty() + _mutex.unlock() + return any + + +## #490: monotonic count of script-type runtime errors seen this run. +## game_helper snapshots this before an eval to use as the `since_seq` +## baseline for find_script_error_since(). Mutex-guarded. +func script_error_seq() -> int: + _mutex.lock() + var v := _script_error_seq + _mutex.unlock() + return v + + +## #490: text of the most recent script error with seq > since_seq whose +## backtrace includes `function_name`, or "" if none. Lets game_helper +## attribute a runtime error to the exact eval whose uniquely named wrapper +## function appears in the stack — ignoring unrelated game errors and errors +## from before the eval started. Mutex-guarded. +func find_script_error_since(since_seq: int, function_name: String) -> String: + _mutex.lock() + var found := "" + for i in range(_recent_script_errors.size() - 1, -1, -1): + var rec: Dictionary = _recent_script_errors[i] + if int(rec["seq"]) <= since_seq: + break + if (rec["funcs"] as PackedStringArray).has(function_name): + found = rec["text"] + break + _mutex.unlock() + return found diff --git a/addons/godot_ai/runtime/game_logger.gd.uid b/addons/godot_ai/runtime/game_logger.gd.uid new file mode 100644 index 0000000..d4e263e --- /dev/null +++ b/addons/godot_ai/runtime/game_logger.gd.uid @@ -0,0 +1 @@ +uid://dwcs6d1y7vhqi diff --git a/addons/godot_ai/runtime/validation_logger.gd b/addons/godot_ai/runtime/validation_logger.gd new file mode 100644 index 0000000..672b11f --- /dev/null +++ b/addons/godot_ai/runtime/validation_logger.gd @@ -0,0 +1,43 @@ +@tool +extends Logger + +## Short-lived Logger used only for per-write validation loads. +## +## Unlike editor_logger.gd this deliberately has no addon feedback-loop filter: +## the caller attaches it around one ResourceLoader.load() call, reads its +## private buffer, and immediately removes it. The shared editor logger should +## still drop these validation-load errors so logs_read(source="editor") stays +## clean. + +const _LogBacktrace := preload("res://addons/godot_ai/utils/log_backtrace.gd") + +var _buffer + + +func _init(buffer = null) -> void: + _buffer = buffer + + +func _log_error( + function: String, + file: String, + line: int, + code: String, + rationale: String, + _editor_notify: bool, + error_type: int, + script_backtraces: Array, +) -> void: + if _buffer == null: + return + var resolved := _LogBacktrace.resolve_error( + function, + file, + line, + code, + rationale, + error_type, + script_backtraces, + ) + var details: Dictionary = resolved.get("details", {}) + _buffer.append(resolved.level, resolved.message, resolved.path, resolved.line, resolved.function, details) diff --git a/addons/godot_ai/runtime/validation_logger.gd.uid b/addons/godot_ai/runtime/validation_logger.gd.uid new file mode 100644 index 0000000..4e693b4 --- /dev/null +++ b/addons/godot_ai/runtime/validation_logger.gd.uid @@ -0,0 +1 @@ +uid://b2ff3aot6t2l4 diff --git a/addons/godot_ai/telemetry.gd b/addons/godot_ai/telemetry.gd new file mode 100644 index 0000000..dc90bf9 --- /dev/null +++ b/addons/godot_ai/telemetry.gd @@ -0,0 +1,198 @@ +## Plugin-side telemetry helper. +## +## Relays plugin-only events (dock startup, self-update outcome, plugin +## reload, dev-server toggle) to the Python MCP server via the existing +## `send_event("plugin_event", {...})` channel. The server's +## `transport/websocket.py` allowlists event names and forwards into the +## central telemetry pipeline — meaning opt-out, endpoint, customer_uuid +## and the bounded-queue worker stay in one place (Python), not +## duplicated in GDScript. +## +## Opt-out options priority: +## 1. `GODOT_AI_DISABLE_TELEMETRY` / `DISABLE_TELEMETRY` env vars — +## checked first so CI / operators can force-disable without touching +## EditorSettings. +## 2. The `godot_ai/telemetry_enabled` EditorSetting — set through the +## MCP dock and persisted between sessions. +## +## When telemetry is disabled, events are never buffered or sent. Only a +## *truthy* env var force-disables; a falsey or absent env var falls through +## to the EditorSetting (which defaults to enabled). See McpSettings.telemetry_enabled. +## +## Buffering: events recorded before the WebSocket is connected go into +## a small bounded buffer and flush on the next `record_event` call once +## connected. The buffer is intentionally small (`_MAX_BUFFER`); plugin +## events are sparse, and a flood means something is misconfigured. + +extends RefCounted + +## Allowlist mirrored on the Python side in +## `src/godot_ai/transport/websocket.py::_PLUGIN_EVENT_NAMES`. Update +## both together. +const _ALLOWED_EVENTS := [ + "dock_startup", + "plugin_reload", + "self_update", + "dev_server_toggle", +] + +const _MAX_BUFFER := 32 + +## EditorSetting key used to defer a ``plugin_reload`` event across the +## disable -> enable boundary. Callers that trigger plugin reload (the +## dock reload button, ``editor_reload_plugin`` MCP-tool path) write +## here *before* the disable kills the live WebSocket; the new +## plugin's ``_enter_tree`` flushes via ``flush_pending_plugin_reload``. +const PENDING_PLUGIN_RELOAD_KEY := "godot_ai/pending_plugin_reload_event" + + +## Persist a ``plugin_reload`` event so the re-enabled plugin instance +## can emit it once its new WebSocket is up. Static so callers without +## a telemetry instance handle (e.g. ``editor_handler.reload_plugin``) +## can use it via the preloaded const alias. +static func record_pending_plugin_reload(source: String) -> void: + var settings := EditorInterface.get_editor_settings() + if settings == null: + return + settings.set_setting( + PENDING_PLUGIN_RELOAD_KEY, + JSON.stringify({"source": source, "success": true}), + ) + + +## Read + clear an EditorSetting JSON-encoded event payload. Returns +## the parsed dict, or ``null`` if the key is absent / empty / +## malformed. Used by ``flush_pending_plugin_reload`` (below) and by +## ``plugin.gd::_flush_pending_self_update_telemetry``. Centralising +## the read-and-clear dance keeps both flush sites symmetric with the +## ``record_pending_*`` writers and prevents the "key gets stuck" +## class of bug if a future flush helper forgets the clear step. +static func _drain_editor_setting_dict(key: String): + var settings := EditorInterface.get_editor_settings() + if settings == null: + return null + if not settings.has_setting(key): + return null + var raw := str(settings.get_setting(key)) + settings.set_setting(key, "") + if raw == "": + return null + var parsed = JSON.parse_string(raw) + if typeof(parsed) != TYPE_DICTIONARY: + return null + return parsed + +var _connection +var _disabled: bool = false +var _pending: Array = [] # of {name: String, data: Dictionary} + +func _init(connection) -> void: + _connection = connection + _disabled = not McpSettings.telemetry_enabled() + ## Subscribe to ``connection_state_changed`` so events buffered before + ## the WebSocket handshake (e.g. ``record_dock_startup`` from + ## ``plugin._enter_tree``) actually leave the editor. Without this, + ## the buffer only drained on the next ``record_event`` call — when + ## that call never came (the common single-session case), the very + ## events we cared about most sat in the queue forever. + if _connection != null and _connection.has_signal("connection_state_changed"): + _connection.connection_state_changed.connect(_on_connection_state_changed) + + +func record_event(name: String, data: Dictionary = {}) -> void: + if _disabled: + return + if not _ALLOWED_EVENTS.has(name): + ## Drop silently — matches the server's behavior for unknown + ## names, and avoids editor yellow-bar noise from third-party + ## callers or stale event names mid-rollout. + return + if _connection != null and _connection.is_connected: + _flush() + _send_one(name, data) + return + ## Pre-handshake: stash in a small bounded buffer. Drained on the + ## first ``connection_state_changed(true)`` after this point (see + ## ``_on_connection_state_changed``). Falling back to "drain on the + ## next record_event" is a footgun: the most useful plugin events + ## (``dock_startup``, pending ``self_update``) fire from + ## ``plugin._enter_tree`` before the handshake, and a single-session + ## editor may never emit a second event — so without the signal- + ## driven flush they sat buffered forever. + if _pending.size() >= _MAX_BUFFER: + _pending.pop_front() + _pending.append({"name": name, "data": data}) + + +func _on_connection_state_changed(is_open: bool) -> void: + if is_open: + _flush() + +func _flush() -> void: + if _pending.is_empty(): + return + var to_send := _pending.duplicate() + _pending.clear() + for entry in to_send: + _send_one(entry["name"], entry["data"]) + +func _send_one(name: String, data: Dictionary) -> void: + if _connection == null: + return + _connection.send_event("plugin_event", {"name": name, "data": data}) + +# --- convenience emitters -------------------------------------------------- + +func record_dock_startup(extra: Dictionary = {}) -> void: + record_event("dock_startup", extra) + +func record_self_update( + status: String, + from_version: String = "", + to_version: String = "", + error: String = "", +) -> void: + var data := {"status": status} + if from_version != "": + data["from_version"] = from_version + if to_version != "": + data["to_version"] = to_version + if error != "": + data["error"] = error.substr(0, 200) + record_event("self_update", data) + +func record_dev_server_toggle(action: String) -> void: + record_event("dev_server_toggle", {"action": action}) + + +## Drain a pending ``plugin_reload`` event written by the previous +## instance before it disabled itself. Pending events are currently +## always success=true — ``record_pending_plugin_reload`` above is the +## only writer and hardcodes it (a reload that fails never reaches the +## flush anyway; there is no new instance to drain the key). The +## error/success parsing below stays tolerant for forward compat with +## a writer that records failures. +func flush_pending_plugin_reload() -> void: + var parsed = _drain_editor_setting_dict(PENDING_PLUGIN_RELOAD_KEY) + if parsed == null: + return + var data := { + "success": bool(parsed.get("success", true)), + "source": str(parsed.get("source", "unknown")), + } + var error := str(parsed.get("error", "")) + if error != "": + data["error"] = error.substr(0, 200) + record_event("plugin_reload", data) + +# --- test seam ------------------------------------------------------------- + +## Inject a fake connection or force the disabled flag for unit tests +## that don't have a live WebSocket. Production code does not call this. +func _test_set_state(connection, disabled: bool) -> void: + _connection = connection + _disabled = disabled + _pending.clear() + +func _test_pending_count() -> int: + return _pending.size() diff --git a/addons/godot_ai/telemetry.gd.uid b/addons/godot_ai/telemetry.gd.uid new file mode 100644 index 0000000..6f46be6 --- /dev/null +++ b/addons/godot_ai/telemetry.gd.uid @@ -0,0 +1 @@ +uid://dlul2gculiy1p diff --git a/addons/godot_ai/testing/script_error_capture.gd b/addons/godot_ai/testing/script_error_capture.gd new file mode 100644 index 0000000..92c53ed --- /dev/null +++ b/addons/godot_ai/testing/script_error_capture.gd @@ -0,0 +1,49 @@ +@tool +extends Logger + +## Captures GDScript runtime errors emitted while a test is running. +## +## Deliberately no class_name: this is an internal test helper. +## +## Only ERROR_TYPE_SCRIPT is captured. push_error(), push_warning(), and +## engine-internal ERR_FAIL_* checks are often valid negative-path assertions and +## should not abort the test. + +var _mutex := Mutex.new() +var _capturing := false +var _errors := PackedStringArray() + + +func begin_capture() -> void: + _mutex.lock() + _capturing = true + _errors.clear() + _mutex.unlock() + + +func end_capture() -> PackedStringArray: + _mutex.lock() + var captured := _errors.duplicate() + _capturing = false + _errors.clear() + _mutex.unlock() + return captured + + +func _log_error( + function: String, + file: String, + line: int, + code: String, + rationale: String, + _editor_notify: bool, + error_type: int, + _script_backtraces: Array, +) -> void: + if error_type != ERROR_TYPE_SCRIPT: + return + _mutex.lock() + if _capturing: + var text := rationale if not rationale.is_empty() else code + _errors.append("%s (%s:%d in %s)" % [text, file, line, function]) + _mutex.unlock() diff --git a/addons/godot_ai/testing/script_error_capture.gd.uid b/addons/godot_ai/testing/script_error_capture.gd.uid new file mode 100644 index 0000000..6b2d712 --- /dev/null +++ b/addons/godot_ai/testing/script_error_capture.gd.uid @@ -0,0 +1 @@ +uid://crk8w2nei087v diff --git a/addons/godot_ai/testing/test_runner.gd b/addons/godot_ai/testing/test_runner.gd new file mode 100644 index 0000000..1aa0041 --- /dev/null +++ b/addons/godot_ai/testing/test_runner.gd @@ -0,0 +1,441 @@ +@tool +class_name McpTestRunner +extends RefCounted + +## Lightweight test runner for MCP plugin tests. Discovers test_* methods +## on McpTestSuite instances, runs them, and collects structured results. + +const ScriptErrorCapture := preload("res://addons/godot_ai/testing/script_error_capture.gd") + +var _results: Array[Dictionary] = [] +var _last_run_ms: int = 0 +var _script_error_capture: ScriptErrorCapture = null +var _capture_registered := false + + +func _notification(what: int) -> void: + if what == NOTIFICATION_PREDELETE and _capture_registered and _script_error_capture != null: + OS.remove_logger(_script_error_capture) + _capture_registered = false + + +func run_suite(suite: McpTestSuite, test_filter: String = "", exclude_test_filter: String = "") -> void: + var owns_capture := not _capture_registered + if owns_capture: + _register_capture() + + _run_suite_tests(suite, test_filter, exclude_test_filter, Callable(), 0, {}) + + if owns_capture: + _unregister_capture() + + +## Shared per-test loop for both the legacy synchronous path and the +## serviced driver. Returns "" when the loop completed, or a terminal +## outcome ("timeout" / "transport_lost" / "paused") when a checkpoint +## aborted it. Checkpoints run BETWEEN tests — an atomic test body is +## never preempted (see docs/test-run-transport-starvation-plan.md). +func _run_suite_tests( + suite: McpTestSuite, + test_filter: String, + exclude_test_filter: String, + service_cb: Callable, + deadline_ticks_ms: int, + run_state: Dictionary, +) -> String: + var name := suite.suite_name() + var methods := _get_test_methods(suite) + var exclusions := _parse_exclusions(exclude_test_filter) + + for method_name in methods: + if not test_filter.is_empty() and method_name.find(test_filter) == -1: + continue + _selected_processed += 1 + if _matches_any_exclusion(method_name, exclusions): + _results.append({ + "suite": name, + "test": method_name, + "passed": true, + "skipped": true, + "message": "Excluded by exclude_test_name filter", + "assertion_count": 0, + "duration_ms": 0, + }) + continue + + var test_start := Time.get_ticks_msec() + var entry := _run_one_test(suite, name, method_name) + entry["duration_ms"] = Time.get_ticks_msec() - test_start + _results.append(entry) + + var stop := _checkpoint(service_cb, deadline_ticks_ms, run_state) + if not stop.is_empty(): + return stop + return "" + + +## Execute one test method and return its result entry (not yet appended; +## the caller stamps `duration_ms`). Extracted from run_suite so the legacy +## and serviced drivers share one execution core — behavior must stay +## byte-identical to the pre-refactor loop body. +func _run_one_test(suite: McpTestSuite, name: String, method_name: String) -> Dictionary: + suite._reset() + _begin_script_error_capture() + suite.setup() + suite.call(method_name) + suite.teardown() + var script_errors := suite._unexpected_script_errors(_end_script_error_capture()) + suite._free_tracked() + + ## Issue #19 defence: free any `_McpTest*` nodes the test created, even + ## nested ones. If the scene gets auto-saved mid-test while one of these + ## exists, the reference bakes into main.tscn and breaks the next open + ## with a "missing dependency" error. Runs after every test, not just at + ## suite boundaries, so a test that fails mid-flow can't leave a trap + ## for the next test or for scene autosave. + var scene_root_for_cleanup := _edited_scene_root() + if scene_root_for_cleanup != null and scene_root_for_cleanup.is_inside_tree(): + _free_mcp_test_nodes_recursive(scene_root_for_cleanup) + + if not script_errors.is_empty(): + var abort_message := "Aborted by SCRIPT ERROR: %s" % "; ".join(script_errors) + if suite._failed: + abort_message += " (after assertion failure: %s)" % suite._message + return { + "suite": name, + "test": method_name, + "passed": false, + "message": abort_message, + "assertion_count": suite._assertion_count, + } + + ## A failed assertion always wins over a later skip(): a test that + ## fails and then hits a skip-guard must report the failure, not + ## park itself as green-skipped. + if suite._skipped and not suite._failed: + return { + "suite": name, + "test": method_name, + "passed": true, + "skipped": true, + "message": suite._skip_reason, + "assertion_count": 0, + } + + var passed := not suite._failed + var msg := suite._message + + ## Warn about zero-assertion tests (likely silently skipped logic). + if passed and suite._assertion_count == 0: + passed = false + msg = "Test completed with 0 assertions (likely skipped its logic)" + + return { + "suite": name, + "test": method_name, + "passed": passed, + "message": msg, + "assertion_count": suite._assertion_count, + } + + +func run_suites(suites: Array, suite_filter: String = "", test_filter: String = "", ctx: Dictionary = {}, verbose: bool = false, exclude_test_filter: String = "") -> Dictionary: + ## Legacy synchronous API — unchanged signature and semantics for direct + ## callers, unit-test fixtures, and any batch context. No servicing, no + ## ceiling: with an invalid Callable and deadline 0 every checkpoint is a + ## no-op and the outcome is always "completed". + var run := run_suites_serviced(suites, suite_filter, test_filter, ctx, verbose, exclude_test_filter) + return run["results"] + + +## Serviced driver for live MCP runs. Between tests and at suite +## boundaries it (a) aborts once `deadline_ticks_ms` passes and (b) calls +## `service_cb` (McpConnection.service_transport_during_exclusive_run) so +## the WebSocket heartbeat stays alive while the suite monopolizes the +## main thread. Returns: +## { +## "outcome": "completed" | "timeout" | "transport_lost" | "paused", +## "results": , +## "tests_not_run": , +## } +## Every outcome path — including aborts — runs the current suite's +## teardown + leak cleanup, restores console echo, and unregisters the +## capture logger. `run_state` is caller-owned and threaded through to the +## service callback (cumulative packet counter lives there). +func run_suites_serviced( + suites: Array, + suite_filter: String = "", + test_filter: String = "", + ctx: Dictionary = {}, + verbose: bool = false, + exclude_test_filter: String = "", + service_cb: Callable = Callable(), + deadline_ticks_ms: int = 0, + run_state: Dictionary = {}, +) -> Dictionary: + _results.clear() + _selected_processed = 0 + var selected_total := _count_selected_tests(suites, suite_filter, test_filter) + var start := Time.get_ticks_msec() + var outcome := "" + + ## Silence the plugin's ring-buffer console echo while tests run. Negative- + ## path suites deliberately fill the ring with 500 lines and log malformed- + ## result errors; echoing all of that buries an all-green run in scary + ## console output. The ring contents tests assert on are untouched, and + ## the flag is restored after the run so live logging resumes. + var _prev_console_echo := McpLogBuffer.console_echo + McpLogBuffer.console_echo = false + + ## If a prior run was interrupted after registering the logger but before + ## normal teardown, remove that stale registration before starting fresh. + _unregister_capture() + _register_capture() + + for suite: McpTestSuite in suites: + if not suite_filter.is_empty() and suite.suite_name() != suite_filter: + continue + + ## Snapshot scene children before the suite so we can clean up leaks. + var scene_root := _edited_scene_root() + var before_children: Array[Node] = [] + if scene_root != null: + before_children = _get_children_snapshot(scene_root) + + suite._reset_suite_state() + suite.suite_setup(ctx.duplicate(true)) + + ## fail_setup() / skip_suite() gives suites a clean way to bail out of + ## suite_setup without leaving N tests to fail with "0 assertions". We + ## emit ONE suite-level result and skip individual tests entirely. + if suite._suite_failed: + _results.append({ + "suite": suite.suite_name(), + "test": "", + "passed": false, + "message": "suite_setup() failed: %s (subsequent tests not run)" % suite._suite_failed_message, + "assertion_count": 0, + }) + ## The bailed suite's tests are accounted for, not "not run". + _selected_processed += _count_selected_tests([suite], "", test_filter) + elif suite._suite_skipped: + _results.append({ + "suite": suite.suite_name(), + "test": "", + "passed": true, + "skipped": true, + "message": "suite_setup() skipped: %s" % suite._suite_skipped_reason, + "assertion_count": 0, + }) + _selected_processed += _count_selected_tests([suite], "", test_filter) + else: + outcome = _checkpoint(service_cb, deadline_ticks_ms, run_state) + if outcome.is_empty(): + outcome = _run_suite_tests( + suite, test_filter, exclude_test_filter, + service_cb, deadline_ticks_ms, run_state + ) + ## Suite epilogue runs on EVERY path, including aborts: the suite has + ## begun, so its teardown and leak cleanup must not be skipped. + suite.suite_teardown() + suite._free_tracked() + + ## Remove any nodes the suite left behind (failed undo, missing cleanup). + if scene_root != null and scene_root.is_inside_tree(): + _cleanup_leaked_nodes(scene_root, before_children) + + if not outcome.is_empty(): + break + + outcome = _checkpoint(service_cb, deadline_ticks_ms, run_state) + if not outcome.is_empty(): + break + + _last_run_ms = Time.get_ticks_msec() - start + McpLogBuffer.console_echo = _prev_console_echo + _unregister_capture() + if outcome.is_empty(): + outcome = "completed" + return { + "outcome": outcome, + "results": get_results(verbose), + "tests_not_run": maxi(0, selected_total - _selected_processed), + } + + +## Count of selected (filter-surviving) tests already looped over this run, +## including exclusion-skips and bailed-suite accounting. Drives the +## `tests_not_run` estimate on aborted runs. +var _selected_processed := 0 + + +func _count_selected_tests(suites: Array, suite_filter: String, test_filter: String) -> int: + var count := 0 + for suite: McpTestSuite in suites: + if not suite_filter.is_empty() and suite.suite_name() != suite_filter: + continue + for method_name in _get_test_methods(suite): + if not test_filter.is_empty() and method_name.find(test_filter) == -1: + continue + count += 1 + return count + + +## Between-phase checkpoint: "" to continue, or a terminal outcome. +## Delegates to the shared mapping so the discovery checkpoints in +## test_handler.gd can never drift from the between-test ones (plan §9 Q2). +func _checkpoint(service_cb: Callable, deadline_ticks_ms: int, run_state: Dictionary) -> String: + return McpConnection.exclusive_run_checkpoint(service_cb, deadline_ticks_ms, run_state) + + +func _register_capture() -> void: + if _capture_registered: + return + if _script_error_capture == null: + _script_error_capture = ScriptErrorCapture.new() + if _script_error_capture == null: + return + OS.add_logger(_script_error_capture) + _capture_registered = true + + +func _unregister_capture() -> void: + if not _capture_registered: + return + if _script_error_capture == null: + _capture_registered = false + return + OS.remove_logger(_script_error_capture) + _capture_registered = false + + +func _begin_script_error_capture() -> void: + if _script_error_capture != null and _capture_registered: + _script_error_capture.begin_capture() + + +func _end_script_error_capture() -> PackedStringArray: + if _script_error_capture == null or not _capture_registered: + return PackedStringArray() + return _script_error_capture.end_capture() + + +static func _edited_scene_root() -> Node: + if not Engine.is_editor_hint(): + return null + return EditorInterface.get_edited_scene_root() + + +func get_results(verbose: bool = false) -> Dictionary: + var passed := 0 + var failed := 0 + var skipped := 0 + var failures: Array[Dictionary] = [] + var suites_seen := {} + for r in _results: + suites_seen[r.suite] = true + if r.get("skipped", false): + skipped += 1 + elif r.passed: + passed += 1 + else: + failed += 1 + failures.append(r) + + var result := { + "passed": passed, + "failed": failed, + "skipped": skipped, + "total": _results.size(), + "duration_ms": _last_run_ms, + "suites_run": suites_seen.keys(), + "suite_count": suites_seen.size(), + } + + if not failures.is_empty(): + result["failures"] = failures + + if verbose: + result["results"] = _results + + return result + + +func clear() -> void: + _results.clear() + _last_run_ms = 0 + + +func _get_test_methods(obj: Object) -> Array[String]: + var methods: Array[String] = [] + for m in obj.get_method_list(): + var name: String = m.get("name", "") + if name.begins_with("test_"): + methods.append(name) + methods.sort() + return methods + + +func _get_children_snapshot(node: Node) -> Array[Node]: + var children: Array[Node] = [] + for child in node.get_children(): + children.append(child) + return children + + +## Remove any nodes in scene_root that weren't present before the suite ran, +## plus any _McpTest* named nodes anywhere in the tree (catches nested leaks). +## NOTE: this bypasses EditorUndoRedoManager by design — the test runner +## owns these leaks and needs to clear them unconditionally. Don't Ctrl-Z in +## the editor immediately after a test run that triggered cleanup; the undo +## stack may reference freed nodes. +func _cleanup_leaked_nodes(scene_root: Node, before: Array[Node]) -> void: + var before_set := {} + for n in before: + before_set[n] = true + for child in scene_root.get_children(): + if not before_set.has(child): + scene_root.remove_child(child) + child.queue_free() + + +## Recursively free every node whose name starts with `_McpTest`, anywhere in +## the scene. Intentionally bypasses undo — these are test leaks, not user +## work. Walk breadth-first so we can collect victims before mutating the tree. +func _free_mcp_test_nodes_recursive(root: Node) -> void: + var victims: Array[Node] = [] + var queue: Array[Node] = [root] + while not queue.is_empty(): + var node: Node = queue.pop_back() + for child in node.get_children(): + if str(child.name).begins_with("_McpTest"): + victims.append(child) + else: + queue.append(child) + for v in victims: + if v.get_parent() != null: + v.get_parent().remove_child(v) + v.queue_free() + + +## Split the `exclude_test_name` filter into individual substring matchers. +## Comma-separated so the CI smoke harness can list multiple flaky tests +## without shipping a richer schema (single names still work — same string, +## no comma, same one-element list). Whitespace around each name is stripped +## so `"a, b"` and `"a,b"` behave identically. +static func _parse_exclusions(filter: String) -> Array[String]: + var out: Array[String] = [] + if filter.is_empty(): + return out + for part in filter.split(","): + var trimmed := part.strip_edges() + if not trimmed.is_empty(): + out.append(trimmed) + return out + + +static func _matches_any_exclusion(method_name: String, exclusions: Array[String]) -> bool: + for ex in exclusions: + if method_name.find(ex) != -1: + return true + return false diff --git a/addons/godot_ai/testing/test_runner.gd.uid b/addons/godot_ai/testing/test_runner.gd.uid new file mode 100644 index 0000000..c0befb0 --- /dev/null +++ b/addons/godot_ai/testing/test_runner.gd.uid @@ -0,0 +1 @@ +uid://367b77qh5grt diff --git a/addons/godot_ai/testing/test_suite.gd b/addons/godot_ai/testing/test_suite.gd new file mode 100644 index 0000000..57b3bef --- /dev/null +++ b/addons/godot_ai/testing/test_suite.gd @@ -0,0 +1,330 @@ +@tool +class_name McpTestSuite +extends RefCounted + +## Base class for MCP test suites. Provides assertion methods and +## lifecycle hooks. Subclass this, add test_* methods, and drop the +## script in res://tests/. + +## Override to return a short name for this suite (e.g. "scene", "node"). +func suite_name() -> String: + return "unnamed" + + +## Called once before the suite runs. Override to create handlers. +func suite_setup(_ctx: Dictionary) -> void: + pass + + +## Called before each test method. +func setup() -> void: + pass + + +## Called after each test method. +func teardown() -> void: + pass + + +## Called once after the suite finishes. +func suite_teardown() -> void: + pass + + +# ----- tracked allocations (freed by the runner after each test) ----- + +var _tracked_objects: Array[Object] = [] + + +## Register a manually-managed Object (plain Object or out-of-tree Node) so +## the runner frees it after the current test. RefCounted instances are +## accepted but ignored because they manage their own lifetime. +func track(obj: Object) -> Object: + if obj != null and not obj is RefCounted: + _tracked_objects.append(obj) + return obj + + +## Free everything registered via track(). Called by the runner after each +## test's teardown() and again after suite_teardown(). +func _free_tracked() -> void: + for obj in _tracked_objects: + if not is_instance_valid(obj) or (obj is Node and obj.is_queued_for_deletion()): + continue + if obj is Node: + var parent := (obj as Node).get_parent() + if parent != null: + parent.remove_child(obj) + obj.free() + _tracked_objects.clear() + + +# ----- assertion state (managed by McpTestRunner) ----- + +var _failed: bool = false +var _message: String = "" +var _assertion_count: int = 0 +var _skipped: bool = false +var _skip_reason: String = "" +var _expected_script_error_substrings: Array[String] = [] + +# ----- suite-level state (managed by McpTestRunner) ----- + +var _suite_failed: bool = false +var _suite_failed_message: String = "" +var _suite_skipped: bool = false +var _suite_skipped_reason: String = "" + + +func _reset() -> void: + _failed = false + _message = "" + _assertion_count = 0 + _skipped = false + _skip_reason = "" + _expected_script_error_substrings.clear() + + +func _reset_suite_state() -> void: + _suite_failed = false + _suite_failed_message = "" + _suite_skipped = false + _suite_skipped_reason = "" + + +## Mark the current test as skipped. Use when a precondition isn't met +## (e.g. no scene open, no Node3D in scene) and the test can't run. +## Skipped tests count separately from passed/failed. +func skip(reason: String = "") -> void: + _skipped = true + _skip_reason = reason + + +## Bail out of suite_setup() with a failure. Subsequent tests in this suite +## are not run; the runner reports a single suite-level failure with the +## given reason instead of N zero-assertion noise lines per test. +## +## Example: +## func suite_setup(ctx): +## var arena = preload("res://game/arena.gd").new() +## if arena == null: +## fail_setup("arena.gd failed to instantiate in @tool scope") +## return +func fail_setup(reason: String) -> void: + _suite_failed = true + _suite_failed_message = reason + + +## Bail out of suite_setup() because a precondition isn't met (no scene open, +## no game running, etc.). Subsequent tests are not run and the runner emits +## a single suite-level skip rather than per-test skip noise. +func skip_suite(reason: String) -> void: + _suite_skipped = true + _suite_skipped_reason = reason + + +## Mark the current test as skipped when the running Godot is older than +## `min_version` (a "major.minor" string like "4.6"). Use for tests that +## exercise an engine API or behavior that only exists on newer Godot. +## Returns true when the test was skipped, so callers can `return` from +## the test body. +## +## Example: +## func test_uses_46_only_api() -> void: +## if skip_on_godot_lt("4.6", "example API requires Godot 4.6+"): +## return +## ... +func skip_on_godot_lt(min_version: String, reason: String = "") -> bool: + var v := Engine.get_version_info() + var current_major := int(v.get("major", 0)) + var current_minor := int(v.get("minor", 0)) + var parts := min_version.split(".") + var want_major := int(parts[0]) if parts.size() > 0 else 0 + var want_minor := int(parts[1]) if parts.size() > 1 else 0 + if ( + current_major < want_major + or (current_major == want_major and current_minor < want_minor) + ): + var msg := reason if not reason.is_empty() else "requires Godot %s+" % min_version + skip(msg + " (running %d.%d)" % [current_major, current_minor]) + return true + return false + + +## Allow one captured SCRIPT ERROR whose text contains `substring`. +## Use only for negative-path tests that intentionally compile or execute +## invalid GDScript and assert on the resulting diagnostics. +func expect_script_error_containing(substring: String) -> void: + _expected_script_error_substrings.append(substring) + + +func _unexpected_script_errors(captured: PackedStringArray) -> PackedStringArray: + var unexpected := PackedStringArray() + var remaining := _expected_script_error_substrings.duplicate() + for error in captured: + var matched_index := -1 + for i in range(remaining.size()): + if error.find(remaining[i]) != -1: + matched_index = i + break + if matched_index == -1: + unexpected.append(error) + else: + remaining.remove_at(matched_index) + return unexpected + + +## Trigger an undo against whichever history (scene or global) holds the most +## recent action. `EditorUndoRedoManager` in Godot 4.x doesn't expose `.undo()` +## directly — you resolve the history's underlying UndoRedo and call it there. +## Actions registered via `add_do_method(self, …)` with a non-scene target land +## in GLOBAL_HISTORY, while actions on scene nodes land in the scene's history, +## so we try both (matches the pattern in batch_handler.gd). +func editor_undo(undo_redo: EditorUndoRedoManager) -> bool: + for ur in _collect_histories(undo_redo): + if ur.undo(): + return true + return false + + +## Mirror of `editor_undo` for redo. +func editor_redo(undo_redo: EditorUndoRedoManager) -> bool: + for ur in _collect_histories(undo_redo): + if ur.redo(): + return true + return false + + +func _collect_histories(undo_redo: EditorUndoRedoManager) -> Array: + var out: Array = [] + if undo_redo == null: + return out + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root != null: + var scene_id := undo_redo.get_object_history_id(scene_root) + var scene_ur := undo_redo.get_history_undo_redo(scene_id) + if scene_ur != null: + out.append(scene_ur) + var global_ur := undo_redo.get_history_undo_redo(EditorUndoRedoManager.GLOBAL_HISTORY) + if global_ur != null and not global_ur in out: + out.append(global_ur) + return out + + +# ----- assertions ----- + +func assert_true(condition: bool, msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if not condition: + _failed = true + _message = msg if msg else "Expected true" + + +func assert_false(condition: bool, msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if condition: + _failed = true + _message = msg if msg else "Expected false" + + +func assert_eq(actual: Variant, expected: Variant, msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if actual != expected: + _failed = true + _message = msg if msg else "Expected %s, got %s" % [str(expected), str(actual)] + + +func assert_ne(actual: Variant, not_expected: Variant, msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if actual == not_expected: + _failed = true + _message = msg if msg else "Expected value != %s" % str(not_expected) + + +func assert_gt(actual: Variant, threshold: Variant, msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if not (actual > threshold): + _failed = true + _message = msg if msg else "Expected %s > %s" % [str(actual), str(threshold)] + + +func assert_has_key(dict: Variant, key: String, msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if not dict is Dictionary: + _failed = true + _message = msg if msg else "Expected Dictionary, got %s" % type_string(typeof(dict)) + return + if not dict.has(key): + _failed = true + _message = msg if msg else "Missing key: %s (keys: %s)" % [key, str(dict.keys())] + + +func assert_contains(haystack: Variant, needle: Variant, msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if haystack is String: + if haystack.find(str(needle)) == -1: + _failed = true + _message = msg if msg else "'%s' not found in '%s'" % [str(needle), haystack] + elif haystack is Array: + if not haystack.has(needle): + _failed = true + _message = msg if msg else "%s not found in array" % str(needle) + else: + _failed = true + _message = msg if msg else "assert_contains requires String or Array" + + +func assert_is_error(result: Dictionary, expected_code: String = "", msg: String = "") -> void: + _assertion_count += 1 + if _failed: + return + if not result.has("error"): + _failed = true + _message = msg if msg else "Expected error response, got: %s" % str(result.keys()) + return + if expected_code and result.error.get("code", "") != expected_code: + _failed = true + _message = msg if msg else "Expected error code %s, got %s" % [expected_code, result.error.get("code", "")] + + +# ----- scene helpers (shared across suites that create/remove Controls) ----- + +## Add a Control under the scene root. Creates a Panel if ctl is null. +## Returns the scene path, or "" when no scene is open — in which case a +## caller-supplied ctl is freed to prevent leaks. +func _add_control(ctl_name: String, ctl: Control = null) -> String: + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root == null: + if ctl != null: + ctl.queue_free() + return "" + if ctl == null: + ctl = Panel.new() + ctl.name = ctl_name + scene_root.add_child(ctl) + ctl.owner = scene_root + return "/" + scene_root.name + "/" + ctl_name + + +func _remove_control(path: String) -> void: + var scene_root := EditorInterface.get_edited_scene_root() + if scene_root == null: + return + var node := McpScenePath.resolve(path, scene_root) + if node != null: + node.get_parent().remove_child(node) + node.queue_free() diff --git a/addons/godot_ai/testing/test_suite.gd.uid b/addons/godot_ai/testing/test_suite.gd.uid new file mode 100644 index 0000000..b75e726 --- /dev/null +++ b/addons/godot_ai/testing/test_suite.gd.uid @@ -0,0 +1 @@ +uid://dlrq2s7jhp71s diff --git a/addons/godot_ai/tool_catalog.gd b/addons/godot_ai/tool_catalog.gd new file mode 100644 index 0000000..d1e8b4a --- /dev/null +++ b/addons/godot_ai/tool_catalog.gd @@ -0,0 +1,110 @@ +@tool +class_name McpToolCatalog +extends RefCounted + +## Mirror of src/godot_ai/tools/domains.py — drives the dock's Tools tab +## so the UI can render checkboxes, tool counts, and tooltips without +## round-tripping to a running server. +## +## DO NOT EDIT by hand. tests/unit/test_tool_domains.py verifies this file +## against actual tool registration and fails CI when they drift; the +## failure message prints the up-to-date catalog body for paste-over. +## +## The four core tools are always registered and cannot be excluded — they +## render as a single grayed-out "Core" row in the UI. Each non-core domain +## now exposes one or two named verbs plus a single rolled-up +## `_manage` tool. + +const CORE_TOOLS := [ + "editor_state", + "node_get_properties", + "scene_get_hierarchy", + "session_activate", +] + +## Non-core tools that live in a NON-excludable domain (only `session` +## today), so they appear in no DOMAINS row yet are always registered. +## Counted alongside CORE_TOOLS so the dock's totals match the real +## server surface. +const ALWAYS_ON_TOOLS := [ + "session_manage", +] + +## Ordered list of user-toggleable domains. Each entry: +## id: matches the name passed to `--exclude-domains` +## label: human-friendly display (same as id for now, kept separate so +## a future renaming doesn't break the setting) +## count: number of NON-CORE tools in this domain +## tools: flat list of tool names registered by this domain (non-core only) +const DOMAINS := [ + {"id": "animation", "label": "animation", "count": 2, "tools": ["animation_create", "animation_manage"]}, + {"id": "api", "label": "api", "count": 1, "tools": ["api_manage"]}, + {"id": "audio", "label": "audio", "count": 1, "tools": ["audio_manage"]}, + {"id": "autoload", "label": "autoload", "count": 1, "tools": ["autoload_manage"]}, + {"id": "batch", "label": "batch", "count": 1, "tools": ["batch_execute"]}, + {"id": "camera", "label": "camera", "count": 1, "tools": ["camera_manage"]}, + {"id": "client", "label": "client", "count": 1, "tools": ["client_manage"]}, + {"id": "custom", "label": "custom", "count": 1, "tools": ["custom_manage"]}, + {"id": "editor", "label": "editor", "count": 4, "tools": ["editor_manage", "editor_reload_plugin", "editor_screenshot", "logs_read"]}, + {"id": "filesystem", "label": "filesystem", "count": 1, "tools": ["filesystem_manage"]}, + {"id": "game", "label": "game", "count": 1, "tools": ["game_manage"]}, + {"id": "input_map", "label": "input_map", "count": 1, "tools": ["input_map_manage"]}, + {"id": "material", "label": "material", "count": 1, "tools": ["material_manage"]}, + {"id": "node", "label": "node", "count": 4, "tools": ["node_create", "node_find", "node_manage", "node_set_property"]}, + {"id": "particle", "label": "particle", "count": 1, "tools": ["particle_manage"]}, + {"id": "project", "label": "project", "count": 2, "tools": ["project_manage", "project_run"]}, + {"id": "resource", "label": "resource", "count": 1, "tools": ["resource_manage"]}, + {"id": "scene", "label": "scene", "count": 3, "tools": ["scene_manage", "scene_open", "scene_save"]}, + {"id": "script", "label": "script", "count": 4, "tools": ["script_attach", "script_create", "script_manage", "script_patch"]}, + {"id": "signal", "label": "signal", "count": 1, "tools": ["signal_manage"]}, + {"id": "testing", "label": "testing", "count": 2, "tools": ["test_manage", "test_run"]}, + {"id": "theme", "label": "theme", "count": 1, "tools": ["theme_manage"]}, + {"id": "tilemap", "label": "tilemap", "count": 1, "tools": ["tilemap_manage"]}, + {"id": "tileset", "label": "tileset", "count": 1, "tools": ["tileset_manage"]}, + {"id": "gridmap", "label": "gridmap", "count": 1, "tools": ["gridmap_manage"]}, + {"id": "csg", "label": "csg", "count": 1, "tools": ["csg_manage"]}, + {"id": "ui", "label": "ui", "count": 1, "tools": ["ui_manage"]}, +] + + +## Whether `id` is a real, excludable domain in this plugin version. Used to +## drop stale names (e.g. a domain removed since the setting was written) so +## they never reach the server's `--exclude-domains`, whose `parse_exclude_list` +## hard-fails on unknown names. +static func is_excludable_domain(id: String) -> bool: + for d in DOMAINS: + if d["id"] == id: + return true + return false + + +## Total tool count when no domains are excluded. Used for the "Enabled: N / M" +## readout in the Tools tab without looping the catalog on every repaint. +static func total_tool_count() -> int: + var n := CORE_TOOLS.size() + ALWAYS_ON_TOOLS.size() + for d in DOMAINS: + n += int(d["count"]) + return n + + +## Tool count remaining after excluding the given set of domain ids. +static func enabled_tool_count(excluded: PackedStringArray) -> int: + var n := CORE_TOOLS.size() + ALWAYS_ON_TOOLS.size() + for d in DOMAINS: + if excluded.find(d["id"]) == -1: + n += int(d["count"]) + return n + + +## Canonical comma-separated string for a set of domain ids — sorted and +## deduplicated so two equivalent settings (entered in different orders) +## hash to the same EditorSetting value. Matches `excluded_domains()` in +## client_configurator.gd. +static func canonical(excluded: PackedStringArray) -> String: + var seen := PackedStringArray() + for e in excluded: + var t := e.strip_edges() + if not t.is_empty() and seen.find(t) == -1: + seen.append(t) + seen.sort() + return ",".join(seen) diff --git a/addons/godot_ai/tool_catalog.gd.uid b/addons/godot_ai/tool_catalog.gd.uid new file mode 100644 index 0000000..c0c179b --- /dev/null +++ b/addons/godot_ai/tool_catalog.gd.uid @@ -0,0 +1 @@ +uid://d1vqyt4uyo378 diff --git a/addons/godot_ai/update_reload_runner.gd b/addons/godot_ai/update_reload_runner.gd new file mode 100644 index 0000000..7761e40 --- /dev/null +++ b/addons/godot_ai/update_reload_runner.gd @@ -0,0 +1,590 @@ +@tool +extends Node + +## EditorSetting key used to defer a self_update telemetry event across the +## disable -> enable boundary. The runner runs while the plugin is disabled, +## so it can't send WebSocket events directly; it writes the outcome here +## and the re-enabled plugin's `_enter_tree` flushes it. See +## `plugin.gd::_flush_pending_self_update_telemetry`. +const PENDING_SELF_UPDATE_TELEMETRY_KEY := "godot_ai/pending_self_update_event" + +## Self-update runner. Owns the install-and-reload sequence from +## `start(zip_path, temp_dir, detached_dock)` onward: extract files into +## `addons/godot_ai/` with rollback bookkeeping, scan the filesystem, +## re-enable the plugin, and clean up the detached dock. +## +## Single-phase install: writes the full `_new_file_paths + +## _existing_file_paths` set before issuing exactly one +## `EditorFileSystem.scan()`. Godot's scan-time reparse pass then sees one +## consistent v(N+1) snapshot, so new files and existing files can resolve +## each other's same-release API changes regardless of parse order. +## +## Not owned here: HTTP download (in `utils/update_manager.gd`), banner UI +## (in `mcp_dock.gd`), or server stop prep (called by +## `plugin.gd::install_downloaded_update` before this runner starts via +## `_lifecycle.prepare_for_update_reload()`). +## +## This node is deliberately tiny and not parented under the EditorPlugin: +## it survives `set_plugin_enabled(false)`, extracts the downloaded release, +## waits for Godot's filesystem scan, then enables the plugin again. The old +## dock is detached before this runner starts, kept alive while deferred +## Callables drain, and freed only after the new plugin instance is loaded. + +const PLUGIN_CFG_PATH := "res://addons/godot_ai/plugin.cfg" +const PRE_DISABLE_DRAIN_FRAMES := 8 +const POST_DISABLE_DRAIN_FRAMES := 2 +const POST_ENABLE_FREE_FRAMES := 8 +const INSTALL_BASE_PATH := "res://" +const ZIP_ADDON_PREFIX := "addons/godot_ai/" +const TEMP_FILE_SUFFIX := ".godot_ai_update_tmp" +const INSTALL_BACKUP_SUFFIX := ".update_backup" + +## Outcome of `_install_zip_paths`. `OK` means all listed files were replaced. +## `FAILED_CLEAN` means a write/rename failed mid-batch but every previously +## written file was rolled back to its vN content (or removed, if the file +## was new in vN+1). `FAILED_MIXED` means rollback itself failed: the addons +## tree contains a mix of vN and vN+1 files. The runner MUST NOT re-enable +## the plugin in the MIXED case — see issue #297 finding #9 for the data-loss +## scenario this guards against. +enum InstallStatus { OK, FAILED_CLEAN, FAILED_MIXED } + +var _zip_path := "" +## Old plugin.cfg version, read from disk in `start()` before the extract +## replaces it. Rides the pending self-update marker. +var _from_version := "" +var _temp_dir := "" +var _detached_dock = null +var _started := false +var _next_step := "" +var _frames_remaining := 0 +var _waiting_for_scan := false +var _scan_next_step := "" +## Watchdog for `_start_filesystem_scan`: if Godot's `filesystem_changed` +## signal never fires (slow disk, NFS, AV holding the just-extracted addon +## files open), the runner used to hang in `_waiting_for_scan = true` +## forever and the dock stayed disabled. After this timeout we disconnect +## the signal and proceed anyway — worst case the new files aren't visible +## on the first frame, but they get picked up on the next scan. See +## audit-v2 finding #9 (issue #353). Untyped to match the codebase's +## defensive pattern for state that survives `fs.scan()` during update. +const SCAN_WATCHDOG_SECS := 30.0 +var _scan_watchdog_timer = null +## Sticky flag set by `_on_scan_watchdog_timeout`. Subsequent +## `_start_filesystem_scan` calls in the same update bypass connect+scan +## so a delayed `filesystem_changed` emission from the timed-out scan +## can't fire on a freshly-armed listener for the next scan and falsely +## settle it before that scan actually completed. See PR #381 review for +## the cross-scan race this guards against. +var _scan_timed_out := false +## Keep Array fields untyped: this runner survives fs.scan() during update, +## and typed Variant storage is part of the hot-reload crash class. +var _new_file_paths = [] +var _existing_file_paths = [] +## Per-file install records accumulated during install so a later failure +## can roll back files already replaced earlier in the same update. +## Each entry is an untyped Dictionary with target_path / backup_path / +## had_original keys. Cleared by `_finalize_install_success` on full success +## and by `_rollback_paths_written` on failure. +var _paths_written = [] +## Set true if `_install_zip_file`'s inner restore-from-backup couldn't +## complete (backup gone, copy failed). The failed file is NOT recorded in +## `_paths_written` because the function bails at that point — without this +## flag, `_rollback_paths_written` would walk only the prior records, all +## restore cleanly, and report FAILED_CLEAN even though the current target +## is missing or stale on disk. Surfaces FAILED_MIXED so the runner refuses +## to re-enable the plugin against a half-installed tree. +var _restore_failed := false +## Test-only opt-out for the scan-watchdog `push_warning` lines. The +## watchdog unit tests in `test_update_reload_runner.gd` invoke +## `_on_scan_watchdog_timeout()` and the post-timeout +## `_start_filesystem_scan` bypass branch directly to pin their behavior +## — but those code paths' `push_warning` calls then appear as yellow +## console noise in every `test_run`, training reviewers to ignore the +## runner's real production warnings. Tests set this true; production +## leaves it false so genuine scan timeouts during a real self-update +## still surface loudly. See issue #413. +var _suppress_scan_warnings := false + + +func start(zip_path: String, temp_dir: String, detached_dock) -> void: + if _started: + return + _started = true + _zip_path = zip_path + _temp_dir = temp_dir + _detached_dock = detached_dock + ## Captured before the extract replaces plugin.cfg: the success marker + ## carries from/to versions so the re-enabled plugin can (a) report a + ## complete self_update telemetry event and (b) scope the post-update + ## client repin to entries whose ONLY drift is the old version pin. Pure + ## file IO on purpose — the runner must not call into plugin scripts + ## during the disable window. + _from_version = _read_plugin_cfg_version() + _wait_frames(PRE_DISABLE_DRAIN_FRAMES, "_disable_old_plugin") + + +## Read `version="X.Y.Z"` from the on-disk plugin.cfg. Returns "" when the +## file or key is missing — consumers treat an empty version as "unknown" +## and degrade (telemetry sends empty fields, the repin gate skips). +static func _read_plugin_cfg_version() -> String: + var file := FileAccess.open(PLUGIN_CFG_PATH, FileAccess.READ) + if file == null: + return "" + var text := file.get_as_text() + file.close() + var re := RegEx.new() + if re.compile("(?m)^version=\"([^\"]+)\"") != OK: + return "" + var found := re.search(text) + return found.get_string(1) if found != null else "" + + +func _process(_delta: float) -> void: + if _frames_remaining <= 0: + set_process(false) + return + + _frames_remaining -= 1 + if _frames_remaining <= 0: + var step := _next_step + _next_step = "" + set_process(false) + call(step) + + +func _wait_frames(frame_count: int, next_step: String) -> void: + _next_step = next_step + _frames_remaining = max(1, frame_count) + set_process(true) + + +func _disable_old_plugin() -> void: + ## Disable before writing or scanning new scripts. This avoids both the + ## Dict/Array field-storage hot-reload crash (#245) and cached handler + ## constructor shape mismatches (#247) for plugin-owned instances. + print("MCP | update runner disabling old plugin") + EditorInterface.set_plugin_enabled(PLUGIN_CFG_PATH, false) + _wait_frames(POST_DISABLE_DRAIN_FRAMES, "_extract_and_scan") + + +func _extract_and_scan() -> void: + if not _read_update_manifest(): + EditorInterface.set_plugin_enabled(PLUGIN_CFG_PATH, true) + _wait_frames(POST_ENABLE_FREE_FRAMES, "_cleanup_and_finish") + return + + var install_paths := [] + install_paths.append_array(_new_file_paths) + install_paths.append_array(_existing_file_paths) + + var status := _install_zip_paths(install_paths) + if status != InstallStatus.OK: + _handle_install_failure(status) + return + + _finalize_install_success() + _cleanup_update_temp() + ## One scan covers both dependency directions: plugin.gd's preloads of + ## new files resolve because those files are already present, and new + ## files' references to new members or static-ness changes on existing + ## load-surface scripts resolve because those existing files are also + ## already at v(N+1). The goal is a consistent snapshot before scan, not + ## a tree-atomic install; per-file writes still use `.tmp` + rename and + ## rollback on failure. + _start_filesystem_scan("_enable_new_plugin") + + +func _start_filesystem_scan(next_step: String = "_enable_new_plugin") -> void: + var fs := EditorInterface.get_resource_filesystem() + var deferred_step := next_step if not next_step.is_empty() else "_enable_new_plugin" + if fs == null: + call_deferred(deferred_step) + return + + ## Bypass: a previous scan in this update already watchdog'd, so the + ## editor's filesystem is unresponsive. Re-arming a `filesystem_changed` + ## listener now would race with a delayed emission from the timed-out + ## scan: that single emission would fire whichever listener is currently + ## connected to the shared signal, falsely settling this scan before it + ## actually completed. Skip the wait; Godot's normal background scan + ## catches up after the plugin re-enables. See PR #381 review. + if _scan_timed_out: + if not _suppress_scan_warnings: + push_warning( + "MCP | skipping filesystem_changed wait after previous timeout (next_step=%s)" + % deferred_step + ) + call_deferred(deferred_step) + return + + _waiting_for_scan = true + _scan_next_step = deferred_step + if not fs.filesystem_changed.is_connected(_on_filesystem_changed): + fs.filesystem_changed.connect(_on_filesystem_changed, CONNECT_ONE_SHOT) + _arm_scan_watchdog() + fs.scan() + + +func _arm_scan_watchdog() -> void: + if _scan_watchdog_timer == null: + _scan_watchdog_timer = Timer.new() + _scan_watchdog_timer.one_shot = true + _scan_watchdog_timer.timeout.connect(_on_scan_watchdog_timeout) + add_child(_scan_watchdog_timer) + _scan_watchdog_timer.start(SCAN_WATCHDOG_SECS) + + +func _stop_scan_watchdog() -> void: + if _scan_watchdog_timer != null: + _scan_watchdog_timer.stop() + + +func _on_scan_watchdog_timeout() -> void: + ## Signal didn't fire within SCAN_WATCHDOG_SECS — most likely the + ## filesystem scan is blocked behind a slow disk / NFS / AV scanner + ## still reading the just-extracted addon files. + ## Set the sticky `_scan_timed_out` flag so any subsequent + ## `_start_filesystem_scan` in this update skips its connect+scan + ## (otherwise a delayed emission from this scan would falsely settle + ## the next scan's listener — see PR #381 review). + ## Disconnect the current listener too, so this scan's listener can't + ## double-call `_finish_scan_wait` if the signal arrives quickly after + ## the timeout fires. `_finish_scan_wait` is idempotent on + ## `_waiting_for_scan == false`. + if not _waiting_for_scan: + return + if not _suppress_scan_warnings: + push_warning( + "MCP | filesystem_changed didn't fire within %ds; proceeding without scan confirmation" + % int(SCAN_WATCHDOG_SECS) + ) + _scan_timed_out = true + var fs := EditorInterface.get_resource_filesystem() + if fs != null and fs.filesystem_changed.is_connected(_on_filesystem_changed): + fs.filesystem_changed.disconnect(_on_filesystem_changed) + _finish_scan_wait() + + +func _read_update_manifest() -> bool: + var zip_path := ProjectSettings.globalize_path(_zip_path) + var install_base := ProjectSettings.globalize_path(INSTALL_BASE_PATH) + + var reader := ZIPReader.new() + if reader.open(zip_path) != OK: + print("MCP | update extract failed: could not open %s" % zip_path) + return false + + _new_file_paths.clear() + _existing_file_paths.clear() + var has_plugin_cfg := false + var has_plugin_script := false + var files := reader.get_files() + for file_path in files: + if not file_path.begins_with(ZIP_ADDON_PREFIX): + continue + var rel_path := file_path.trim_prefix(ZIP_ADDON_PREFIX) + ## Many zip builders (`zip -r` without `-D`, AssetLib uploads, hand- + ## built archives) emit zero-byte directory entries like + ## `addons/godot_ai/`. Skip those before the safety check; the + ## empty-segment guard in `_is_safe_zip_addon_file` would otherwise + ## flag the bare prefix as unsafe and abort the extract. Current + ## release.yml passes `-D` to strip them, but installed runners must + ## still tolerate older or manually built zips. + if rel_path.is_empty() or file_path.ends_with("/"): + continue + if not _is_safe_zip_addon_file(file_path): + print("MCP | update extract failed: unsafe zip path %s" % file_path) + reader.close() + return false + if rel_path == "plugin.cfg": + has_plugin_cfg = true + elif rel_path == "plugin.gd": + has_plugin_script = true + var target_path := install_base.path_join(file_path) + if FileAccess.file_exists(target_path): + _existing_file_paths.append(file_path) + else: + _new_file_paths.append(file_path) + reader.close() + if not has_plugin_cfg: + print("MCP | update extract failed: zip is missing plugin.cfg") + return false + if not has_plugin_script: + print("MCP | update extract failed: zip is missing plugin.gd") + return false + return true + + +func _handle_install_failure(status: int) -> void: + _record_pending_self_update({ + "status": "failed_mixed" if status == InstallStatus.FAILED_MIXED else "failed_clean", + }) + if status == InstallStatus.FAILED_MIXED: + ## Half-installed addon tree on disk: re-enabling the plugin would + ## load a mix of vN and vN+1 files. Print a load-bearing diagnostic + ## and bail without re-enabling — user must restore manually. See + ## issue #297 finding #9 for the data-loss scenario. + push_error( + "MCP | self-update failed mid-install AND rollback could not" + + " restore the previous addons/godot_ai/ contents. The plugin" + + " is left disabled. Inspect addons/godot_ai/ for" + + " *.update_backup / *.godot_ai_update_tmp files and restore" + + " manually before re-enabling the plugin." + ) + print( + "MCP | self-update aborted: addons/godot_ai/ is in a mixed state;" + + " plugin left disabled (manual intervention required)." + ) + _wait_frames(POST_ENABLE_FREE_FRAMES, "_cleanup_and_finish") + return + ## FAILED_CLEAN: rollback restored every previously-written file. Safe + ## to re-enable the previous plugin version. + print("MCP | self-update rolled back; re-enabling previous plugin version") + EditorInterface.set_plugin_enabled(PLUGIN_CFG_PATH, true) + _wait_frames(POST_ENABLE_FREE_FRAMES, "_cleanup_and_finish") + + +func _is_safe_zip_addon_file(file_path: String) -> bool: + if file_path.is_absolute_path() or file_path.contains("\\"): + return false + if not file_path.begins_with(ZIP_ADDON_PREFIX): + return false + var rel_path := file_path.trim_prefix(ZIP_ADDON_PREFIX) + if rel_path.is_empty() or rel_path.ends_with("/"): + return false + ## Reserved install-machinery suffixes (#713): an entry named like the + ## runner's own staging/backup files would collide with the temp file + ## `_install_zip_file` writes, or overwrite / later be deleted with the + ## rollback snapshots `_finalize_install_success` cleans up — corrupting + ## the very rollback set protecting this install. + if rel_path.ends_with(TEMP_FILE_SUFFIX) or rel_path.ends_with(INSTALL_BACKUP_SUFFIX): + return false + for segment in rel_path.split("/", true): + if segment.is_empty() or segment == "." or segment == "..": + return false + return true + + +func _install_zip_paths(paths: Array) -> int: + if paths.is_empty(): + return InstallStatus.OK + + var zip_path := ProjectSettings.globalize_path(_zip_path) + var reader := ZIPReader.new() + if reader.open(zip_path) != OK: + print("MCP | update extract failed: could not reopen %s" % zip_path) + ## Nothing else can be written, but earlier files from this update + ## may have landed on disk; roll those back too. + return _rollback_paths_written() + + var install_base := ProjectSettings.globalize_path(INSTALL_BASE_PATH) + for file_path in paths: + var record := _install_zip_file(reader, String(file_path), install_base) + if record.is_empty(): + reader.close() + return _rollback_paths_written() + _paths_written.append(record) + reader.close() + return InstallStatus.OK + + +func _install_zip_file( + reader: ZIPReader, file_path: String, install_base: String +) -> Dictionary: + var target_path := install_base.path_join(file_path) + var dir := target_path.get_base_dir() + if DirAccess.make_dir_recursive_absolute(dir) != OK: + print("MCP | update extract failed: could not create %s" % dir) + return {} + + var temp_path := target_path + TEMP_FILE_SUFFIX + DirAccess.remove_absolute(temp_path) + var content := reader.read_file(file_path) + var f := FileAccess.open(temp_path, FileAccess.WRITE) + if f == null: + print("MCP | update extract failed: could not write %s (error %d)" % [ + temp_path, + FileAccess.get_open_error(), + ]) + return {} + ## `store_buffer` reports a short write only via its return value — it + ## does NOT set the last-error state `get_error()` reads — and the write + ## is stdio-buffered, so disk-full surfaces at flush/close, not here. + ## Capture the return and re-verify the on-disk size after close() so a + ## disk-full "succeeds" write can't rename a truncated file over the + ## live target (#687). + var stored := f.store_buffer(content) + f.flush() + var write_error := f.get_error() + f.close() + ## get_length() on a read handle, not get_file_as_bytes().size() — the + ## latter re-reads the whole file into memory per extracted entry just + ## to learn its length. + var written_size := -1 + var verify := FileAccess.open(temp_path, FileAccess.READ) + if verify != null: + written_size = verify.get_length() + verify.close() + if not stored or write_error != OK or written_size != content.size(): + print("MCP | update extract failed: write validation failed (error %d) for %s (stored=%s size=%d expected=%d)" % [ + write_error, + temp_path, + stored, + written_size, + content.size(), + ]) + DirAccess.remove_absolute(temp_path) + return {} + + ## Back up the original via COPY (not rename) so the source of truth + ## stays in place if a later step fails. Rolled back via + ## `_rollback_paths_written` if a subsequent file in this batch — or a + ## later batch — can't be installed. + var had_original := FileAccess.file_exists(target_path) + var backup_path := target_path + INSTALL_BACKUP_SUFFIX + if had_original: + DirAccess.remove_absolute(backup_path) + if DirAccess.copy_absolute(target_path, backup_path) != OK: + DirAccess.remove_absolute(temp_path) + print("MCP | update extract failed: could not back up %s" % target_path) + return {} + + if DirAccess.rename_absolute(temp_path, target_path) != OK: + ## POSIX and APFS replace atomically. Some filesystems reject + ## rename-over-existing; keep a fallback so the update can still + ## proceed, but the common path never exposes a truncated target. + DirAccess.remove_absolute(target_path) + if DirAccess.rename_absolute(temp_path, target_path) != OK: + DirAccess.remove_absolute(temp_path) + ## Target was removed above; restore from the COPY backup so the + ## addons dir is left in its vN state before we surface failure. + ## Only delete the backup if the restore copy actually succeeded + ## — if it didn't, target_path is missing, and `_restore_failed` + ## tells `_rollback_paths_written` to surface FAILED_MIXED so the + ## runner refuses to re-enable the plugin. Leaving the backup on + ## disk also gives the user a manual recovery path. Without this + ## guard the failed file isn't tracked anywhere (we return `{}`, + ## not appended to `_paths_written`) and the caller would + ## erroneously see FAILED_CLEAN. + if had_original: + if ( + FileAccess.file_exists(backup_path) + and DirAccess.copy_absolute(backup_path, target_path) == OK + ): + DirAccess.remove_absolute(backup_path) + else: + _restore_failed = true + print("MCP | update extract failed: could not replace %s" % target_path) + return {} + return { + "target_path": target_path, + "backup_path": backup_path, + "had_original": had_original, + } + + +## Restore (or remove) every file already touched in this update. Safe to +## call after a partial install — entries are processed in reverse so a +## given target is restored before the next earlier write of the same path +## could resurrect a stale value. Returns FAILED_CLEAN if every entry was +## restored AND no in-flight `_install_zip_file` left a target stranded +## (`_restore_failed`); FAILED_MIXED otherwise. The caller MUST NOT +## re-enable the plugin in the MIXED case. +func _rollback_paths_written() -> int: + var any_failed := false + var i := _paths_written.size() - 1 + while i >= 0: + var record = _paths_written[i] + var target := String(record.get("target_path", "")) + var backup := String(record.get("backup_path", "")) + var had_original := bool(record.get("had_original", false)) + if had_original: + if not FileAccess.file_exists(backup): + print("MCP | update rollback failed: backup missing for %s" % target) + any_failed = true + else: + DirAccess.remove_absolute(target) + if DirAccess.copy_absolute(backup, target) != OK: + print("MCP | update rollback failed: could not restore %s" % target) + any_failed = true + else: + DirAccess.remove_absolute(backup) + else: + if FileAccess.file_exists(target): + if DirAccess.remove_absolute(target) != OK: + print( + "MCP | update rollback failed: could not delete %s" % target + ) + any_failed = true + i -= 1 + _paths_written.clear() + if any_failed or _restore_failed: + return InstallStatus.FAILED_MIXED + return InstallStatus.FAILED_CLEAN + + +## Discard accumulated backups after the combined install succeeds. Backups +## are best-effort: a failure here doesn't compromise the new install, just +## leaves stray *.update_backup files for the user to clean up. +func _finalize_install_success() -> void: + for record in _paths_written: + if record.get("had_original", false): + DirAccess.remove_absolute(String(record.get("backup_path", ""))) + _paths_written.clear() + ## plugin.cfg on disk is the NEW version by now — read it back rather + ## than trusting any in-memory value, so the marker describes what was + ## actually installed. + _record_pending_self_update({ + "status": "success", + "from_version": _from_version, + "to_version": _read_plugin_cfg_version(), + }) + + +## Persist a self_update event description so the re-enabled plugin can +## emit it once its WebSocket is connected. Survives the disable -> enable +## window where the runner cannot send anything itself. +func _record_pending_self_update(data: Dictionary) -> void: + var settings := EditorInterface.get_editor_settings() + if settings == null: + return + settings.set_setting(PENDING_SELF_UPDATE_TELEMETRY_KEY, JSON.stringify(data)) + + +func _cleanup_update_temp() -> void: + DirAccess.remove_absolute(ProjectSettings.globalize_path(_zip_path)) + DirAccess.remove_absolute(ProjectSettings.globalize_path(_temp_dir)) + + +func _on_filesystem_changed() -> void: + _finish_scan_wait() + + +func _finish_scan_wait() -> void: + if not _waiting_for_scan: + return + _waiting_for_scan = false + _stop_scan_watchdog() + var next_step := _scan_next_step + _scan_next_step = "" + set_process(false) + if next_step.is_empty(): + next_step = "_enable_new_plugin" + call_deferred(next_step) + + +func _enable_new_plugin() -> void: + print("MCP | update runner enabling new plugin") + EditorInterface.set_plugin_enabled(PLUGIN_CFG_PATH, true) + _wait_frames(POST_ENABLE_FREE_FRAMES, "_cleanup_and_finish") + + +func _cleanup_and_finish() -> void: + _cleanup_detached_dock() + queue_free() + + +func _cleanup_detached_dock() -> void: + if _detached_dock != null and is_instance_valid(_detached_dock): + _detached_dock.queue_free() + _detached_dock = null diff --git a/addons/godot_ai/update_reload_runner.gd.uid b/addons/godot_ai/update_reload_runner.gd.uid new file mode 100644 index 0000000..9cc6615 --- /dev/null +++ b/addons/godot_ai/update_reload_runner.gd.uid @@ -0,0 +1 @@ +uid://cu6c75n3x2pik diff --git a/addons/godot_ai/utils/allow_hosts.gd b/addons/godot_ai/utils/allow_hosts.gd new file mode 100644 index 0000000..a34c964 --- /dev/null +++ b/addons/godot_ai/utils/allow_hosts.gd @@ -0,0 +1,170 @@ +@tool +class_name McpAllowHosts +extends RefCounted + +## Client-side helpers for the `--allow-host` LAN opt-in (#507, server core +## in #421). Pure static functions only — no EditorSettings, no sockets — +## so the settings-value → launch-args plumbing and the manual-command LAN +## URL builder are deterministically testable without a live editor. +## +## Accepted syntax mirrors the server's `parse_allow_hosts` +## (src/godot_ai/transport/origin_guard.py): each token is a bare IP +## (IPv4 or IPv6) or a CIDR, comma-separated. Host bits set on a CIDR are +## tolerated server-side (`strict=False`), so we only validate the IP part +## and the prefix length here — anything else fails loudly at server +## startup, which the dock-side validation exists to pre-empt. + + +## Canonicalize a comma-separated allow-host value: whitespace-stripped, +## deduplicated, sorted. Returns "" for a value with no usable tokens so +## callers can skip appending `--allow-host` entirely (keeps spawns +## compatible with pre-#421 servers — same contract as +## `ClientConfigurator.excluded_domains()`). +static func normalize(raw: String) -> String: + var parts := PackedStringArray() + for p in raw.split(","): + var t := p.strip_edges() + if not t.is_empty() and parts.find(t) == -1: + parts.append(t) + parts.sort() + return ",".join(parts) + + +## Whether a single token is a bare IP or a CIDR the server will accept. +static func token_is_valid(token: String) -> bool: + var t := token.strip_edges() + if t.is_empty(): + return false + var ip := t + var prefix := 0 + ## Track slash presence separately from the prefix value: reusing -1 as + ## the "no slash" sentinel let an explicit negative prefix like + ## "10.0.0.0/-1" validate (is_valid_int accepts "-1"). CodeRabbit review. + var has_prefix := false + var slash := t.find("/") + if slash != -1: + ip = t.substr(0, slash) + var prefix_text := t.substr(slash + 1) + ## Explicit signs are rejected by the server's parse_allow_hosts + ## (ipaddress refuses "10.0.0.0/+8"), but is_valid_int accepts + ## them — keep the mirror honest. + if prefix_text.is_empty() or prefix_text.begins_with("+") or prefix_text.begins_with("-"): + return false + if not prefix_text.is_valid_int(): + return false + prefix = int(prefix_text) + has_prefix = true + if not ip.is_valid_ip_address(): + return false + var max_prefix := 128 if ip.contains(":") else 32 + return not has_prefix or (prefix >= 0 and prefix <= max_prefix) + + +## Every token in `raw` that fails `token_is_valid` — the dock surfaces +## these inline so a typo is caught before it aborts the server spawn. +static func invalid_tokens(raw: String) -> PackedStringArray: + var bad := PackedStringArray() + for p in raw.split(","): + var t := p.strip_edges() + if t.is_empty(): + continue + if not token_is_valid(t) and bad.find(t) == -1: + bad.append(t) + return bad + + +## True when the allowlist names at least one non-loopback range — i.e. +## the server is actually reachable off this machine and the manual +## command should surface a LAN URL. +static func is_lan_allowlist_active(value: String) -> bool: + for p in value.split(","): + var t := p.strip_edges() + if t.is_empty(): + continue + var ip := t.substr(0, t.find("/")) if t.contains("/") else t + if not _is_loopback(ip): + return true + return false + + +## Choose the LAN address to show in the manual command from the +## machine's local addresses (caller passes `IP.get_local_addresses()` +## so this stays pure). Loopback and link-local addresses are dropped; +## the first private-range IPv4 wins, then any remaining IPv4, then +## anything left (IPv6). Returns `{"address": String, "ambiguous": bool}` +## — `ambiguous` flags multiple viable candidates so the note can tell +## the user to pick the interface on their trusted network. +static func pick_lan_address(addresses: PackedStringArray) -> Dictionary: + var candidates := PackedStringArray() + for a in addresses: + var addr := String(a).strip_edges() + if addr.is_empty() or _is_loopback(addr) or _is_link_local(addr): + continue + candidates.append(addr) + if candidates.is_empty(): + return {"address": "", "ambiguous": false} + var chosen := "" + for addr in candidates: + if _is_private_ipv4(addr): + chosen = addr + break + if chosen.is_empty(): + for addr in candidates: + if addr.contains("."): + chosen = addr + break + if chosen.is_empty(): + chosen = candidates[0] + return {"address": chosen, "ambiguous": candidates.size() > 1} + + +## Informational LAN-URL note appended to the manual command when the +## allowlist is active (#507). Never changes what gets WRITTEN to client +## configs — loopback stays the write target; this is copy-paste help for +## pointing a remote agent at the right address. +static func lan_url_note(allow_hosts_value: String, addresses: PackedStringArray, http_port: int) -> String: + if not is_lan_allowlist_active(allow_hosts_value): + return "" + var pick := pick_lan_address(addresses) + var addr := String(pick.get("address", "")) + if addr.is_empty(): + return ( + "LAN access is enabled (--allow-host %s), but no LAN address was detected on this machine." + % allow_hosts_value + ) + var host := "[%s]" % addr if addr.contains(":") else addr + var note := ( + "LAN access is enabled (--allow-host %s). Remote agents on the allowed network can use: http://%s:%d/mcp" + % [allow_hosts_value, host, http_port] + ) + if bool(pick.get("ambiguous", false)): + note += "\n(multiple network interfaces detected — pick the address on the network you allowed)" + return note + + +static func _is_loopback(addr: String) -> bool: + var a := addr.to_lower() + return a.begins_with("127.") or a == "::1" or a == "localhost" + + +static func _is_link_local(addr: String) -> bool: + var a := addr.to_lower() + if a.begins_with("169.254."): + return true + ## IPv6 link-local is fe80::/10 — the whole fe80-febf first hextet, not + ## just literal "fe80" (Copilot review on #507's PR: fea0::... etc. must + ## also be excluded from LAN-URL candidates). + if a.length() >= 4 and a.begins_with("fe") and a[2] in "89ab": + return true + return false + + +static func _is_private_ipv4(addr: String) -> bool: + if not addr.contains("."): + return false + if addr.begins_with("10.") or addr.begins_with("192.168."): + return true + if addr.begins_with("172."): + var second := int(addr.get_slice(".", 1)) + return second >= 16 and second <= 31 + return false diff --git a/addons/godot_ai/utils/allow_hosts.gd.uid b/addons/godot_ai/utils/allow_hosts.gd.uid new file mode 100644 index 0000000..02fecd1 --- /dev/null +++ b/addons/godot_ai/utils/allow_hosts.gd.uid @@ -0,0 +1 @@ +uid://b7qk3vw2nxr4d diff --git a/addons/godot_ai/utils/class_introspection.gd b/addons/godot_ai/utils/class_introspection.gd new file mode 100644 index 0000000..3076740 --- /dev/null +++ b/addons/godot_ai/utils/class_introspection.gd @@ -0,0 +1,259 @@ +@tool +extends RefCounted + +## Builds stable, JSON-safe metadata for any class registered in ClassDB. + +const VariantSerializer := preload("res://addons/godot_ai/utils/variant_serializer.gd") + +## Sections returned when the caller does not name any. Deliberately narrow: +## a bare `get_class` is almost always "what properties does X have", and the +## full five-section dump for a large class (e.g. Node, Control) costs an agent +## thousands of tokens it rarely wanted. Callers opt into the rest by name, or +## request the lot with the "all" keyword (see `_sections`). +const DEFAULT_SECTIONS: Array[String] = ["properties"] +## The full documentation-shaped section set (excludes the heavier, separately +## gated "inheritors"). Expanded from the "all" keyword. +const ALL_SECTIONS: Array[String] = ["properties", "methods", "signals", "enums", "constants"] +const KNOWN_SECTIONS: Array[String] = ["properties", "methods", "signals", "enums", "constants", "inheritors"] +## Tokens a caller may legitimately pass in `sections` — the known sections plus +## the "all" meta-keyword. Used for error suggestions so a typo like "al" can +## resolve to "all"; "all" is NOT a section (it expands in `_sections`), so it +## stays out of KNOWN_SECTIONS which gates validity. +const SUGGESTABLE_SECTION_TOKENS: Array[String] = [ + "properties", "methods", "signals", "enums", "constants", "inheritors", "all" +] +const MAX_DEFAULT_ITEMS := 100 + + +static func build(type_name: String, options: Dictionary = {}) -> Dictionary: + var sections := _sections(options.get("sections", DEFAULT_SECTIONS)) + var include_inherited := bool(options.get("include_inherited", false)) + var include_inheritors := bool(options.get("include_inheritors", false)) + var offset := max(0, int(options.get("offset", 0))) + var limit := int(options.get("limit", MAX_DEFAULT_ITEMS)) + if limit < 0: + limit = MAX_DEFAULT_ITEMS + var can_instantiate := ClassDB.can_instantiate(type_name) + + var data := { + "class_name": type_name, + "engine_version": Engine.get_version_info().get("string", ""), + "parent_class": str(ClassDB.get_parent_class(type_name)), + "inheritance_chain": _inheritance_chain(type_name), + "can_instantiate": can_instantiate, + "is_singleton": Engine.has_singleton(type_name), + "include_inherited": include_inherited, + "offset": offset, + "limit": limit, + } + if include_inheritors or sections.has("inheritors"): + _add_paged(data, "inheritor", "inheritors", _inheritors(type_name, false), offset, limit) + _add_paged( + data, + "concrete_inheritor", + "concrete_inheritors", + _inheritors(type_name, true), + offset, + limit + ) + if sections.has("properties"): + _add_paged(data, "property", "properties", _properties(type_name, include_inherited), offset, limit) + if sections.has("methods"): + _add_paged(data, "method", "methods", _methods(type_name, include_inherited), offset, limit) + if sections.has("signals"): + _add_paged(data, "signal", "signals", _signals(type_name, include_inherited), offset, limit) + if sections.has("enums"): + _add_paged(data, "enum", "enums", _enums(type_name, include_inherited), offset, limit) + if sections.has("constants"): + _add_paged( + data, + "constant", + "constants", + _unscoped_constants(type_name, include_inherited), + offset, + limit + ) + return data + + +static func validate_sections(raw_sections: Variant) -> Dictionary: + var sections := _sections(raw_sections) + var invalid: Array[String] = [] + for section in sections: + if not KNOWN_SECTIONS.has(section): + invalid.append(section) + return {"sections": sections, "invalid": invalid} + + +static func _inheritance_chain(type_name: String) -> Array[String]: + var chain: Array[String] = [] + var current := type_name + while not current.is_empty(): + chain.append(current) + current = str(ClassDB.get_parent_class(current)) + return chain + + +static func _sections(raw_sections: Variant) -> Array[String]: + var result: Array[String] = [] + var values: Array = [] + if raw_sections is String: + values = raw_sections.split(",", false) + elif raw_sections is Array: + values = raw_sections + else: + values = DEFAULT_SECTIONS + for raw_section in values: + var section := str(raw_section).strip_edges().to_lower() + if section == "all": + for expanded in ALL_SECTIONS: + if not result.has(expanded): + result.append(expanded) + continue + if not section.is_empty() and not result.has(section): + result.append(section) + if result.is_empty(): + result.assign(DEFAULT_SECTIONS) + return result + + +static func _add_paged( + data: Dictionary, + singular: String, + key: String, + items: Array, + offset: int, + limit: int +) -> void: + var end := items.size() if limit == 0 else min(items.size(), offset + limit) + var page: Array = [] + if offset < items.size(): + page = items.slice(offset, end) + data[key] = page + data["%s_count" % singular] = items.size() + data["%s_returned_count" % singular] = page.size() + + +static func _inheritors(type_name: String, concrete_only: bool) -> Array[String]: + var result: Array[String] = [] + for inheritor in ClassDB.get_inheriters_from_class(type_name): + var inheritor_name := str(inheritor) + if concrete_only and not ClassDB.can_instantiate(inheritor_name): + continue + result.append(inheritor_name) + result.sort() + return result + + +static func _properties(type_name: String, include_inherited: bool) -> Array[Dictionary]: + var result: Array[Dictionary] = [] + for raw_prop in ClassDB.class_get_property_list(type_name, not include_inherited): + var prop: Dictionary = raw_prop + var usage := int(prop.get("usage", 0)) + if not (usage & PROPERTY_USAGE_EDITOR): + continue + var prop_name := str(prop.get("name", "")) + result.append({ + "name": prop_name, + "type": type_string(int(prop.get("type", TYPE_NIL))), + "class_name": str(prop.get("class_name", "")), + "hint": int(prop.get("hint", PROPERTY_HINT_NONE)), + "hint_string": str(prop.get("hint_string", "")), + "usage": usage, + "default": VariantSerializer.serialize( + ClassDB.class_get_property_default_value(type_name, prop_name) + ), + }) + result.sort_custom(func(a, b): return a.name < b.name) + return result + + +static func _methods(type_name: String, include_inherited: bool) -> Array[Dictionary]: + var result: Array[Dictionary] = [] + for raw_method in ClassDB.class_get_method_list(type_name, not include_inherited): + var method: Dictionary = raw_method + var args: Array[Dictionary] = [] + for raw_arg in method.get("args", []): + args.append(_argument_info(raw_arg)) + var defaults: Array = [] + for value in method.get("default_args", []): + defaults.append(VariantSerializer.serialize(value)) + result.append({ + "name": str(method.get("name", "")), + "arguments": args, + "default_arguments": defaults, + "return": _argument_info(method.get("return", {})), + "flags": int(method.get("flags", 0)), + }) + result.sort_custom(func(a, b): return a.name < b.name) + return result + + +static func _signals(type_name: String, include_inherited: bool) -> Array[Dictionary]: + var result: Array[Dictionary] = [] + for raw_signal in ClassDB.class_get_signal_list(type_name, not include_inherited): + var signal_info: Dictionary = raw_signal + var args: Array[Dictionary] = [] + for raw_arg in signal_info.get("args", []): + args.append(_argument_info(raw_arg)) + var defaults: Array = [] + for value in signal_info.get("default_args", []): + defaults.append(VariantSerializer.serialize(value)) + result.append({ + "name": str(signal_info.get("name", "")), + "arguments": args, + "default_arguments": defaults, + "flags": int(signal_info.get("flags", 0)), + }) + result.sort_custom(func(a, b): return a.name < b.name) + return result + + +static func _argument_info(raw_info: Variant) -> Dictionary: + var info: Dictionary = raw_info if raw_info is Dictionary else {} + return { + "name": str(info.get("name", "")), + "type": type_string(int(info.get("type", TYPE_NIL))), + "class_name": str(info.get("class_name", "")), + "hint": int(info.get("hint", PROPERTY_HINT_NONE)), + "hint_string": str(info.get("hint_string", "")), + "usage": int(info.get("usage", 0)), + } + + +static func _enums(type_name: String, include_inherited: bool) -> Array[Dictionary]: + var result: Array[Dictionary] = [] + var enum_names: Array[String] = [] + for enum_name in ClassDB.class_get_enum_list(type_name, not include_inherited): + enum_names.append(str(enum_name)) + enum_names.sort() + for enum_name in enum_names: + var values: Array[Dictionary] = [] + for constant_name in ClassDB.class_get_enum_constants(type_name, enum_name, not include_inherited): + values.append({ + "name": str(constant_name), + "value": ClassDB.class_get_integer_constant(type_name, constant_name), + }) + values.sort_custom(func(a, b): return a.name < b.name) + result.append({ + "name": enum_name, + "is_bitfield": ClassDB.is_class_enum_bitfield(type_name, enum_name, not include_inherited), + "values": values, + }) + return result + + +static func _unscoped_constants(type_name: String, include_inherited: bool) -> Array[Dictionary]: + var result: Array[Dictionary] = [] + for constant_name in ClassDB.class_get_integer_constant_list(type_name, not include_inherited): + var enum_name := str( + ClassDB.class_get_integer_constant_enum(type_name, constant_name, not include_inherited) + ) + if not enum_name.is_empty(): + continue + result.append({ + "name": str(constant_name), + "value": ClassDB.class_get_integer_constant(type_name, constant_name), + }) + result.sort_custom(func(a, b): return a.name < b.name) + return result diff --git a/addons/godot_ai/utils/class_introspection.gd.uid b/addons/godot_ai/utils/class_introspection.gd.uid new file mode 100644 index 0000000..3eda5ca --- /dev/null +++ b/addons/godot_ai/utils/class_introspection.gd.uid @@ -0,0 +1 @@ +uid://caedbsmsl6fk4 diff --git a/addons/godot_ai/utils/diagnostics_capture.gd b/addons/godot_ai/utils/diagnostics_capture.gd new file mode 100644 index 0000000..22441ad --- /dev/null +++ b/addons/godot_ai/utils/diagnostics_capture.gd @@ -0,0 +1,66 @@ +@tool +class_name McpDiagnosticsCapture +extends RefCounted + +## Small helper for scoped validation-log capture windows. Callers snapshot a +## private log cursor, perform a deliberate validation action, then only report +## new diagnostics whose original source location is the target file. + + +static func capture_this_file(log_buffer: McpEditorLogBuffer, target_path: String, action: Callable) -> Dictionary: + var cursor := 0 + if log_buffer != null: + cursor = log_buffer.appended_total() + + var action_result = action.call() + var diagnostics: Array[Dictionary] = [] + var truncated := false + + if log_buffer != null: + var captured: Dictionary = log_buffer.get_since(cursor) + truncated = captured.get("truncated", false) + diagnostics = _diagnostics_for_target(captured.get("entries", []), target_path) + + return { + "action": action_result if action_result is Dictionary else {}, + "diagnostics": diagnostics, + "diagnostics_detail": "log_capture" if not diagnostics.is_empty() else "none", + "diagnostics_scope": "this_file", + "diagnostics_status": "partial" if truncated else "checked", + } + + +static func _diagnostics_for_target(entries: Array, target_path: String) -> Array[Dictionary]: + var out: Array[Dictionary] = [] + for raw_entry in entries: + if not raw_entry is Dictionary: + continue + var entry: Dictionary = raw_entry + if not _entry_matches_target(entry, target_path): + continue + out.append(_normalize_entry(entry, target_path)) + return out + + +static func _entry_matches_target(entry: Dictionary, target_path: String) -> bool: + var source := _source_location(entry) + return str(source.get("path", "")) == target_path + + +static func _normalize_entry(entry: Dictionary, target_path: String) -> Dictionary: + var normalized := entry.duplicate(true) + var source := _source_location(entry) + normalized["path"] = str(source.get("path", target_path)) + normalized["line"] = int(source.get("line", normalized.get("line", 0))) + normalized["function"] = str(source.get("function", normalized.get("function", ""))) + if normalized.has("details") and normalized.details is Dictionary: + normalized["details"] = normalized.details.duplicate(true) + return normalized + + +static func _source_location(entry: Dictionary) -> Dictionary: + if entry.get("details") is Dictionary: + var details: Dictionary = entry.details + if details.get("source") is Dictionary: + return details.source + return {} diff --git a/addons/godot_ai/utils/diagnostics_capture.gd.uid b/addons/godot_ai/utils/diagnostics_capture.gd.uid new file mode 100644 index 0000000..95973c9 --- /dev/null +++ b/addons/godot_ai/utils/diagnostics_capture.gd.uid @@ -0,0 +1 @@ +uid://b3npxxpuobbc2 diff --git a/addons/godot_ai/utils/editor_log_buffer.gd b/addons/godot_ai/utils/editor_log_buffer.gd new file mode 100644 index 0000000..0ea44e7 --- /dev/null +++ b/addons/godot_ai/utils/editor_log_buffer.gd @@ -0,0 +1,127 @@ +@tool +class_name McpEditorLogBuffer +extends McpStructuredLogRing + +## Ring buffer for editor-process script errors and warnings (parse errors, +## @tool runtime errors, EditorPlugin errors, push_error/push_warning) captured +## by editor_logger.gd's Logger subclass. +## +## Smaller cap than McpGameLogBuffer (500 vs 2000) — the editor only emits errors, +## not the full println firehose a game can produce. No run_id rotation: editor +## errors persist across project_run cycles (they're about *editing* state, not +## about the playing game). +## +## Mutex-protected because Logger virtuals can fire from any thread (e.g. +## async script-loader threads emitting parse errors), and the buffer is +## read on the main thread by EditorHandler.get_logs. Each public method +## wraps the base ring's lockless helpers in `_mutex.lock()/unlock()` — +## the base stays lockless so McpGameLogBuffer's hot path doesn't pay an +## unused mutex cost. +## +## Entry shape: {source: "editor", level: "info"|"warn"|"error", +## text, path, line, function} — `path/line/function` may be empty/zero +## when the source location wasn't recoverable (e.g. printerr from a +## thread without a script context). + +const MAX_LINES := 500 + +var _mutex := Mutex.new() +var _error_appended_total := 0 +var _warn_appended_total := 0 + + +func _init() -> void: + super._init(MAX_LINES) + + +func append(level: String, text: String, path: String = "", line: int = 0, function: String = "", details: Dictionary = {}) -> void: + var coerced_level := _coerce_level(level) + var entry := { + "source": "editor", + "level": coerced_level, + "text": text, + "path": path, + "line": line, + "function": function, + } + if not details.is_empty(): + entry["details"] = details.duplicate(true) + _mutex.lock() + _append_entry(entry) + if coerced_level == "error": + _error_appended_total += 1 + elif coerced_level == "warn": + _warn_appended_total += 1 + _mutex.unlock() + + +func get_range(offset: int, count: int) -> Array[Dictionary]: + _mutex.lock() + var out := _get_range_unlocked(offset, count) + _mutex.unlock() + return out + + +func get_recent(count: int) -> Array[Dictionary]: + ## Single-lock so the size we compute `start` from can't race against + ## a concurrent append between the size read and the slice copy. + _mutex.lock() + var size := _total_count_unlocked() + var start := maxi(0, size - count) + var out := _get_range_unlocked(start, size - start) + _mutex.unlock() + return out + + +func get_since(since_seq: int, limit: int = -1) -> Dictionary: + ## Single-lock so the cursor snapshot and slice copy can't race against a + ## Logger-thread append. + _mutex.lock() + var out := _get_since_unlocked(since_seq, limit) + _mutex.unlock() + return out + + +func total_count() -> int: + _mutex.lock() + var n := _total_count_unlocked() + _mutex.unlock() + return n + + +func dropped_count() -> int: + _mutex.lock() + var n := _dropped_count_unlocked() + _mutex.unlock() + return n + + +func appended_total() -> int: + _mutex.lock() + var n := _appended_total_unlocked() + _mutex.unlock() + return n + + +func error_appended_total() -> int: + _mutex.lock() + var n := _error_appended_total + _mutex.unlock() + return n + + +func warn_appended_total() -> int: + _mutex.lock() + var n := _warn_appended_total + _mutex.unlock() + return n + + +func clear() -> int: + _mutex.lock() + var n := _total_count_unlocked() + _clear_storage() + _error_appended_total = 0 + _warn_appended_total = 0 + _mutex.unlock() + return n diff --git a/addons/godot_ai/utils/editor_log_buffer.gd.uid b/addons/godot_ai/utils/editor_log_buffer.gd.uid new file mode 100644 index 0000000..8c8d823 --- /dev/null +++ b/addons/godot_ai/utils/editor_log_buffer.gd.uid @@ -0,0 +1 @@ +uid://b6ynms0856hhq diff --git a/addons/godot_ai/utils/error_codes.gd b/addons/godot_ai/utils/error_codes.gd new file mode 100644 index 0000000..5dc3466 --- /dev/null +++ b/addons/godot_ai/utils/error_codes.gd @@ -0,0 +1,163 @@ +@tool +class_name McpErrorCodes +extends RefCounted + +## Error code constants shared across handlers. Mirrors protocol/errors.py. +## +## This `class_name` shipped in v2.3.2 and earlier and must stay reachable +## through self-update. v2.4.1 dropped it and triggered a "Could not resolve +## script" cascade for every user upgrading from any earlier version; v2.4.2 +## restored it as a hot-fix. The cascade fires because Godot keeps stale +## registry entries during the disable -> extract -> enable window when a +## previously-registered class_name disappears, and that failure mode is +## independent of the runner's install ordering. See CLAUDE.md's +## never-delete-published-class_name policy for the shape-aware shim path +## that retirement (if ever needed) must follow. +## +## All consumers use the preload-alias pattern +## (`const ErrorCodes := preload(...)`) introduced in #412. The alias is +## stylistic; both `McpErrorCodes.X` and `ErrorCodes.X` resolve through the +## same Script object cache, so the alias is not a parse-safety boundary +## under the single-phase runner. + +const INVALID_PARAMS := "INVALID_PARAMS" +const EDITED_SCENE_MISMATCH := "EDITED_SCENE_MISMATCH" +const EDITOR_NOT_READY := "EDITOR_NOT_READY" +const UNKNOWN_COMMAND := "UNKNOWN_COMMAND" +const INTERNAL_ERROR := "INTERNAL_ERROR" +const DEFERRED_TIMEOUT := "DEFERRED_TIMEOUT" +## Python-originated attach bridge codes. GDScript has no emit path, but the +## public registry intentionally mirrors protocol/errors.py. +const TRANSPORT_OUTCOME_UNKNOWN := "TRANSPORT_OUTCOME_UNKNOWN" +const NEW_CLIENT_SESSION_REQUIRED := "NEW_CLIENT_SESSION_REQUIRED" +const ATTACH_LOCK_TIMEOUT := "ATTACH_LOCK_TIMEOUT" +const ATTACH_LOCK_ERROR := "ATTACH_LOCK_ERROR" +const ATTACH_RUNTIME_DIR_ERROR := "ATTACH_RUNTIME_DIR_ERROR" +const PORT_OCCUPIED := "PORT_OCCUPIED" +const BACKEND_START_FAILED := "BACKEND_START_FAILED" +const BACKEND_START_TIMEOUT := "BACKEND_START_TIMEOUT" +# game_eval failure codes (#490) — keep in sync with protocol/errors.py +const EVAL_COMPILE_ERROR := "EVAL_COMPILE_ERROR" +const EVAL_RUNTIME_ERROR := "EVAL_RUNTIME_ERROR" +## #518/#859: the play session is up (EditorInterface.is_playing_scene() is true, +## so editor_handler's EDITOR_NOT_READY "game is not running" gate already +## passed) but the game cannot service evals: the helper did not register within +## EVAL_READY_WAIT_SEC, its main-loop beacon is stale, or its debugger session +## closed mid-eval. Carved out of INTERNAL_ERROR so these fast, +## caller-actionable failures do not burn the opaque 10s eval backstop. +const EVAL_GAME_NOT_READY := "EVAL_GAME_NOT_READY" +## #518: the eval genuinely never finished inside the timeout ladder — the +## game-side 8s deadline aborted a hung await, or the editor-side 10s backstop +## fired because the game never replied at all (CPU-bound loop, frozen / +## backgrounded idle loop). Carved out of INTERNAL_ERROR — the last big +## still-unlabeled bucket from #487/#488 — so "your eval code never finished" +## stops reading as an internal fault in telemetry and agent-facing errors. +const EVAL_HUNG := "EVAL_HUNG" +## #518: the eval completed but its serialized result is too large for the +## debugger + WebSocket pipeline. Without this the reply is dropped silently +## (the debugger TCP peer discards messages over ~8 MiB) and the request rides +## to the 10s backstop as a phantom "hang". Failing fast game-side with the +## real byte count makes the failure actionable (return a smaller slice). +const EVAL_RESULT_TOO_LARGE := "EVAL_RESULT_TOO_LARGE" +## #777: a game-side request (currently editor_screenshot source="game") +## reached a live, registered game helper but no reply came back before the +## editor-side timer fired. Every editor gate already passed +## (is_playing_scene, helper hello) so this is a TOP-LEVEL code, not an +## EDITOR_NOT_READY sub-code: the game process itself failed to respond — +## backgrounded with a frozen main loop and nothing rendered to fall back +## on, main thread blocked, or the helper died mid-run. Carved out of +## INTERNAL_ERROR (the largest opaque timeout bucket fleet-wide) so the +## residual timeout is attributable and actionable. +const GAME_HELPER_TIMEOUT := "GAME_HELPER_TIMEOUT" +## audit-v2 #21 (issue #365): finer-grained codes carved out of the 471 +## INVALID_PARAMS sites so agents can distinguish recoverable input +## errors from structural ones. INVALID_PARAMS stays for genuinely +## catch-all input errors that don't fit any of the buckets below. +## +## - NODE_NOT_FOUND: scene-tree/autoload node lookup failed (path didn't +## resolve to a Node). +## - RESOURCE_NOT_FOUND: a `res://` path lookup failed (file/.tres/ +## .gdshader/.tscn etc. doesn't exist or couldn't load). Distinct from +## NODE_NOT_FOUND because the recovery path differs — agents need to +## know whether to fix a node path vs. create/import a resource. +## - PROPERTY_NOT_ON_CLASS: property/signal/method/uniform/slot lookup +## failed on a known instance (path resolved, but the requested +## member doesn't exist on that class). +## - VALUE_OUT_OF_RANGE: numeric/index bound violation OR enum value +## not in the allowed set. +## - WRONG_TYPE: input was a value (or a loaded resource) of the wrong +## type — the param was provided, but `typeof` or `is X` failed. +## - MISSING_REQUIRED_PARAM: required input field was absent or empty. +const NODE_NOT_FOUND := "NODE_NOT_FOUND" +const RESOURCE_NOT_FOUND := "RESOURCE_NOT_FOUND" +const PROPERTY_NOT_ON_CLASS := "PROPERTY_NOT_ON_CLASS" +const VALUE_OUT_OF_RANGE := "VALUE_OUT_OF_RANGE" +const WRONG_TYPE := "WRONG_TYPE" +const MISSING_REQUIRED_PARAM := "MISSING_REQUIRED_PARAM" +const CUSTOM_TOOL_NOT_UNDOABLE := "CUSTOM_TOOL_NOT_UNDOABLE" +const CUSTOM_TOOL_DISABLED := "CUSTOM_TOOL_DISABLED" + +## #651 stage 1: EDITOR_NOT_READY sub-codes. These travel in +## `error.data.sub_code`, NEVER as the top-level `error.code` — existing +## callers and dashboards key on EDITOR_NOT_READY, so the top-level code is +## frozen. Each sub-code names the concrete editor state at rejection time, +## limited to states EditorInterface/EditorFileSystem can report +## deterministically. States we cannot observe (script compilation, +## resource reload, modal dialogs) intentionally get NO sub-code: a bare +## EDITOR_NOT_READY stays the honest fallback rather than a guessed label. +## Keep in sync with protocol/errors.py::EditorNotReadySubCode — enforced +## by tests/unit/test_editor_not_ready_hint_contract.py. +const SUB_EDITOR_IMPORTING := "EDITOR_IMPORTING" +const SUB_EDITOR_PLAYING := "EDITOR_PLAYING" +const SUB_EDITOR_NO_SCENE := "EDITOR_NO_SCENE" +const SUB_EDITOR_GAME_NOT_RUNNING := "EDITOR_GAME_NOT_RUNNING" +const SUB_EDITOR_VIEWPORT_UNAVAILABLE := "EDITOR_VIEWPORT_UNAVAILABLE" +const SUB_EDITOR_VIEWPORT_NOT_3D := "EDITOR_VIEWPORT_NOT_3D" +const SUB_EDITOR_VIEWPORT_EMPTY := "EDITOR_VIEWPORT_EMPTY" +const SUB_EDITOR_UNAVAILABLE := "EDITOR_UNAVAILABLE" +## Emitted only by the exclusive-run transport servicing path: a command +## arrived while a synchronous test run holds the main thread, and was +## rejected (not buffered) so it can't replay stale after its server-side +## future expires. See connection.gd::service_transport_during_exclusive_run. +const SUB_EDITOR_TEST_RUNNING := "EDITOR_TEST_RUNNING" + +## Terminal code for a test run that hit its between-test abort ceiling +## before finishing. error.data carries the partial summary; full partial +## results stay retrievable via get_test_results. +const TEST_RUN_TIMEOUT := "TEST_RUN_TIMEOUT" + + +## Build a standard error response dictionary. +static func make(code: String, message: String) -> Dictionary: + return {"status": "error", "error": {"code": code, "message": message}} + + +## Build an EDITOR_NOT_READY error carrying the #651 stage-1 attribution +## payload: `data.sub_code` + `retryable` + `hint`. Mirrors the shape +## scene_path.gd::require_edited_scene established (editor_state/retryable/ +## hint). `hint` may be empty when `message` already IS the recovery hint — +## the server's GodotCommandError string-appends every data key, so +## duplicating the message into data would double the agent-visible text. +static func make_not_ready( + sub_code: String, message: String, retryable: bool, hint: String = "" +) -> Dictionary: + var err := make(EDITOR_NOT_READY, message) + var data := {"sub_code": sub_code, "retryable": retryable} + if not hint.is_empty(): + data["hint"] = hint + err["error"]["data"] = data + return err + + +## Return a NEW error dict with the original code and a prefixed message. +## Prefer this over mutating `err["error"]["message"]` in place — callers +## that want to add context ("Property '%s': …") shouldn't need to know +## the internal shape of the dict returned by `make`. Empty `prefix` +## returns `err` unchanged so callers don't need their own guard. +static func prefix_message(err: Dictionary, prefix: String) -> Dictionary: + if prefix.is_empty(): + return err + var inner: Dictionary = err.get("error", {}) + var code: String = inner.get("code", INTERNAL_ERROR) + var message: String = inner.get("message", "") + return make(code, "%s: %s" % [prefix, message]) diff --git a/addons/godot_ai/utils/error_codes.gd.uid b/addons/godot_ai/utils/error_codes.gd.uid new file mode 100644 index 0000000..fcc1e82 --- /dev/null +++ b/addons/godot_ai/utils/error_codes.gd.uid @@ -0,0 +1 @@ +uid://d2klnglf5p861 diff --git a/addons/godot_ai/utils/fuzzy_suggestions.gd b/addons/godot_ai/utils/fuzzy_suggestions.gd new file mode 100644 index 0000000..de7cc19 --- /dev/null +++ b/addons/godot_ai/utils/fuzzy_suggestions.gd @@ -0,0 +1,39 @@ +@tool +extends RefCounted + +## Shared fuzzy ranking for typo suggestions. + + +static func rank( + needle: String, + candidates: Array, + limit: int = 5, + threshold: float = 0.4, + substring_bonus: float = 0.5, + prefix_bonus: float = 1.0 +) -> Array[String]: + if needle.is_empty() or candidates.is_empty(): + return [] + var needle_lower := needle.to_lower() + var scored: Array = [] + for raw_candidate in candidates: + var candidate := str(raw_candidate) + var candidate_lower := candidate.to_lower() + var score := needle.similarity(candidate) + if prefix_bonus != 0.0 and candidate_lower.begins_with(needle_lower): + score += prefix_bonus + elif substring_bonus != 0.0 and ( + candidate_lower.contains(needle_lower) or needle_lower.contains(candidate_lower) + ): + score += substring_bonus + if score >= threshold: + scored.append([score, candidate]) + scored.sort_custom(func(a, b): + if a[0] == b[0]: + return a[1] < b[1] + return a[0] > b[0] + ) + var result: Array[String] = [] + for index in range(min(limit, scored.size())): + result.append(scored[index][1]) + return result diff --git a/addons/godot_ai/utils/fuzzy_suggestions.gd.uid b/addons/godot_ai/utils/fuzzy_suggestions.gd.uid new file mode 100644 index 0000000..c663d01 --- /dev/null +++ b/addons/godot_ai/utils/fuzzy_suggestions.gd.uid @@ -0,0 +1 @@ +uid://bxwaws6w0xw60 diff --git a/addons/godot_ai/utils/game_log_buffer.gd b/addons/godot_ai/utils/game_log_buffer.gd new file mode 100644 index 0000000..2f1b3b0 --- /dev/null +++ b/addons/godot_ai/utils/game_log_buffer.gd @@ -0,0 +1,105 @@ +@tool +class_name McpGameLogBuffer +extends McpStructuredLogRing + +## Ring buffer for game-process log lines (print, push_warning, push_error) +## ferried back from the playing game over the EngineDebugger channel. +## +## Larger cap than McpEditorLogBuffer because games can be noisy. `run_id` +## rotates at play-start, giving agents a stable cursor for "lines from +## this run" even when the game never reaches the mcp:hello boot beacon. +## +## Single-threaded — game_helper.gd drains its logger from `_process` and +## calls `append` from the main thread, so this subclass can use the base +## ring's lockless reads/writes directly. + +const MAX_LINES := 2000 + +var _run_id := "" +var _run_seq := 0 +var _error_warn_total := 0 +var _error_total := 0 + + +func _init() -> void: + super._init(MAX_LINES) + + +func append(level: String, text: String, details: Dictionary = {}) -> void: + var coerced_level := _coerce_level(level) + var entry := { + "source": "game", + "level": coerced_level, + "text": text, + "run_id": _run_id, + } + if not details.is_empty(): + entry["details"] = details.duplicate(true) + _append_entry(entry) + if coerced_level in ["warn", "error"]: + _error_warn_total += 1 + if coerced_level == "error": + _error_total += 1 + + +## Rotate the run identifier without dropping buffered entries. Called at +## play-start so even no-hello parse failures get a fresh current-run identity. +## Historical lines stay tagged with their original run_id and can still be +## queried explicitly. +func clear_for_new_run() -> String: + _run_id = _generate_run_id() + _error_warn_total = 0 + _error_total = 0 + return _run_id + + +func run_id() -> String: + return _run_id + + +func error_warn_total() -> int: + return _error_warn_total + + +func error_total() -> int: + return _error_total + + +## Warn-level lines for the current run: the combined error+warn tally minus +## the error-only tally. Feeds the `game_warn` watermark component so a run +## that only emitted push_warning is no longer reported as clean. +func warn_total() -> int: + return _error_warn_total - _error_total + + +func get_run_range(run_id: String, offset: int, count: int) -> Array[Dictionary]: + return get_run_page(run_id, offset, count).entries + + +func get_run_page(run_id: String, offset: int, count: int) -> Dictionary: + var entries := _entries_for_run(run_id) + var start := mini(maxi(0, offset), entries.size()) + var stop := mini(entries.size(), start + maxi(0, count)) + var out: Array[Dictionary] = [] + for i in range(start, stop): + out.append(entries[i]) + return { + "entries": out, + "total_count": entries.size(), + } + + +func _entries_for_run(run_id: String) -> Array[Dictionary]: + var out: Array[Dictionary] = [] + for entry in get_range(0, total_count()): + if str(entry.get("run_id", "")) == run_id: + out.append(entry) + return out + + +func _generate_run_id() -> String: + ## Opaque to agents — they only check equality. Time-based is plenty + ## unique within a single editor session; the local sequence protects + ## fast back-to-back test runs within the same millisecond. + _run_seq += 1 + return "r%d-%d" % [Time.get_ticks_msec(), _run_seq] diff --git a/addons/godot_ai/utils/game_log_buffer.gd.uid b/addons/godot_ai/utils/game_log_buffer.gd.uid new file mode 100644 index 0000000..6c7ce7d --- /dev/null +++ b/addons/godot_ai/utils/game_log_buffer.gd.uid @@ -0,0 +1 @@ +uid://biojw0xl64haw diff --git a/addons/godot_ai/utils/json_values.gd b/addons/godot_ai/utils/json_values.gd new file mode 100644 index 0000000..d745d02 --- /dev/null +++ b/addons/godot_ai/utils/json_values.gd @@ -0,0 +1,92 @@ +@tool +class_name McpJsonValues +extends RefCounted + +## Canonical JSON→Variant parsers for the wire shapes agents send. +## +## One parser family instead of five drifted per-handler copies (#714) — +## the canonical color set is the maintainer decision recorded on that +## issue. parse_color accepts: Color passthrough; "#rrggbb"/"#rrggbbaa" +## hex or named-color strings (two-sentinel Color.from_string +## validation); {r,g,b[,a]} dicts; [r,g,b[,a]] arrays. parse_vector2/3 +## accept the Vector passthrough, {x,y[,z]} dicts, and [x,y[,z]] arrays. +## +## Strict WITHIN each shape (the #123/#126 contract): wrong dict keys, +## wrong array lengths, or non-numeric components return null instead of +## guessing zeros — callers turn null into their own typed error. + +const COLOR_KEYS: Array[String] = ["r", "g", "b"] +const VECTOR2_KEYS: Array[String] = ["x", "y"] +const VECTOR3_KEYS: Array[String] = ["x", "y", "z"] + + +static func parse_color(value: Variant) -> Variant: + if value is Color: + return value + if value is String: + ## Color.from_string returns the fallback on parse failure — call + ## twice with distinct sentinels; agreement means a real parse. + var a := Color.from_string(value, Color(0, 0, 0, 0)) + var b := Color.from_string(value, Color(1, 1, 1, 1)) + if a != b: + return null + return a + if value is Dictionary: + var d: Dictionary = value + if not d.has_all(COLOR_KEYS): + return null + var alpha: Variant = d.get("a", 1.0) + if not (_is_number(d.r) and _is_number(d.g) and _is_number(d.b) and _is_number(alpha)): + return null + return Color(float(d.r), float(d.g), float(d.b), float(alpha)) + if value is Array: + var arr: Array = value + if arr.size() != 3 and arr.size() != 4: + return null + for item in arr: + if not _is_number(item): + return null + var a4 := float(arr[3]) if arr.size() == 4 else 1.0 + return Color(float(arr[0]), float(arr[1]), float(arr[2]), a4) + return null + + +static func parse_vector2(value: Variant) -> Variant: + if value is Vector2: + return value + if value is Dictionary: + var d: Dictionary = value + if not d.has_all(VECTOR2_KEYS) or not (_is_number(d.x) and _is_number(d.y)): + return null + return Vector2(float(d.x), float(d.y)) + if value is Array: + var arr: Array = value + if arr.size() != 2 or not (_is_number(arr[0]) and _is_number(arr[1])): + return null + return Vector2(float(arr[0]), float(arr[1])) + return null + + +static func parse_vector3(value: Variant) -> Variant: + if value is Vector3: + return value + if value is Dictionary: + var d: Dictionary = value + if not d.has_all(VECTOR3_KEYS): + return null + if not (_is_number(d.x) and _is_number(d.y) and _is_number(d.z)): + return null + return Vector3(float(d.x), float(d.y), float(d.z)) + if value is Array: + var arr: Array = value + if arr.size() != 3: + return null + for item in arr: + if not _is_number(item): + return null + return Vector3(float(arr[0]), float(arr[1]), float(arr[2])) + return null + + +static func _is_number(v: Variant) -> bool: + return v is int or v is float diff --git a/addons/godot_ai/utils/json_values.gd.uid b/addons/godot_ai/utils/json_values.gd.uid new file mode 100644 index 0000000..b3eeba9 --- /dev/null +++ b/addons/godot_ai/utils/json_values.gd.uid @@ -0,0 +1 @@ +uid://4wbf83hwckms diff --git a/addons/godot_ai/utils/log_backtrace.gd b/addons/godot_ai/utils/log_backtrace.gd new file mode 100644 index 0000000..3fdf838 --- /dev/null +++ b/addons/godot_ai/utils/log_backtrace.gd @@ -0,0 +1,113 @@ +@tool +class_name McpLogBacktrace +extends RefCounted + +## Helpers for interpreting Godot's `_log_error` virtual arguments. +## (Named `McpLogBacktrace`, not `ScriptBacktrace`: Godot ships a built-in +## `ScriptBacktrace` class — the type of `script_backtraces[i]` entries +## — so class_name'ing ours the same would collide. Verified against +## the engine's `--doctool` output in 4.6.) +## +## Both `editor_logger.gd` and `game_logger.gd` need to: +## - Map `error_type` (0=ERROR, 1=WARNING, 2=SCRIPT, 3=SHADER) to a +## two-bucket "error" / "warn" string so callers can filter without +## consulting the enum. +## - Fall back to `code` when `rationale` is empty — single-arg +## `push_error("msg")` leaves rationale empty and stuffs the user's +## string into `code`; without the fallback the user message is +## silently lost. The two-arg form `push_error(code, rationale)` +## populates both and rationale wins. +## - Remap the source location to the first frame of `script_backtraces[0]` +## when present. `push_error` / `push_warning` always report +## `file=core/variant/variant_utility.cpp`; the actual user GDScript +## caller is in the backtrace. +## +## Centralising the rules keeps the next push_error semantics shift +## (already happened once between 4.5 and 4.6, see PR #78) a one-place +## fix instead of a two-place hunt. + + +## Coalesce the per-virtual-arg shape Godot hands `_log_error` into a +## flat record. Always walks `script_backtraces` for the first non-empty +## frame; loggers that need to filter by source path call this first and +## then check the resolved `path` field. +## +## Returns: `{level, message, path, line, function, details}` +## - `level`: "error" or "warn" (warn iff `error_type == 1`). +## - `message`: `rationale` when non-empty, else `code`. +## - `path` / `line` / `function`: first backtrace frame when one is +## available; otherwise the original `file` / `line` / `function`. +## - `details`: original `_log_error` fields plus the first non-empty +## backtrace as frames, mirroring the debugger Errors tab context. +const ERROR_TYPE_NAMES := { + 0: "error", + 1: "warning", + 2: "script", + 3: "shader", +} + + +static func resolve_error( + function: String, + file: String, + line: int, + code: String, + rationale: String, + error_type: int, + script_backtraces: Array, +) -> Dictionary: + var src_file := file + var src_line := line + var src_function := function + var frames: Array[Dictionary] = [] + ## First non-empty frame wins, not just `script_backtraces[0]` — + ## chained errors can leave the leading entry empty with the actual + ## user frame in `script_backtraces[1]`. + for bt in script_backtraces: + if bt != null and bt.get_frame_count() > 0: + frames = _frames_from_backtrace(bt) + src_file = str(frames[0].get("path", "")) + src_line = int(frames[0].get("line", 0)) + src_function = str(frames[0].get("function", "")) + break + var message := rationale if not rationale.is_empty() else code + return { + "level": "warn" if error_type == 1 else "error", + "message": message, + "path": src_file, + "line": src_line, + "function": src_function, + "details": { + "message": message, + "code": code, + "rationale": rationale, + "error_type": error_type, + "error_type_name": _error_type_name(error_type), + "source": { + "path": file, + "line": line, + "function": function, + }, + "resolved": { + "path": src_file, + "line": src_line, + "function": src_function, + }, + "frames": frames, + }, + } + + +static func _frames_from_backtrace(bt) -> Array[Dictionary]: + var frames: Array[Dictionary] = [] + for i in bt.get_frame_count(): + frames.append({ + "path": bt.get_frame_file(i), + "line": bt.get_frame_line(i), + "function": bt.get_frame_function(i), + }) + return frames + + +static func _error_type_name(error_type: int) -> String: + return str(ERROR_TYPE_NAMES.get(error_type, "unknown")) diff --git a/addons/godot_ai/utils/log_backtrace.gd.uid b/addons/godot_ai/utils/log_backtrace.gd.uid new file mode 100644 index 0000000..4845ad8 --- /dev/null +++ b/addons/godot_ai/utils/log_backtrace.gd.uid @@ -0,0 +1 @@ +uid://b8t9kznr2pqxa diff --git a/addons/godot_ai/utils/log_buffer.gd b/addons/godot_ai/utils/log_buffer.gd new file mode 100644 index 0000000..34bd2b5 --- /dev/null +++ b/addons/godot_ai/utils/log_buffer.gd @@ -0,0 +1,67 @@ +@tool +class_name McpLogBuffer +extends RefCounted + +## Ring buffer for MCP log lines. Also prints to Godot console. + +const MAX_LINES := 500 + +## When false, `log()` still records into the ring buffer but does not echo the +## line to the Godot console. The test runner flips this off for the duration +## of a run so negative-path suites (which intentionally drive a 500-line ring +## fill and malformed-result error logging) don't bury an all-green run in +## console noise. Ring *contents* — what tests assert on via `get_recent()` / +## `total_logged()` — are unaffected. Engine-level C++ errors raised by +## negative-path tests are not routed through here and still surface. +static var console_echo := true + +var _lines: Array[String] = [] +## Monotonic count of every line ever passed to `log()` since the last +## `clear()`. Distinct from `_lines.size()`, which is bounded at MAX_LINES. +## Consumers that need to detect "new lines arrived" (e.g. `LogViewer.tick`) +## must track this rather than the bounded size — once the ring fills, the +## size stays at MAX_LINES on every subsequent append, so a size-based +## cursor would freeze and the consumer would stop seeing new entries. +var _total_logged: int = 0 +var enabled := true + + +## `echo=false` records the line into the ring (so the dock's log panel shows +## it) without printing to the Godot console. Used for high-frequency +## machine-driven lines like readiness flips, which spammed the console of +## every install (#626) — filesystem scans toggle readiness on each import. +func log(msg: String, echo: bool = true) -> void: + var line := "MCP | %s" % msg + if enabled and console_echo and echo: + print(line) + _lines.append(line) + if _lines.size() > MAX_LINES: + _lines = _lines.slice(-MAX_LINES) + _total_logged += 1 + + +func get_recent(count: int = 50) -> Array[String]: + var start := maxi(0, _lines.size() - count) + var result: Array[String] = [] + result.assign(_lines.slice(start)) + return result + + +func clear() -> void: + _lines.clear() + ## Reset the monotonic counter so a viewer's `seq < _last_seq` shrink + ## detection still recognizes the clear. Callers that want a cumulative + ## ever-produced count across clears can wrap their own counter. + _total_logged = 0 + + +func total_count() -> int: + return _lines.size() + + +## Monotonic sequence — number of lines ever appended via `log()` since +## the last `clear()`. Strictly increases per append, even once the ring +## has filled and `total_count()` is pinned at MAX_LINES. See `_total_logged` +## for rationale. +func total_logged() -> int: + return _total_logged diff --git a/addons/godot_ai/utils/log_buffer.gd.uid b/addons/godot_ai/utils/log_buffer.gd.uid new file mode 100644 index 0000000..58341ca --- /dev/null +++ b/addons/godot_ai/utils/log_buffer.gd.uid @@ -0,0 +1 @@ +uid://ddkslse7511e6 diff --git a/addons/godot_ai/utils/mcp_adoption_label.gd b/addons/godot_ai/utils/mcp_adoption_label.gd new file mode 100644 index 0000000..3114037 --- /dev/null +++ b/addons/godot_ai/utils/mcp_adoption_label.gd @@ -0,0 +1,23 @@ +@tool +class_name McpAdoptionLabel +extends RefCounted + +## Outcome flag for `McpServerLifecycleManager.adopt_compatible_server`. +## Distinguishes a same-version managed adoption (we own the PID, can +## restart it) from an external compatible adoption (some other plugin +## instance / dev server owns the process; we just rendezvoused with it). +## +## Was a free-form string in PR 5; promoted to constants here because +## the seam now spans `server_lifecycle.gd`, `plugin.gd`'s log helper, +## the dock's restart-button gating, and the test suite. Stable strings +## keep log scrapes and characterization fixtures unaffected. + +## We have a PID we spawned (or re-acquired by reading the managed +## record + verifying liveness). `force_restart_server` and +## `prepare_for_update_reload` may target this PID. +const MANAGED := "managed" + +## A compatible godot-ai server is on the port but we don't own its +## PID — likely another plugin instance's spawn, or a developer-run +## `godot-ai --reload` server. We reuse it but won't kill it on stop. +const EXTERNAL := "external" diff --git a/addons/godot_ai/utils/mcp_adoption_label.gd.uid b/addons/godot_ai/utils/mcp_adoption_label.gd.uid new file mode 100644 index 0000000..aee58fe --- /dev/null +++ b/addons/godot_ai/utils/mcp_adoption_label.gd.uid @@ -0,0 +1 @@ +uid://klhsu1cuhcue diff --git a/addons/godot_ai/utils/mcp_client_refresh_state.gd b/addons/godot_ai/utils/mcp_client_refresh_state.gd new file mode 100644 index 0000000..fbc0b84 --- /dev/null +++ b/addons/godot_ai/utils/mcp_client_refresh_state.gd @@ -0,0 +1,107 @@ +@tool +class_name McpClientRefreshState +extends RefCounted + +## State machine for the dock's client-status refresh sweep. Single +## source of truth — supersedes the seven booleans + deadline previously +## scattered across `mcp_dock.gd` (`_client_status_refresh_in_flight`, +## `_client_status_refresh_pending`, `_client_status_refresh_pending_force`, +## `_client_status_refresh_timed_out`, `_client_status_refresh_started_msec`, +## `_client_status_refresh_deferred_until_filesystem_ready`, +## `_client_status_refresh_deferred_force`, +## `_client_status_refresh_deferred_initial`, +## `_client_status_refresh_shutdown_requested`). +## +## The ints are stable for tests; reordering is a breaking change. + +## No worker running, no pending request. Default state. +const IDLE := 0 +## A refresh request landed but the editor filesystem is busy +## (`EditorInterface.get_resource_filesystem().is_scanning()` is true); +## the dock parks the request and retries on the next `_process` after +## the scan settles. Held alongside two flags (force / initial) for +## what kind of refresh to retry; those live next to the state, not +## inside it, because they're requests not state. +const DEFERRED_FOR_FILESYSTEM := 1 +## Worker thread is alive and probing client status off-main. The +## dock paints "(checking...)" in the clients summary and accepts +## additional requests as `pending`. +const RUNNING := 2 +## Worker has been alive past CLIENT_STATUS_REFRESH_TIMEOUT_MSEC. The +## dock paints "(client probe still running)" and a forced refresh is +## allowed to abandon the worker into the orphan list and start a new +## sweep. The state stays RUNNING after a forced abandon-and-restart. +const RUNNING_TIMED_OUT := 3 +## `_exit_tree` / `_install_update` is draining workers. New refresh +## requests are rejected outright. Set once and not cleared (the dock +## instance is being torn down). +const SHUTTING_DOWN := 4 + +const _NAMES := { + IDLE: "idle", + DEFERRED_FOR_FILESYSTEM: "deferred_for_filesystem", + RUNNING: "running", + RUNNING_TIMED_OUT: "running_timed_out", + SHUTTING_DOWN: "shutting_down", +} + + +static func name_of(state: int) -> String: + return _NAMES.get(state, "unknown(%d)" % state) + + +## True when a worker thread should be alive in this state. Combined +## state — RUNNING or RUNNING_TIMED_OUT both have a worker running, but +## the timed-out flavor allows a force-refresh to abandon it. +static func has_worker_alive(state: int) -> bool: + return state == RUNNING or state == RUNNING_TIMED_OUT + + +## True while the status worker is still within its healthy budget. Once a +## refresh has timed out, the dock keeps the warning badge but must let users +## retry Configure / Configure all instead of stranding the controls behind an +## orphaned, uninterruptible worker. +static func should_disable_client_actions(state: int) -> bool: + return state == RUNNING + + +## True when the dock should reject new refresh spawns. Used by the +## dock's two refresh-spawn guards (the deferred refresh entrypoint and +## the status-refresh scheduler). +static func is_blocked_for_spawn(state: int) -> bool: + return state == SHUTTING_DOWN + + +## True when the summary label should show the in-flight badge. +static func should_show_checking_badge(state: int) -> bool: + return state == RUNNING or state == RUNNING_TIMED_OUT + + +## Transition table. Same shape as McpServerState — illegal transitions +## return false; callers `push_warning` and no-op. +static func can_transition(from: int, to: int) -> bool: + if from == to: + return true + ## Shutdown is sticky. + if from == SHUTTING_DOWN: + return false + ## Anything → SHUTTING_DOWN is legal (drain on _exit_tree / install). + if to == SHUTTING_DOWN: + return true + match from: + IDLE: + return to == RUNNING or to == DEFERRED_FOR_FILESYSTEM + DEFERRED_FOR_FILESYSTEM: + ## When the filesystem scan settles we either spawn a worker + ## (RUNNING) or roll back to IDLE if no rows need probing. + return to == RUNNING or to == IDLE + RUNNING: + ## Worker finishes -> IDLE. Worker outlives budget -> + ## RUNNING_TIMED_OUT. Forced respawn after orphan abandon + ## stays in RUNNING (covered by from == to above). + return to == IDLE or to == RUNNING_TIMED_OUT + RUNNING_TIMED_OUT: + ## Late-arriving worker result drops back to IDLE; forced + ## abandon-and-respawn drops back to RUNNING. + return to == IDLE or to == RUNNING + return false diff --git a/addons/godot_ai/utils/mcp_client_refresh_state.gd.uid b/addons/godot_ai/utils/mcp_client_refresh_state.gd.uid new file mode 100644 index 0000000..9e4129c --- /dev/null +++ b/addons/godot_ai/utils/mcp_client_refresh_state.gd.uid @@ -0,0 +1 @@ +uid://dv4tukg6eioww diff --git a/addons/godot_ai/utils/mcp_server_state.gd b/addons/godot_ai/utils/mcp_server_state.gd new file mode 100644 index 0000000..24597f4 --- /dev/null +++ b/addons/godot_ai/utils/mcp_server_state.gd @@ -0,0 +1,182 @@ +@tool +class_name McpServerState +extends RefCounted + +## State machine for the plugin's server-spawn / adopt / version-verify +## lifecycle. Single source of truth — supersedes the boolean-flag thicket +## (`_server_started_this_session`, `_awaiting_server_version`, +## `_server_version_deadline_ms`, `_connection_blocked`, +## `_can_recover_incompatible`, `_refresh_retried`, +## `_adoption_watch_deadline_ms`) and the older terminal-only +## McpSpawnState string union. +## +## The integer values matter — they're what `get_server_status()` +## surfaces, what the dock pattern-matches on, and what the test suites +## assert against. Reordering the enum is a breaking change. +## +## The transitions are documented in `can_transition()`. The lifecycle +## manager calls `set_state()` which: +## 1. Validates the transition (logs a warning + no-ops on illegal). +## 2. Preserves first-writer-wins among terminal diagnoses so a late +## CRASHED from the watch loop can't clobber an earlier +## PORT_EXCLUDED from the proactive Windows reservation check. + +## Fresh plugin instance, `_start_server` has not run yet. Default state. +const UNINITIALIZED := 0 +## Process spawned via OS.create_process; watch loop is observing the +## SPAWN_GRACE_MS window. Transitions directly to READY (handshake_ack +## verifies a compatible version), CRASHED (process died early), or +## INCOMPATIBLE (handshake reported a mismatch). +const SPAWNING := 1 +## (slot 2 reserved — keep wire-compat for clients pattern-matching +## numeric `editor_state.state` values; do not reuse.) +## Server is healthy and version-verified. Happy path. Includes both +## "spawned fresh" and "adopted compatible existing server" flavors — +## adoption flavor is recorded separately via `McpAdoptionLabel`. +const READY := 3 +## Live server on the HTTP port returned a version that doesn't match +## what this plugin expects, OR returned no `handshake_ack` inside the +## timeout. Connection is blocked; recovery requires a kill+respawn +## click via `recover_incompatible_server`. +const INCOMPATIBLE := 4 +## Spawned process exited inside the SPAWN_GRACE_MS window. Python +## traceback went to Godot's output log. Terminal — reload the plugin +## or restart the editor to retry. +const CRASHED := 5 +## No server command resolved: no `.venv` Python, no `uvx` on PATH, no +## system `godot-ai`. Terminal — install guidance shown in dock. +const NO_COMMAND := 6 +## Windows reserved the HTTP port via Hyper-V / WSL2 / Docker exclusion +## range. Caught proactively before bind. Terminal — port picker shown. +const PORT_EXCLUDED := 7 +## HTTP port held by a process we didn't spawn (no matching managed +## record). Plugin armed an adoption-confirmation watcher; if the foreign +## occupant turns out to be a compatible godot-ai server, +## `handle_server_version_verified` transitions to READY. If the +## adoption deadline expires without a connection, the watcher self- +## disarms but the state stays at FOREIGN_PORT — the dock keeps showing +## "port held by another process" until the user reloads. The version- +## check seam (separate from the adoption deadline) is what fires +## INCOMPATIBLE on a positive-but-mismatched handshake. +const FOREIGN_PORT := 8 +## Static re-entrancy guard fired (`_server_started_this_session` was +## already true). The plugin is being re-enabled within the same editor +## session; the previous instance still owns the spawn. Terminal — does +## NOT block READY paths, just records that this enable cycle no-op'd. +const GUARDED := 9 +## stop_server / prepare_for_update_reload in progress. Transitional — +## next state is STOPPED. +const STOPPING := 10 +## stop_server completed; `_server_pid` reset to -1, port may or may +## not be free. From here a fresh `start_server` call moves back through +## SPAWNING / READY. +const STOPPED := 11 + +const _NAMES := { + UNINITIALIZED: "uninitialized", + SPAWNING: "spawning", + READY: "ready", + INCOMPATIBLE: "incompatible", + CRASHED: "crashed", + NO_COMMAND: "no_command", + PORT_EXCLUDED: "port_excluded", + FOREIGN_PORT: "foreign_port", + GUARDED: "guarded", + STOPPING: "stopping", + STOPPED: "stopped", +} + + +## Human-readable label. Used in startup-trace logs and transition +## warnings. Falls back to `unknown()` for unrecognised values so +## a future enum addition won't crash the formatter. +static func name_of(state: int) -> String: + return _NAMES.get(state, "unknown(%d)" % state) + + +## True for any state the dock should render as a non-OK diagnostic +## panel. Used as the "should we hide the spawn-failure panel?" gate. +static func is_terminal_diagnosis(state: int) -> bool: + return ( + state == CRASHED + or state == NO_COMMAND + or state == PORT_EXCLUDED + or state == INCOMPATIBLE + or state == FOREIGN_PORT + ) + + +## True when the dock should consider the server unsuitable for client +## health checks (incompatible tool surface). Currently just INCOMPATIBLE +## — FOREIGN_PORT is transitional and may resolve to READY if the +## foreign occupant turns out to speak our handshake. +static func blocks_client_health(state: int) -> bool: + return state == INCOMPATIBLE + + +## Transition validation table. Returns true when `from -> to` is a +## legal transition the lifecycle manager should accept. Illegal +## transitions are silently no-op'd at the call site (with a +## `push_warning` log) — this preserves the first-writer-wins contract +## that prevents a late CRASHED from the watch loop overwriting an +## earlier PORT_EXCLUDED diagnosis. +static func can_transition(from: int, to: int) -> bool: + if from == to: + return true + ## Stop is always legal — teardown / install reload short-circuits + ## any in-flight state. + if to == STOPPING: + return true + if to == STOPPED and from == STOPPING: + return true + ## STOPPED can also be reached directly when `_server_pid <= 0` and + ## stop_server early-returns; treat it as legal from any state to + ## keep the teardown path forgiving. + if to == STOPPED: + return true + ## STOPPED -> any (re-arm via restart paths). + if from == STOPPED: + return true + ## GUARDED is sticky for the rest of this enable cycle; only stop is + ## legal out of it. Already covered by the stop checks above. + if from == GUARDED: + return false + ## Terminal diagnoses freeze further forward transitions. Recovery + ## goes through STOPPING (covered above), so any other target is + ## rejected — this is the first-writer-wins contract. + if ( + from == CRASHED + or from == NO_COMMAND + or from == PORT_EXCLUDED + or from == INCOMPATIBLE + ): + return false + ## UNINITIALIZED is the boot state — any target except STOPPING is + ## reachable directly (start_server's early branches set + ## terminal states without going through SPAWNING). + if from == UNINITIALIZED: + return true + ## In-flight forward transitions. + match from: + SPAWNING: + return ( + to == READY + or to == CRASHED + or to == FOREIGN_PORT + or to == INCOMPATIBLE + ) + FOREIGN_PORT: + return to == READY or to == INCOMPATIBLE + READY: + ## Late incompatibility detection (e.g. version verifier + ## re-arms after a foreign-port reconnect that turns out + ## to be incompatible after all). + return to == INCOMPATIBLE or to == CRASHED + STOPPING: + ## Recovery rollback: kill-then-respawn paths that fail to + ## free the port re-latch INCOMPATIBLE (so the dock keeps + ## the diagnostic UI) or fall back to UNINITIALIZED (clean + ## baseline for a follow-up `_set_incompatible_server`). + ## STOPPING -> STOPPED is handled by the early checks above. + return to == INCOMPATIBLE or to == UNINITIALIZED + return false diff --git a/addons/godot_ai/utils/mcp_server_state.gd.uid b/addons/godot_ai/utils/mcp_server_state.gd.uid new file mode 100644 index 0000000..dc5bef9 --- /dev/null +++ b/addons/godot_ai/utils/mcp_server_state.gd.uid @@ -0,0 +1 @@ +uid://d3ial4erjonlq diff --git a/addons/godot_ai/utils/mcp_startup_path.gd b/addons/godot_ai/utils/mcp_startup_path.gd new file mode 100644 index 0000000..130b8e1 --- /dev/null +++ b/addons/godot_ai/utils/mcp_startup_path.gd @@ -0,0 +1,34 @@ +@tool +class_name McpStartupPath +extends RefCounted + +## Branch-tag enum for `McpServerLifecycleManager.start_server`. Records +## which arm of the spawn / adopt / drift / recover decision tree the +## current `_enter_tree` walked. Surfaced via the startup trace log so +## a Windows port-reservation issue or a stale-record kill can be +## reconstructed from the editor output. +## +## Single-file constants, not an int enum, because the values land in +## startup-trace text and the strings are stable across releases (the +## CLAUDE.md "tool surface" entry references them by name). + +const UNSET := "" +## Re-entrancy guard fired; this enable cycle did not spawn or adopt. +const GUARDED := "guarded" +## Adopted a compatible existing server (managed or external). +const ADOPTED := "adopted" +## Spawned a fresh server process. +const SPAWNED := "spawned" +## OS.create_process returned -1 or proactive Windows reservation +## detected. Either way the spawn never produced a live process. +const CRASHED := "crashed" +## Windows port-exclusion check fired — port is blocked at the OS layer. +const RESERVED := "reserved" +## Server-command discovery returned an empty list — no .venv, no uvx, +## no system godot-ai. +const NO_COMMAND := "no_command" +## Drift-recovery kill fell through; we set INCOMPATIBLE and stayed. +const INCOMPATIBLE := "incompatible" +## Port was free at start; this is the prelude to SPAWNED but kept as +## a distinct path so adopt-vs-spawn is unambiguous in the trace. +const FREE := "free" diff --git a/addons/godot_ai/utils/mcp_startup_path.gd.uid b/addons/godot_ai/utils/mcp_startup_path.gd.uid new file mode 100644 index 0000000..fd01066 --- /dev/null +++ b/addons/godot_ai/utils/mcp_startup_path.gd.uid @@ -0,0 +1 @@ +uid://cikdvq2x4vs4x diff --git a/addons/godot_ai/utils/path_validator.gd b/addons/godot_ai/utils/path_validator.gd new file mode 100644 index 0000000..c181578 --- /dev/null +++ b/addons/godot_ai/utils/path_validator.gd @@ -0,0 +1,198 @@ +@tool +class_name McpPathValidator +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Validates `res://`-rooted paths against directory-traversal escape. +## +## Issue #347 (audit-v2 #3): handlers were accepting `res://../etc/passwd.gd` +## because the only check was `path.begins_with("res://")`. LLM-driven path +## generation (prompt injection, agent typos, untrusted issue/PR text in +## context) can produce traversal payloads for the write tools that produce +## arbitrary disk content (`script_create`, `filesystem_write_text`, +## `patch_script`) and for the matching reads (info disclosure surface). +## +## Two entry points: +## * `validate_resource_path` — for paths that name a `res://` disk file the +## plugin will read or (with `for_write`) write. This is the strict one. +## * `validate_loadable_path` — for paths handed to `ResourceLoader`, which +## also accepts `uid://` (an opaque resource-DB id that cannot express +## traversal) and `user://` (the per-project user data sandbox). Load +## handlers must use this so `uid://` references copied out of `.tscn` +## ExtResource / `.uid` sidecars and `user://` runtime assets keep loading. +## +## Error wrapping: callers should use `path_error` / `loadable_error`, which +## return a ready `ErrorCodes.make(VALUE_OUT_OF_RANGE, …)` dict (or null). A +## bad path is a value-domain error, and funneling every site through one +## wrapper keeps the error code consistent across all handlers. +## +## Known limitation: containment is lexical (`globalize_path` + `simplify_path` +## prefix match). It does NOT resolve symlinks — GDScript exposes no realpath. +## A symlink *inside* the project that points outside it can therefore defeat +## the under-root check. This matches the engine's own `res://` resolution and +## is accepted; the loopback trust boundary is the primary control. + + +# Cached project / user roots. `globalize_path` is stable across the editor's +# lifetime — caching avoids redundant resolution on every call. Matters most +# for `reimport`, which loops the validator over each path in a batch. +# Lazy-init on first call so static-load timing can't see a half-initialised +# ProjectSettings. +static var _cached_res_root: String = "" +static var _cached_user_root: String = "" + + +static func _res_root() -> String: + if _cached_res_root.is_empty(): + _cached_res_root = ProjectSettings.globalize_path("res://").simplify_path() + return _cached_res_root + + +static func _user_root() -> String: + if _cached_user_root.is_empty(): + _cached_user_root = ProjectSettings.globalize_path("user://").simplify_path() + return _cached_user_root + + +## True when `path` carries a codepoint that must never reach a filesystem API. +## +## Issue #889: the previous guard built its sentinel with `String.chr(0)`, and +## Godot emits `Unicode parsing error … Unexpected NUL character` while +## *constructing* that string. Every validated call — including reads that then +## failed with "File not found" — printed an alarming engine error that had +## nothing to do with the caller's path. Reading codepoints instead never +## materialises a NUL String, so the noise is gone. +## +## Both codepoints are rejected, for different reasons: +## * `0x0000` — a real embedded NUL can truncate a C string, so the path that +## is validated is not the path that gets opened. Current Godot cannot +## retain one in a String, making this a no-op today; it stays as +## defense-in-depth for any build or input path that can. +## * `0xFFFD` — what current Godot actually substitutes for a NUL or any other +## undecodable input. Once the engine has replaced the byte there is no way +## left to tell an attempted NUL from malformed UTF-8 from a literal +## replacement character, so the only safe reading at a security boundary is +## to refuse all three. A legitimate filename containing U+FFFD is rejected +## too; that false positive is deliberate and vanishingly rare. +static func _contains_invalid_path_codepoint(path: String) -> bool: + for i in path.length(): + var codepoint := path.unicode_at(i) + if codepoint == 0x0000 or codepoint == 0xFFFD: + return true + return false + + +## Returns "" when the path is a safe `res://`-rooted reference inside the +## project root. Returns a human-readable error message otherwise. +## Prefer `path_error` over calling this directly — it wraps the message in the +## canonical error code. +## +## Pass `for_write = true` for any handler that creates/overwrites the file +## (write_file, create_script, patch_script, ResourceSaver-backed saves, +## scene saves). Write callers additionally refuse the project manifest and +## startup override, plus the `.godot/` metadata dir. Reads default to +## `for_write = false`, which permits inspecting those files. +static func validate_resource_path(path: String, for_write: bool = false) -> String: + if path.is_empty(): + return "Missing required param: path" + if _contains_invalid_path_codepoint(path): + return "Path must not contain null bytes or invalid Unicode" + if not path.begins_with("res://"): + return "Path must start with res://" + var confine_err := _confine_under(path, _res_root(), "res://") + if not confine_err.is_empty(): + return confine_err + if for_write: + return _reject_sensitive_write(path) + return "" + + +## Returns "" when `path` is safe to hand to `ResourceLoader.load` / `.exists`. +## Accepts, in addition to confined `res://` paths: +## * `uid://` — an opaque 64-bit resource id; it cannot express a path +## and the engine only ever resolves it to a resource already in the +## project, so there is nothing to confine. +## * `user://…` — the per-project user data dir, confined under its root the +## same way `res://` is (so `user://../…` can't escape the sandbox). +static func validate_loadable_path(path: String) -> String: + if path.is_empty(): + return "Missing required param: path" + if _contains_invalid_path_codepoint(path): + return "Path must not contain null bytes or invalid Unicode" + if path.begins_with("uid://"): + return "" + if path.begins_with("user://"): + return _confine_under(path, _user_root(), "user://") + if path.begins_with("res://"): + return _confine_under(path, _res_root(), "res://") + return "Path must start with res://, uid://, or user://" + + +## Shared traversal + under-root containment. `root` must already be simplified. +static func _confine_under(path: String, root: String, label: String) -> String: + if ".." in path: + return "Path must not contain '..' (path traversal not allowed)" + var globalized := ProjectSettings.globalize_path(path).simplify_path() + # Append a separator so `/proj_evil/...` can't pretend to be inside `/proj` + # via prefix match. `globalized == root` covers the bare `res://` / `user://`. + if globalized != root and not globalized.begins_with(root + "/"): + return "Path must resolve under %s root" % label + return "" + + +## Refuse writes that would clobber project-critical files. The path is already +## confirmed `res://`-rooted and traversal-free by the caller. +## +## Comparisons are case-folded: macOS (APFS) and Windows (NTFS) are +## case-insensitive by default, so `res://Project.godot` resolves to the real +## `project.godot` and must be refused too. +## +## `.import` sidecars are deliberately NOT blocked — editing an asset's import +## options then re-importing is a legitimate, recoverable workflow (the file is +## source-controlled). The blocked set is the startup-execution surface only: +## the manifest, its `override.cfg` shadow, and the `.godot/` cache dir. +static func _reject_sensitive_write(path: String) -> String: + var file_lower := path.get_file().to_lower() + if file_lower == "project.godot": + return "Refusing to write res://project.godot (project manifest)" + if file_lower == "override.cfg": + return "Refusing to write res://override.cfg (startup config override)" + # Reject the `.godot/` editor-metadata dir at any depth. Split drops empty + # segments so a trailing slash can't hide a segment from the check. + var segments := path.trim_prefix("res://").split("/", false) + for segment in segments: + if segment.to_lower() == ".godot": + return "Refusing to write under res://.godot/ (editor metadata)" + # Reject the currently-loaded plugin's own script tree. Overwriting a + # loaded .gd here (plus the immediate reimport triggered by update_file()) + # can SIGABRT the editor mid-call, or silently corrupt the installed + # plugin so the next enable fails to resolve scripts. + if segments.size() >= 2 and segments[0].to_lower() == "addons" and segments[1].to_lower() == "godot_ai": + return "Refusing to write under res://addons/godot_ai/ (overwriting a loaded plugin script can crash the editor)" + return "" + + +## Validate a write/read `res://` path and return a ready error dict, or null +## when the path is fine. The single wrapper every handler should use so the +## error code (VALUE_OUT_OF_RANGE — a bad path is a value-domain error) stays +## consistent. `param_name` is prefixed onto the message for context. +static func path_error(path: String, param_name: String = "path", for_write: bool = false) -> Variant: + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: %s" % param_name) + var err := validate_resource_path(path, for_write) + if err.is_empty(): + return null + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "%s: %s" % [param_name, err]) + + +## Same as `path_error` but for paths handed to `ResourceLoader` (allows +## `uid://` / `user://`). Returns a ready error dict or null. An empty path is +## reported as MISSING_REQUIRED_PARAM rather than a value error. +static func loadable_error(path: String, param_name: String = "path") -> Variant: + if path.is_empty(): + return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: %s" % param_name) + var err := validate_loadable_path(path) + if err.is_empty(): + return null + return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "%s: %s" % [param_name, err]) diff --git a/addons/godot_ai/utils/path_validator.gd.uid b/addons/godot_ai/utils/path_validator.gd.uid new file mode 100644 index 0000000..8ed4acf --- /dev/null +++ b/addons/godot_ai/utils/path_validator.gd.uid @@ -0,0 +1 @@ +uid://blxntmd65ljyu diff --git a/addons/godot_ai/utils/port_resolver.gd b/addons/godot_ai/utils/port_resolver.gd new file mode 100644 index 0000000..789cfc6 --- /dev/null +++ b/addons/godot_ai/utils/port_resolver.gd @@ -0,0 +1,370 @@ +@tool +class_name McpPortResolver +extends RefCounted + +## Pure-static port discovery / OS-specific scrapers. No instance state, +## no editor dependencies. plugin.gd has thin instance shims that wrap +## these and increment the cold-start trace counters. + +## Canonical pid-file path. plugin.gd::SERVER_PID_FILE re-exports this so +## external readers and tests can use either name. +const SERVER_PID_FILE := "user://godot_ai_server.pid" +const WindowsPortReservation := preload("res://addons/godot_ai/utils/windows_port_reservation.gd") + + +static func can_bind_local_port(port: int) -> bool: + var server := TCPServer.new() + var err := server.listen(port, "127.0.0.1") + if err == OK: + server.stop() + return true + return false + + +## True when `port` is bound on 127.0.0.1. Probes via TCPServer first, +## falls back to OS scraping. Callers that want per-scraper trace +## counters should call `is_port_in_use_via_scrape` with a trace hook +## after their own `can_bind_local_port` probe. +static func is_port_in_use(port: int) -> bool: + if can_bind_local_port(port): + ## On POSIX, an IPv6 wildcard listener can coexist with a + ## successful 127.0.0.1 bind probe. Confirm with lsof so startup + ## sees the same listener set that shutdown/recovery would see. + if OS.get_name() != "Windows": + return is_port_in_use_via_scrape(port) + return false + return is_port_in_use_via_scrape(port) + + +## `trace` mirrors `find_all_pids_on_port`'s hook: one call per OS +## invocation with the counter name of the scraper that actually ran, so +## a wrapping caller's startup trace sees a genuine PowerShell fallback +## as `powershell`, not as a silent extra second under `netstat`. +static func is_port_in_use_via_scrape(port: int, trace: Callable = Callable()) -> bool: + var output: Array = [] + if OS.get_name() == "Windows": + _trace(trace, "netstat") + var exit_code := OS.execute("netstat", ["-ano"], output, true) + if exit_code == 0 and output.size() > 0: + var stdout := str(output[0]) + if parse_windows_netstat_listening(stdout, port): + return true + ## A healthy dump with no listener row IS the answer — don't + ## pay the ~1.2s powershell.exe spawn to confirm "not in use" + ## (see find_all_pids_on_port for the cost rationale). + if windows_netstat_dump_parseable(stdout): + return false + ## Fallback: netstat can be absent or unparseable on + ## stripped/locale-odd Windows installs. + _trace(trace, "powershell") + return not find_listener_pids_windows(port).is_empty() + _trace(trace, "lsof") + var exit_code := OS.execute("lsof", ["-ti:%d" % port, "-sTCP:LISTEN"], output, true) + return exit_code == 0 and output.size() > 0 and not output[0].strip_edges().is_empty() + + +## Return the PID currently listening on the given TCP port, or 0 if +## the port is free. Thin convenience wrapper around `find_all_pids_on_port` +## — the per-OS scraping logic lives in one place. +static func find_pid_on_port(port: int, trace: Callable = Callable()) -> int: + var pids := find_all_pids_on_port(port, trace) + return pids[0] if not pids.is_empty() else 0 + + +## Returns every PID bound LISTEN on `port`. Used by the kill paths so +## both the uvicorn reloader parent AND its worker child are caught when +## both bind the same port. +## +## `trace` is an optional Callable that fires once per OS invocation with +## a counter name (`"netstat"` / `"powershell"` / `"lsof"`) so the plugin +## can keep its cold-start trace accurate. The Windows path may fall +## through netstat → PowerShell, and a wrapping caller can't see which +## scraper actually ran without the hook. +static func find_all_pids_on_port(port: int, trace: Callable = Callable()) -> Array[int]: + if OS.get_name() == "Windows": + var output: Array = [] + _trace(trace, "netstat") + var exit_code := OS.execute("netstat", ["-ano"], output, true) + if exit_code == 0 and not output.is_empty(): + var stdout := str(output[0]) + var netstat_pids := parse_windows_netstat_pids(stdout, port) + if not netstat_pids.is_empty(): + return netstat_pids + ## An empty per-port parse from a healthy dump IS the answer + ## ("no listener"). Confirming it through the PowerShell probe + ## costs a powershell.exe spawn (~1.2s measured) against ~30ms + ## for the netstat scrape — two such confirmations dominated a + ## ~7s Windows startup walk. Only fall through when the dump + ## itself is unusable (netstat absent, or so format-odd that + ## zero TCP rows parse). + if windows_netstat_dump_parseable(stdout): + var no_listeners: Array[int] = [] + return no_listeners + _trace(trace, "powershell") + return find_listener_pids_windows(port) + var output: Array = [] + _trace(trace, "lsof") + var exit_code := OS.execute("lsof", ["-ti:%d" % port, "-sTCP:LISTEN"], output, true) + if exit_code != 0 or output.is_empty(): + var empty: Array[int] = [] + return empty + return parse_lsof_pids(str(output[0])) + + +static func _trace(trace: Callable, counter: String) -> void: + if trace.is_valid(): + trace.call(counter) + + +static func find_listener_pids_windows(port: int) -> Array[int]: + var script := ( + "Get-NetTCPConnection -LocalPort %d -State Listen " + + "-ErrorAction SilentlyContinue | " + + "Select-Object -ExpandProperty OwningProcess" + ) % port + var output: Array = [] + var exit_code := execute_windows_powershell(script, output) + return windows_listener_pids_from_execute_result(exit_code, output) + + +static func execute_windows_powershell(script: String, output: Array) -> int: + var args := ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", script] + for exe in windows_powershell_candidates(): + output.clear() + var exit_code := OS.execute(exe, args, output, true) + if exit_code == 0: + return exit_code + return -1 + + +static func windows_powershell_candidates() -> Array[String]: + var candidates: Array[String] = [] + var system_root := OS.get_environment("SystemRoot") + if system_root.is_empty(): + system_root = "C:/Windows" + system_root = system_root.replace("\\", "/").trim_suffix("/") + candidates.append(system_root + "/System32/WindowsPowerShell/v1.0/powershell.exe") + candidates.append("powershell.exe") + candidates.append("pwsh.exe") + return candidates + + +static func windows_listener_pids_from_execute_result(exit_code: int, output: Array) -> Array[int]: + var empty: Array[int] = [] + if exit_code == 0 and not output.is_empty(): + return parse_pid_lines(str(output[0])) + return empty + + +static func windows_listener_execute_result_in_use(exit_code: int, output: Array) -> bool: + return not windows_listener_pids_from_execute_result(exit_code, output).is_empty() + + +## Pure parser for `lsof -ti` output — newline-separated decimal PIDs. +## Empty lines and non-numeric tokens are dropped. Duplicates pass +## through (uvicorn reloader + worker can produce the same PID twice +## across runs but typically two distinct PIDs). +static func parse_lsof_pids(raw: String) -> Array[int]: + var pids: Array[int] = [] + for line in raw.strip_edges().split("\n", false): + var stripped := line.strip_edges() + if stripped.is_valid_int(): + pids.append(int(stripped)) + return pids + + +static func parse_pid_lines(raw: String) -> Array[int]: + var pids: Array[int] = [] + for line in raw.strip_edges().split("\n", false): + var stripped := line.strip_edges() + if stripped.is_valid_int(): + var pid := int(stripped) + if pid > 0 and not pids.has(pid): + pids.append(pid) + return pids + + +## Parse a Windows `netstat -ano` dump and return PIDs of rows whose +## local address ends with `:port` AND state is `LISTENING`. Substring +## matching the whole dump is wrong: a remote address containing +## `:port` would false-positive against an unrelated ESTABLISHED row. +static func parse_windows_netstat_pid(stdout: String, port: int) -> int: + var pids := parse_windows_netstat_pids(stdout, port) + return pids[0] if not pids.is_empty() else 0 + + +static func parse_windows_netstat_pids(stdout: String, port: int) -> Array[int]: + var pids: Array[int] = [] + var port_suffix := ":%d" % port + for line in stdout.split("\n"): + var s := line.strip_edges() + if s.is_empty(): + continue + var fields := split_on_whitespace(s) + if fields.size() < 5: # proto, local, remote, state, pid + continue + ## Locale-independent listener signal (mirrors script/_dev_env.py): + ## the state column is localized ("LISTENING"/"ABHÖREN"/"ÉCOUTE"...), + ## but a listener's FOREIGN address is always the wildcard ":0". + if not fields[2].ends_with(":0"): + continue + if not fields[1].ends_with(port_suffix): + continue + var pid_str := fields[fields.size() - 1] + if pid_str.is_valid_int(): + var pid := int(pid_str) + if pid > 0 and not pids.has(pid): + pids.append(pid) + return pids + + +static func parse_windows_netstat_listening(stdout: String, port: int) -> bool: + return parse_windows_netstat_pid(stdout, port) > 0 + + +## True when `stdout` looks like a healthy `netstat -ano` dump: at least +## one row parses as a TCP connection (proto column literally "TCP", an +## address containing ":", an integer PID in the last column). Locale- +## independent — protocol names are never localized, unlike the state +## column. Gates whether an empty per-port parse can be trusted as "no +## listener": a live Windows host always carries TCP rows (svchost/RPC +## listen on 135 at minimum), so a dump with zero parseable rows means +## netstat itself is absent/broken and the PowerShell fallback must run. +static func windows_netstat_dump_parseable(stdout: String) -> bool: + for line in stdout.split("\n"): + var fields := split_on_whitespace(line.strip_edges()) + if fields.size() < 5: + continue + if fields[0].to_upper() != "TCP": + continue + if fields[1].find(":") < 0: + continue + if fields[fields.size() - 1].is_valid_int(): + return true + return false + + +## `String.split(" ", false)` only splits on single spaces; netstat +## columns are separated by runs of spaces / tabs. Collapse manually. +static func split_on_whitespace(s: String) -> PackedStringArray: + var out: PackedStringArray = [] + var cur := "" + for i in s.length(): + var c := s.substr(i, 1) + if c == " " or c == "\t": + if not cur.is_empty(): + out.append(cur) + cur = "" + else: + cur += c + if not cur.is_empty(): + out.append(cur) + return out + + +static func read_pid_file() -> int: + if not FileAccess.file_exists(SERVER_PID_FILE): + return 0 + var f := FileAccess.open(SERVER_PID_FILE, FileAccess.READ) + if f == null: + return 0 + var content := f.get_as_text().strip_edges() + f.close() + if content.is_empty() or not content.is_valid_int(): + return 0 + var pid := int(content) + return pid if pid > 0 else 0 + + +static func clear_pid_file() -> void: + if FileAccess.file_exists(SERVER_PID_FILE): + DirAccess.remove_absolute(ProjectSettings.globalize_path(SERVER_PID_FILE)) + + +## `kill -0` returns 0 for both running and zombie processes; Godot +## never `waitpid`s on `OS.create_process` children, so a fast-failing +## uvx launcher lingers as a zombie forever and `kill -0` would block +## the spawn-failure branch in check_server_health from firing. Use +## `ps -o stat=` instead. State codes: R/S/D/I/T (live), Z (zombie). #172. +static func pid_alive(pid: int) -> bool: + if pid <= 0: + return false + if OS.get_name() == "Windows": + var output: Array = [] + var exit_code := OS.execute("tasklist", ["/FI", "PID eq %d" % pid, "/NH", "/FO", "CSV"], output, true) + if exit_code != 0 or output.is_empty(): + return false + for line in output: + if str(line).find("\"%d\"" % pid) >= 0: + return true + return false + var output: Array = [] + var exit_code := OS.execute("ps", ["-p", str(pid), "-o", "stat="], output, true) + if exit_code != 0 or output.is_empty(): + return false + var stat := str(output[0]).strip_edges() + return not stat.is_empty() and not stat.begins_with("Z") + + +## Poll until the given port is no longer bound, or the timeout elapses. +## Used after `OS.kill` so we don't race the port-in-use check on rebind. +## NOTE: plugin.gd::_wait_for_port_free (and _is_port_in_use) is a +## deliberate line-for-line fork of this pair kept for _ProofPlugin +## isolation — keep the two in sync when editing either. +static func wait_for_port_free(port: int, timeout_s: float) -> void: + var deadline := Time.get_ticks_msec() + int(timeout_s * 1000.0) + while is_port_in_use(port): + if Time.get_ticks_msec() >= deadline: + push_warning("MCP | port %d still in use after %.1fs — proceeding anyway" % [port, timeout_s]) + return + OS.delay_msec(100) + + +## Choose a non-Windows-reserved WS port. Returns `configured` when free; +## otherwise the first non-excluded port within `span` of it. Optional +## `log_buffer` is a duck-typed sink (`log(String)`) that gets the +## remap notice so users see why the port shifted. +static func resolve_ws_port(configured: int, max_port: int, log_buffer = null) -> int: + var resolved := WindowsPortReservation.suggest_non_excluded_port( + configured, + 2048, + max_port + ) + if resolved != configured: + var message := "WebSocket port %d is reserved by Windows; using %d" % [configured, resolved] + print("MCP | %s" % message) + if log_buffer != null: + log_buffer.log(message) + return resolved + + +## Trust the cached ws_port from the managed record only when the record +## is current ownership proof — i.e. record version matches the installed +## plugin. Otherwise a stale record from an older install (e.g. a 9500 +## value pre-Windows-reservation collision) would mislead the +## compatibility check into killing an unrelated external process. #259. +static func resolved_ws_port_for_existing_server( + record_ws_port: int, + record_version: String, + current_version: String, + fresh_resolved: int +) -> int: + if record_ws_port <= 0: + return fresh_resolved + if current_version.is_empty() or record_version != current_version: + return fresh_resolved + return record_ws_port + + +static func resolve_ws_port_from_output( + configured_port: int, + netsh_output: String, + max_port: int, + span: int = 2048 +) -> int: + return WindowsPortReservation.suggest_non_excluded_port_from_output( + netsh_output, + configured_port, + span, + max_port + ) diff --git a/addons/godot_ai/utils/port_resolver.gd.uid b/addons/godot_ai/utils/port_resolver.gd.uid new file mode 100644 index 0000000..54a3d73 --- /dev/null +++ b/addons/godot_ai/utils/port_resolver.gd.uid @@ -0,0 +1 @@ +uid://pk0212qfh61x diff --git a/addons/godot_ai/utils/resource_io.gd b/addons/godot_ai/utils/resource_io.gd new file mode 100644 index 0000000..cfac90f --- /dev/null +++ b/addons/godot_ai/utils/resource_io.gd @@ -0,0 +1,277 @@ +@tool +class_name McpResourceIO +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Shared helpers for "save a Resource to .tres" and the mutually-exclusive +## path-vs-resource_path param validation that every resource-authoring +## handler needs. Extracted to remove 4-way duplication across +## resource_handler, environment_handler, texture_handler, and curve_handler. +## Also home to the shared write-a-text-file path + deferred import-settle +## completion used by both script_handler.create_script and +## filesystem_handler.write_file (#714). + +# Bounded settle window for `ResourceLoader.exists(path)` after a fresh text +# write registers with the filesystem, so an agent calling +# create_script/write_file -> attach_script back-to-back doesn't race the +# editor's import pipeline (#261, extended to write_file by #714). Polled once +# per frame, with an elapsed-time cap below the dispatcher's deferred timeouts +# for both commands. If import is still not visible at the cap, we still +# return committed data instead of letting the already-written file surface +# as DEFERRED_TIMEOUT. +const IMPORT_SETTLE_MAX_FRAMES := 300 +const IMPORT_SETTLE_MAX_MSEC := 3500 + + +## Validate that exactly one of {path, resource_path} is provided. +## +## When `require_property` is true (default), also requires a non-empty +## `property` param when `path` is given — this matches the semantics of +## "assign a resource to node.property" (resource_create, texture tools, +## curve_set_points). Pass false for tools where the path itself IS the +## target (environment_create assigning to WorldEnvironment.environment). +## +## Returns null on success or an error dict on failure. +static func validate_home(params: Dictionary, require_property: bool = true) -> Variant: + var node_path: String = params.get("path", "") + var property: String = params.get("property", "") + var resource_path: String = params.get("resource_path", "") + var has_node_target := not node_path.is_empty() + var has_file_target := not resource_path.is_empty() + + if has_node_target and has_file_target: + var both_msg := "Provide either path+property or resource_path, not both" if require_property else "Provide either path or resource_path, not both" + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, both_msg) + if not has_node_target and not has_file_target: + var none_msg := "Must provide either path+property (assign inline) or resource_path (save .tres)" if require_property else "Must provide either path or resource_path" + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, none_msg) + if require_property and has_node_target and property.is_empty(): + return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Missing required param: property (required when path is given)") + return null + + +## Save `res` to `resource_path` as a .tres/.res file. +## +## Handles: res:// prefix validation, overwrite check, parent-directory +## creation, ResourceSaver.save error reporting, and the post-save +## EditorFileSystem.update_file() so the dock picks up the change. +## +## `label` is the human-readable resource-kind for error messages (e.g. +## "Environment", "Gradient texture", "Curve"). `extra_fields` is merged +## into the success response alongside the standard fields +## (`resource_path`, `overwritten`, `undoable: false`, `reason`). Passing +## a `reason` key in `extra_fields` overrides the default — useful for +## tools that edit existing files rather than creating fresh ones. +## +## `pause_target` should be the handler's `McpConnection`. When supplied, +## `pause_processing` is flipped on around `ResourceSaver.save()` so the +## dispatcher's WebSocket pump can't re-enter while Godot pumps +## `Main::iteration()` for the resource-save's progress UI / script-class +## update task. Without this guard a queued command landing during the +## save can trigger another `save_to_disk` that tries to add the same +## `update_scripts_classes` editor task — "Task already exists" → null +## deref → SIGSEGV. Same family of bug as godotengine/godot#118545 and +## the same mitigation as `SceneHandler`'s `save_scene*` wraps. See +## issue #288. +## +## Returns either an error dict or a {"data": {...}} success dict — ready +## for the handler to return directly. +static func save_to_disk( + res: Resource, + resource_path: String, + overwrite: bool, + label: String, + extra_fields: Dictionary = {}, + pause_target: McpConnection = null, +) -> Dictionary: + var path_err = McpPathValidator.path_error(resource_path, "resource_path", true) + if path_err != null: + return path_err + + var existed_before := FileAccess.file_exists(resource_path) + if existed_before and not overwrite: + return ErrorCodes.make( + ErrorCodes.INVALID_PARAMS, + "%s already exists at %s (pass overwrite=true to replace)" % [label, resource_path] + ) + # Captured BEFORE the overwrite below so a resave of an already-uid'd file + # (overwrite=true) can restore its own uid instead of losing it — see + # ensure_uid's doc comment. + var prior_uid := ResourceLoader.get_resource_uid(resource_path) if existed_before else ResourceUID.INVALID_ID + + var dir_path := resource_path.get_base_dir() + var mkdir_err := DirAccess.make_dir_recursive_absolute(dir_path) + if mkdir_err != OK and mkdir_err != ERR_ALREADY_EXISTS: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to create directory %s: %s" % [dir_path, error_string(mkdir_err)] + ) + + if pause_target != null: + pause_target.pause_processing = true + var save_err := ResourceSaver.save(res, resource_path) + if pause_target != null: + pause_target.pause_processing = false + if save_err != OK: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Failed to save %s to %s: %s" % [label, resource_path, error_string(save_err)] + ) + var uid_err := ensure_uid(resource_path, prior_uid) + if uid_err != OK: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "%s saved to %s but failed to write its uid: %s" % [label, resource_path, error_string(uid_err)] + ) + + var efs := EditorInterface.get_resource_filesystem() + if efs != null: + efs.update_file(resource_path) + + var data := { + "resource_path": resource_path, + "overwritten": existed_before, + "undoable": false, + "reason": "File creation is persistent; delete the file manually to revert", + } + attach_cleanup_hint(data, existed_before, [resource_path]) + # merge with overwrite=true so callers (e.g. curve_set_points editing an + # existing .tres) can supply a domain-specific `reason`. + data.merge(extra_fields, true) + return {"data": data} + + +## Save `res` to `resource_path` with the same `pause_processing` re-entrancy +## guard as `save_to_disk` (see its doc for the #288 SIGSEGV background), for +## call sites that need to pick their own error handling / overwrite policy +## instead of `save_to_disk`'s full validate+mkdir+overwrite-guard bundle +## (undo/redo callables reloading-mutating-resaving an existing resource, +## `apply_to_node`'s inline-then-save branch). Returns the raw +## `ResourceSaver.save` error code. +static func guarded_save(res: Resource, resource_path: String, pause_target: McpConnection) -> int: + var prior_uid := ResourceLoader.get_resource_uid(resource_path) if FileAccess.file_exists(resource_path) else ResourceUID.INVALID_ID + if pause_target != null: + pause_target.pause_processing = true + var save_err := ResourceSaver.save(res, resource_path) + if pause_target != null: + pause_target.pause_processing = false + if save_err != OK: + return save_err + return ensure_uid(resource_path, prior_uid) + + +## Make `resource_path` carry a stable uid after a successful +## `ResourceSaver.save()`, matching what Godot's own "New Scene"/"New +## Resource" editor flows always embed. A bare `ResourceSaver.save()` call +## does neither on its own: a brand-new file gets no `uid=` at all, and +## resaving a file that already had one silently drops it (#737). Call this +## immediately after every successful save. +## +## `prior_uid` is whatever `ResourceLoader.get_resource_uid(resource_path)` +## returned BEFORE this save overwrote the file (pass `ResourceUID.INVALID_ID` +## for a brand-new path). Reusing the prior id — instead of always minting a +## fresh one — keeps any `uid://...` references elsewhere in the project +## resolving to the same file. +## +## Returns the `Error` from `ResourceSaver.set_uid()` so callers can surface a +## uid-write failure instead of silently reporting success on a file that +## didn't end up with the uid it was supposed to get. +static func ensure_uid(resource_path: String, prior_uid: int) -> Error: + var id := prior_uid + if id == ResourceUID.INVALID_ID: + id = ResourceUID.create_id() + return ResourceSaver.set_uid(resource_path, id) + + +## Attach a `cleanup.rm` hint listing `paths` to `data` — only when the call +## just created a new file (`existed_before == false`). On overwrite the field +## is omitted because the caller already had the file on disk, and handing +## them a cleanup list would invite dropping user content instead of just +## scratch artifacts. Used by write-and-return handlers (create_script, +## filesystem_write_text, resource_create/save_to_disk) so callers running +## transient smoke tests can rm artifacts without tracking paths. See #82. +static func attach_cleanup_hint(data: Dictionary, existed_before: bool, paths: Array) -> void: + if existed_before: + return + data["cleanup"] = {"rm": paths} + + +## Shared write-a-text-file path (#714): parent-directory mkdir, write + +## flush with an explicit error check so a truncated write (disk full, +## permission flip mid-write) surfaces as an error instead of plain success. +## Deliberately does NOT call `EditorFileSystem.update_file()` — callers +## register the file themselves after assembling their response fields, so +## the registration comment (the dsarno/godot#6 scan-stacking rationale) +## stays next to the call. Returns null on success or an error dict ready +## to return from the handler. +static func write_text_to_disk(path: String, content: String) -> Variant: + var dir_path := path.get_base_dir() + if not DirAccess.dir_exists_absolute(dir_path): + var err := DirAccess.make_dir_recursive_absolute(dir_path) + if err != OK: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to create directory: %s" % dir_path) + + var file := FileAccess.open(path, FileAccess.WRITE) + if file == null: + return ErrorCodes.make(ErrorCodes.INTERNAL_ERROR, "Failed to open file for writing: %s" % path) + + file.store_string(content) + file.flush() + var write_err := file.get_error() + file.close() + if write_err != OK: + return ErrorCodes.make( + ErrorCodes.INTERNAL_ERROR, + "Write failed for %s (%s); file may be truncated" % [path, error_string(write_err)] + ) + return null + + +# `static` is load-bearing: the deferred completion captures no `self`, so the +# coroutine survives even if the calling handler RefCounted is freed mid-await. +# Under concurrent create storms with editor_reload_plugin fired during the +# burst, an instance-method coroutine is otherwise GC'd between `await` and +# resume, producing "Resumed function ... after await, but class instance is +# gone" errors and dropping the response. Keep this function static and +# parameterise everything it needs explicitly — do not reference instance +# state. Shared by create_script and write_file's fresh-`.gd` path (#714). +static func finish_text_write_deferred( + connection: McpConnection, + request_id: String, + path: String, + data: Dictionary, +) -> void: + if not is_instance_valid(connection): + return + var tree := connection.get_tree() + if tree == null: + return + var deadline_ms := Time.get_ticks_msec() + IMPORT_SETTLE_MAX_MSEC + # Let _dispatch() return DEFERRED_RESPONSE and register the request before + # this coroutine can send a committed result. ResourceLoader.exists(path) + # may already be true on fast imports; without this handoff the connection + # treats the response as late/unregistered and drops it, then the dispatcher + # times out a file that was already written (#324). The deadline starts + # before this await so a slow handoff frame is counted against the bounded + # settle window. + await tree.process_frame + var frames := 0 + while ( + frames < IMPORT_SETTLE_MAX_FRAMES + and Time.get_ticks_msec() < deadline_ms + and not ResourceLoader.exists(path) + ): + await tree.process_frame + frames += 1 + # If the plugin tears down (_exit_tree frees the connection) during the + # await, is_instance_valid() goes false and we drop the response silently — + # the server's request timeout will surface the failure to the caller. + if not is_instance_valid(connection): + return + var payload := data.duplicate() + var settled := ResourceLoader.exists(path) + payload["import_settled"] = settled + payload["import_settle"] = "settled" if settled else "timeout" + payload["import_pending"] = not settled + connection.send_deferred_response(request_id, {"data": payload}) diff --git a/addons/godot_ai/utils/resource_io.gd.uid b/addons/godot_ai/utils/resource_io.gd.uid new file mode 100644 index 0000000..94da4c9 --- /dev/null +++ b/addons/godot_ai/utils/resource_io.gd.uid @@ -0,0 +1 @@ +uid://de2rwdoa4wabf diff --git a/addons/godot_ai/utils/scene_path.gd b/addons/godot_ai/utils/scene_path.gd new file mode 100644 index 0000000..782aea1 --- /dev/null +++ b/addons/godot_ai/utils/scene_path.gd @@ -0,0 +1,155 @@ +@tool +class_name McpScenePath +extends RefCounted + +const ErrorCodes := preload("res://addons/godot_ai/utils/error_codes.gd") + +## Utility for converting between Godot internal node paths and clean +## scene-relative paths like /Main/Camera3D. + + +## Return a clean path relative to the scene root (e.g. /Main/Camera3D). +## Returns "" when `node` is not the scene root or a descendant of it — +## without the ancestry guard, get_path_to() returns an empty NodePath that +## concatenates into a plausible-looking but invalid "/Main/". +static func from_node(node: Node, scene_root: Node) -> String: + if scene_root == null or node == null: + return "" + if node == scene_root: + return "/" + scene_root.name + if not scene_root.is_ancestor_of(node): + return "" + var relative := scene_root.get_path_to(node) + return "/" + scene_root.name + "/" + str(relative) + + +## Resolve a clean scene path like "/Main/Camera3D" to the actual node. +## +## Accepts forms relative to the edited scene root: +## "/Main" — explicit root prefix (canonical) +## "/Main/Camera3D" — descendant path +## "Camera3D" — bare relative to scene_root +## "World/Ground" — nested bare relative to scene_root +## +## Also accepts SceneTree-style "/root/[/...]" as an alias for +## the edited scene root. Agents reach for /root/Foo right after creating a +## scene because that's where scenes live at runtime; we honor it so the call +## doesn't fail with a confusing "not found" error. The alias only kicks in +## when the segment after /root matches the scene root's name — paths like +## "/root/@EditorNode@.../Main/..." (returned by Node.get_path() in the editor) +## fall through to the absolute-path fallback unchanged. +static func resolve(scene_path: String, scene_root: Node) -> Node: + if scene_root == null: + return null + + ## Bare "/" alias: the most natural first guess for "the scene root". + ## There is exactly one edited-scene root, so the alias is unambiguous; + ## without it, "/" falls through to get_node_or_null("/") → null and + ## every call costs the agent a NODE_NOT_FOUND round trip (issue #624). + if scene_path == "/": + return scene_root + + ## /root/[/...] alias: strip the /root prefix and recurse. + ## Match the scene root by name explicitly so we don't capture editor- + ## internal paths that legitimately live under /root. + var alias_prefix := "/root/" + scene_root.name + if scene_path == alias_prefix or scene_path.begins_with(alias_prefix + "/"): + return resolve(scene_path.substr(5), scene_root) # keep leading slash + + var root_prefix := "/" + scene_root.name + if scene_path == root_prefix: + return scene_root + if scene_path.begins_with(root_prefix + "/"): + var relative := scene_path.substr(root_prefix.length() + 1) + return scene_root.get_node_or_null(relative) + + # Try as-is (relative path, or absolute SceneTree path). + return scene_root.get_node_or_null(scene_path) + + +## Return the edited scene root, or an error dict if the editor has no open +## scene or the open scene doesn't match `expected_scene_file`. +## +## `expected_scene_file` is the caller's `scene_file` parameter — an empty +## string means "target whatever is currently edited" (current behaviour, +## no guard). A non-empty value must match `scene_file_path` on the current +## edited scene root exactly, or we return EDITED_SCENE_MISMATCH so the +## caller can re-open the right scene. +## +## Shape on success: {"node": }. Shape on error matches +## `ErrorCodes.make()` so callers can propagate the result directly. +static func require_edited_scene(expected_scene_file: String) -> Dictionary: + var root := EditorInterface.get_edited_scene_root() + if root == null: + # Mirrors the structured payload that the Python-side require_writable + # gate attaches for `playing` / `importing`. Together these cover the + # three recoverable editor *states* (playing / importing / no_scene) + # — the EDITOR_NOT_READY paths an AI caller can act on. Other + # EDITOR_NOT_READY callsites describing internal-state failures + # ("EditorFileSystem not available" etc.) carry sub_code + retryable + # via ErrorCodes.make_not_ready (#651 stage 1) but intentionally + # omit the hint — there's no useful caller action to name. + var err := ErrorCodes.make(ErrorCodes.EDITOR_NOT_READY, "No scene open") + err["error"]["data"] = { + "sub_code": ErrorCodes.SUB_EDITOR_NO_SCENE, + "editor_state": "no_scene", + "retryable": false, + "hint": ( + "No scene is open. Call scene_open with a scene path " + + "(e.g. \"res://main.tscn\") before issuing scene-mutating tools." + ), + } + return err + if not expected_scene_file.is_empty() and root.scene_file_path != expected_scene_file: + var actual := root.scene_file_path if not root.scene_file_path.is_empty() else "" + return ErrorCodes.make( + ErrorCodes.EDITED_SCENE_MISMATCH, + ( + "Expected edited scene \"%s\" but \"%s\" is active. " + + "Call scene_open(\"%s\") first, or omit scene_file to target the active scene." + ) % [expected_scene_file, actual, expected_scene_file], + ) + return {"node": root} + + +## Format a "parent not found" error that names the path convention. +## Agents routinely try /root/Foo or absolute SceneTree paths; the bare +## "Parent not found: X" gave them no hint that paths are scene-relative. +## Wording is generic ("Paths are relative...") so the helper works for any +## param name (parent_path, new_parent, …). +static func format_parent_error(path: String, scene_root: Node) -> String: + if scene_root == null: + return "Parent not found: %s. No edited scene is open." % path + var root_name := str(scene_root.name) + return "Parent not found: %s. Paths are relative to the edited scene root (e.g. \"/%s\" or \"\"), not the SceneTree. Scene root is \"/%s\"." % [path, root_name, root_name] + + +## Format a "node not found" error that names the path convention and, when +## possible, suggests a corrected path. Agents routinely pass /root/Foo +## (runtime SceneTree) or unprefixed names; the bare "Node not found: X" +## gives no hint that paths are edited-scene-relative. +## +## Suggestion logic (highest-confidence first): +## 1. /root/[/...] where is not the scene root → suggest //[/...] +## 2. path doesn't start with "/" → suggest "//" +## 3. otherwise no concrete "did you mean", just the convention reminder. +static func format_node_error(path: String, scene_root: Node) -> String: + if scene_root == null: + return "Node not found: %s. No edited scene is open." % path + var root_name := str(scene_root.name) + var suggestion := "" + + if path.begins_with("/root/"): + var after_root := path.substr(6) # "/root/" is 6 chars + # Only suggest if the segment after /root/ isn't already the scene root + # (resolve() handles /root//... as an alias, so a failure + # with that prefix means a deeper segment is wrong — no clean rewrite). + var first_seg := after_root.split("/")[0] + if first_seg != root_name and not first_seg.is_empty(): + suggestion = "/" + root_name + "/" + after_root + elif not path.begins_with("/") and not path.is_empty(): + suggestion = "/" + root_name + "/" + path + + if suggestion.is_empty(): + return "Node not found: %s. Paths are relative to the edited scene root (e.g. \"/%s/Child\"), not runtime /root/... paths. Scene root is \"/%s\"." % [path, root_name, root_name] + return "Node not found: %s. Did you mean \"%s\"? Paths are relative to the edited scene root, not runtime /root/... paths. Scene root is \"/%s\"." % [path, suggestion, root_name] diff --git a/addons/godot_ai/utils/scene_path.gd.uid b/addons/godot_ai/utils/scene_path.gd.uid new file mode 100644 index 0000000..85795a9 --- /dev/null +++ b/addons/godot_ai/utils/scene_path.gd.uid @@ -0,0 +1 @@ +uid://c1irdrss0amex diff --git a/addons/godot_ai/utils/screenshot_encode.gd b/addons/godot_ai/utils/screenshot_encode.gd new file mode 100644 index 0000000..e3b0210 --- /dev/null +++ b/addons/godot_ai/utils/screenshot_encode.gd @@ -0,0 +1,38 @@ +@tool +class_name McpScreenshotEncode +extends RefCounted + +## Shared downscale + PNG + base64 block for the screenshot paths (#716). +## +## Two call sites straddle the editor/game process boundary — the editor's +## take_screenshot (editor_handler) and the game-process autoload +## (runtime/game_helper) — and were maintained as manually synchronized +## copies. Pure static, no editor APIs, so it loads safely in the game +## process too. + + +## Downscale `image` in place so its longest edge is at most +## `max_resolution` (0 = no cap), then PNG-encode. Returns +## {base64, width, height, original_width, original_height}. +static func downscale_and_encode(image: Image, max_resolution: int) -> Dictionary: + var original_width := image.get_width() + var original_height := image.get_height() + + if max_resolution > 0: + var longest := maxi(original_width, original_height) + if longest > max_resolution: + var scale := float(max_resolution) / float(longest) + ## Clamp to 1px min: extreme aspect ratios at very small + ## max_resolution could otherwise compute a zero dimension and + ## crash image.resize(). + var new_w := maxi(1, int(original_width * scale)) + var new_h := maxi(1, int(original_height * scale)) + image.resize(new_w, new_h, Image.INTERPOLATE_LANCZOS) + + return { + "base64": Marshalls.raw_to_base64(image.save_png_to_buffer()), + "width": image.get_width(), + "height": image.get_height(), + "original_width": original_width, + "original_height": original_height, + } diff --git a/addons/godot_ai/utils/screenshot_encode.gd.uid b/addons/godot_ai/utils/screenshot_encode.gd.uid new file mode 100644 index 0000000..0bcdac2 --- /dev/null +++ b/addons/godot_ai/utils/screenshot_encode.gd.uid @@ -0,0 +1 @@ +uid://cl0xhoxwsbmow diff --git a/addons/godot_ai/utils/server_lifecycle.gd b/addons/godot_ai/utils/server_lifecycle.gd new file mode 100644 index 0000000..2abc497 --- /dev/null +++ b/addons/godot_ai/utils/server_lifecycle.gd @@ -0,0 +1,2197 @@ +@tool +class_name McpServerLifecycleManager +extends RefCounted + +## Server spawn / stop / respawn / adopt / recover orchestration plus the +## update-reload handoff. Owns the server-state machine +## (`McpServerState`), version-check seam (`McpServerVersionCheck`), +## adoption metadata, and connection-blocked / dev-mismatch flags. +## +## State previously lived on plugin.gd; PR 6 (#297) moved it here so +## PR 7 (UpdateManager extraction) can absorb the same encapsulation +## pattern. The plugin still owns the physical editor surfaces +## (Connection, Dock, Timer, EditorSettings I/O) and exposes them via +## `_host.()` shims; the test fixtures override those shims to +## drive the manager without touching the editor. +## +## `_host` is untyped to honor the self-update field-storage policy +## plugin.gd calls out near `_connection`. +var _host + +const UvCacheCleanup := preload("res://addons/godot_ai/utils/uv_cache_cleanup.gd") +const ClientConfigurator := preload("res://addons/godot_ai/client_configurator.gd") +const PortResolver := preload("res://addons/godot_ai/utils/port_resolver.gd") +const WindowsPortReservation := preload("res://addons/godot_ai/utils/windows_port_reservation.gd") +const McpServerStateScript := preload("res://addons/godot_ai/utils/mcp_server_state.gd") +const McpStartupPathScript := preload("res://addons/godot_ai/utils/mcp_startup_path.gd") +const McpAdoptionLabelScript := preload("res://addons/godot_ai/utils/mcp_adoption_label.gd") +const McpServerVersionCheckScript := preload("res://addons/godot_ai/utils/server_version_check.gd") + +# ---- State (owned here, was on plugin.gd through PR 5) --------------- + +## Single source of truth for the server-spawn/adopt/version lifecycle. +## See `McpServerState` for the transition table. +var _server_state: int = McpServerStateScript.UNINITIALIZED + +## OS-level state populated only when WE spawned the process. +var _server_pid: int = -1 +## keep_server_on_exit (#800): whether the RUNNING server was launched with +## the keep-alive env opt-outs (no owner pid, NO_IDLE_EXIT staged). Editor +## teardown routes on this, never on the live setting — a server spawned +## without the opt-outs must die with the editor even if the user enabled +## the setting mid-session, or the owner-PID watchdog reaps it seconds +## later and the preserved record goes stale (the #774 scenario). Set at +## spawn, recovered from the managed-server record on adoption. +var _server_keep_alive := false +var _server_spawn_ms: int = 0 +var _server_exit_ms: int = 0 +## Elapsed-since-spawn when the pid-file first appeared. The warm watch window +## starts here, not at process creation: a cold uvx download may consume most +## of the cold-start budget before Python starts and publishes the file. +var _server_pid_published_elapsed_ms: int = 0 +## Elapsed-since-spawn at the first watch tick that saw the spawn PID dead, or +## 0 when it is alive / has been healed onto the real PID. Only meaningful +## while a Windows trampoline handoff is being waited out (#797): it preserves +## the true exit time so a diagnosis raised after the wait still reports when +## the process actually died. Reset per spawn alongside `_server_spawn_ms`. +var _spawn_dead_since_ms: int = 0 + +## Version metadata. `expected_version` is what the plugin shipped with; +## `actual_version` is what the live server reported via handshake_ack. +var _server_expected_version: String = "" +var _server_actual_version: String = "" +var _server_actual_name: String = "" + +## Diagnostic + recovery flags surfaced to the dock via `get_status()`. +var _server_status_message: String = "" +## #647: when a post-crash probe pins the failure on a specific port held +## by a foreign process, this names that port (HTTP or WS) so the dock's +## status line and port-picker gating don't blame the wrong one. Zero when +## no conflict was diagnosed. +var _conflict_port: int = 0 +var _can_recover_incompatible: bool = false +var _connection_blocked: bool = false + +## One-shot guard for the stale-uvx-index recovery (#172). Reset at the +## top of `start_server` so each fresh spawn attempt gets its own +## refresh budget. +var _refresh_retried: bool = false + +## One-shot guard for the spawn-lost-port-race re-adoption (see +## `_diagnose_spawn_fast_exit`). #805: the budget is per RECOVERY, not per +## walk — a walk the re-adopt arm itself triggered must NOT refresh it +## (`_readopt_walk_pending` skips the top-of-walk reset), or a flapping +## godot-ai occupant sustains spawn → fast-exit → re-walk forever. The +## budget refreshes on the paths that prove recovery: a fresh +## user/plugin-initiated walk, a successful `adopt_compatible_server`, +## or a spawn that survives to publish its pid-file. +var _readopt_after_spawn_exit_retried: bool = false + +## #805: set by the re-adopt arm just before it re-runs `start_server`, +## consumed by the top of `_start_server_impl` to skip that walk's +## `_readopt_after_spawn_exit_retried` reset. Never true outside that +## one triggered walk. +var _readopt_walk_pending: bool = false + +## Rounds of weak-proof (`status_name`-tier) recovery available against a +## brand-verified stale-VERSION godot-ai occupant. Zero by default: the +## startup walk may only kill via strong ownership proof. Armed by an +## explicit user action that already authorizes replacing the old backend — +## the post-self-update startup (`authorize_stale_recovery` from plugin.gd, +## consented by the Update click) and the dock's recovery click. This is +## what lets the walk finish an update against an attach-bridge-owned old +## server: bridges pinned to the previous version respawn it the moment it +## is killed, and each respawn is an external server with no strong proof, +## so without this budget every lost port race dead-ends in INCOMPATIBLE +## and the user is left toggling the plugin by hand. Never spent on a +## same-version or foreign occupant; each spent round re-proves brand at +## kill time. Reset on the proven recoveries — adoption and the verified +## compatible handshake — so leftover rounds can't authorize a kill in a +## later, unrelated episode. Pid-file publication deliberately does NOT +## reset it: the server writes that file before binding either port, so a +## bridge respawn can still steal the bind afterwards and the fast-exit +## needs its remaining rounds (#890 review P1). +var _stale_recovery_budget: int = 0 + +## Single owner for kill/drain/respawn recovery. Startup probing and the +## WebSocket version verdict observe the same backend from different async +## paths; a retry budget bounds how often they may act, but does not stop both +## paths acting at once. Keep one recovery transaction in flight and coalesce +## stale handshake verdicts into it so an older continuation cannot kill the +## fresh server that another continuation just spawned. +var _recovery_in_flight: bool = false +## Generation-scoped capability for the startup walk spawned by +## `_recover_incompatible_server_impl`. The outer recovery keeps +## `_recovery_in_flight` armed so handshakes and unrelated recovery calls still +## coalesce, while this token lets only that exact owned walk spend another +## bounded stale-recovery round if an attach bridge reclaims the port after the +## kill. A later walk created by invalidation gets a different generation and +## cannot inherit the authority. +var _recovery_owned_startup_generation: int = -1 + +## Bounded deadline for the foreign-port adoption-confirmation watcher. +## Zero when disarmed. +var _adoption_watch_deadline_ms: int = 0 + +## Branch-tag from the most recent `start_server` walk. See +## `McpStartupPath`. Drives the startup-trace log. +var _startup_path: String = McpStartupPathScript.UNSET + +## Version-check seam. Lazily constructed on `arm_version_check` so +## tests that exercise the manager without a connection don't have to +## stub it out. +var _version_check + +## #678: when true, the blocking primitives on the startup path (port +## scrapes, per-PID brand shells, the HTTP status probe, kill + port-drain +## waits) run on a WorkerThreadPool thread while the main thread keeps +## pumping frames — the editor stays responsive during plugin init/reload +## on a contended port; the dock panel just arrives a beat later. The +## plugin enables this in production. Default false: unit tests (and any +## legacy caller) keep the historical fully-synchronous behavior, where +## the startup coroutines never actually suspend and call-then-assert +## still works. +var defer_blocking_work: bool = false + +## Cancellation for in-flight async startup work: bumped by `stop_server` +## (and therefore by `_exit_tree` and update-reload prep), checked after +## every await so a suspended `start_server` can't resurrect state — or +## spawn a server — after teardown started. +var _async_generation: int = 0 + +## Re-entrancy guard: with startup a coroutine, a second `start_server` +## call (respawn watch, dock button) can land mid-flight. +var _start_in_flight: bool = false + + +func _init(host) -> void: + _host = host + + +## The worker thread of the walk's current `_run_blocking` call, while it +## runs. `_invalidate_async_startup` JOINS it (bounded by the blocking +## op's own timeout) so no worker can still be executing a plugin method +## when `_exit_tree` frees the plugin — a mid-call free is use-after-free +## on the worker, which wedged the editor on macOS during rapid reload +## churn (main CI, post-#682). Null when no blocking work is in flight. +var _active_blocking_thread: Thread = null + + +## Run `work` off the main thread and suspend until it completes (#678). +## Falls back to inline execution when `defer_blocking_work` is off, or +## when no SceneTree is available to pump frames against. +## +## Uses a dedicated Thread (the dock's #238/#239 worker pattern) rather +## than WorkerThreadPool: `wait_to_finish()` hands the return value back +## without a shared mutable container, and this plugin has already seen +## WorkerThreadPool tasks SIGABRT under concurrency (see the notes in +## script_handler.gd / filesystem_handler.gd). `wait_to_finish` after +## `is_alive()` goes false joins an already-dead thread, so it never +## blocks the main thread. +## +## Returns null (without joining) when `_invalidate_async_startup` took +## ownership of the thread mid-flight — the walk is stale at that point +## and must bail. Callers therefore assign the result to an untyped +## local and bail on `_async_stale(...) or result == null` BEFORE any +## typed use — a typed assignment (or a bool()/int() constructor, both +## of which have no Nil form) trips on the null first. The null check is +## not redundant with the generation check: a caller that loses the slot +## without a generation bump — an invariant violation, but exactly what +## a concurrent fire-and-forget `_run_blocking` user produces — must +## still unwind instead of crashing on the Nil. +func _run_blocking(work: Callable) -> Variant: + if not defer_blocking_work: + return work.call() + var tree := Engine.get_main_loop() + if not (tree is SceneTree): + return work.call() + var thread := Thread.new() + if thread.start(work) != OK: + return work.call() + _active_blocking_thread = thread + while thread.is_alive(): + await (tree as SceneTree).process_frame + if _active_blocking_thread != thread: + ## Teardown/invalidation already joined this thread; the + ## result belongs to a cancelled walk. All resumes and joins + ## happen on the main thread, so this check cannot race. + return null + if _active_blocking_thread != thread: + return null + _active_blocking_thread = null + return thread.wait_to_finish() + + +func _async_stale(generation: int) -> bool: + return generation != _async_generation + + +## Cancel any in-flight async startup walk AND release the re-entrancy +## guard so the very next `start_server()` call walks fresh (#682 review). +## Every one-shot kill-and-restart path must call this before its +## follow-up start: without the generation bump the suspended walk +## resumes against post-kill reality (stale live-status snapshots), and +## without releasing the guard the follow-up start is silently swallowed. +## The cancelled walk unwinds via its post-await staleness checks and +## must NOT clear the guard itself — a newer walk may already own it +## (see the generation check in `start_server`). +## +## Also JOINS the walk's in-flight worker thread (bounded by that op's +## own timeout: lsof/netstat scrape, ≤800ms status probe, or kill + +## port-drain wait). `stop_server` runs this from `_exit_tree`, so once +## it returns no worker thread can still be executing a method of the +## plugin that is about to be freed — the macOS reload-churn wedge. +func _invalidate_async_startup() -> void: + _async_generation += 1 + _start_in_flight = false + var thread := _active_blocking_thread + _active_blocking_thread = null + if thread != null: + thread.wait_to_finish() + + +# ---- Public state accessors -------------------------------------------- + +func get_state() -> int: + return _server_state + + +func get_status_dict() -> Dictionary: + return { + "state": _server_state, + "exit_ms": _server_exit_ms, + "actual_name": _server_actual_name, + "actual_version": _server_actual_version, + "expected_version": _server_expected_version, + "message": _server_status_message, + "can_recover_incompatible": _can_recover_incompatible, + "connection_blocked": _connection_blocked, + "conflict_port": _conflict_port, + "keep_alive": _server_keep_alive, + "stale_recovery_budget": _stale_recovery_budget, + } + + +## Arm the bounded stale-occupant recovery (see `_stale_recovery_budget`). +## Called before the startup walk when a completed self-update is detected +## (plugin.gd) and by the dock recovery click — both are user actions that +## already authorize replacing the previous-version backend. `max()` so a +## click landing on an already-armed post-update episode never shrinks the +## remaining rounds. +func authorize_stale_recovery(rounds: int = 2) -> void: + _stale_recovery_budget = maxi(_stale_recovery_budget, rounds) + + +## True when a spent round of stale-occupant recovery may target the live +## occupant: budget remains and the occupant is a VERIFIED godot-ai whose +## version differs from ours. An empty version (foreign or unverified +## occupant) never qualifies — those stay on the strong-proof-only path. +func _stale_recovery_available(live_version: String, expected_version: String) -> bool: + if _stale_recovery_budget <= 0: + return false + if live_version.is_empty(): + return false + return live_version != expected_version + + +func get_server_pid() -> int: + return _server_pid + + +func get_startup_path() -> String: + return _startup_path + + +func get_adoption_watch_deadline_ms() -> int: + return _adoption_watch_deadline_ms + + +func is_awaiting_server_version() -> bool: + return _version_check != null and _version_check.is_active() + + +func is_connection_blocked() -> bool: + return _connection_blocked + + +# ---- State-machine entry points --------------------------------------- + +## Validated transition. Returns true on success; false (and logs a +## warning) when the transition is illegal under `McpServerState`'s +## table. Callers that need first-writer-wins among terminal diagnoses +## use `set_terminal_diagnosis` instead — that helper silently no-ops +## without warning when the diagnosis would be a regression. +func transition_state(target: int) -> bool: + if _server_state == target: + return true + if not McpServerStateScript.can_transition(_server_state, target): + push_warning( + "MCP | rejected illegal state transition %s -> %s" + % [ + McpServerStateScript.name_of(_server_state), + McpServerStateScript.name_of(target), + ] + ) + return false + _server_state = target + return true + + +## First-writer-wins mutator for terminal diagnoses (CRASHED, +## NO_COMMAND, PORT_EXCLUDED, INCOMPATIBLE, FOREIGN_PORT). Used during +## spawn to make sure a late watch-loop CRASHED doesn't clobber an +## earlier proactive PORT_EXCLUDED. Silent no-op when the current state +## is already a terminal diagnosis — the existing diagnosis is kept. +func set_terminal_diagnosis(target: int) -> bool: + if not McpServerStateScript.is_terminal_diagnosis(target): + push_warning( + "MCP | set_terminal_diagnosis called with non-terminal %s" + % McpServerStateScript.name_of(target) + ) + return false + if McpServerStateScript.is_terminal_diagnosis(_server_state): + return false + _server_state = target + return true + + +# ---- Adoption confirmation watcher ------------------------------------- + +## Arm the FOREIGN_PORT adoption-confirmation watcher. SPAWN_GRACE_MS +## ahead of `now`; `tick_adoption_watch` self-disarms after this expires +## so per-frame cost drops back to zero on a permanent foreign occupant. +func arm_adoption_watch() -> void: + _adoption_watch_deadline_ms = ( + Time.get_ticks_msec() + int(_host.SPAWN_GRACE_MS) + ) + + +func tick_adoption_watch(now_msec: int) -> void: + if _adoption_watch_deadline_ms > 0 and now_msec >= _adoption_watch_deadline_ms: + _adoption_watch_deadline_ms = 0 + + +# ---- Server version-check seam ---------------------------------------- + +func arm_version_check(connection, expected_version: String) -> void: + if _version_check == null: + _version_check = McpServerVersionCheckScript.new(self) + var expected := _resolve_expected_version(expected_version) + _server_expected_version = expected + _version_check.arm(connection, expected) + + +func disarm_version_check() -> void: + if _version_check != null: + _version_check.disarm() + + +func get_version_check(): + return _version_check + + +## Resolves a possibly-empty expected version to the plugin's shipping +## version. Manager methods that are called via test fixtures may +## receive an empty string when the test never seeded +## `_server_expected_version`, so this is the one place that fallback +## lives. +func _resolve_expected_version(supplied: String) -> String: + if not supplied.is_empty(): + return supplied + return _expected_server_version() + + +func _expected_server_version() -> String: + return ClientConfigurator.get_plugin_version() + + +## Called by McpServerVersionCheck when handshake_ack carries a version +## string. Decides compatible vs incompatible and transitions the state. +func handle_server_version_verified(expected_version: String, version: String) -> void: + _server_actual_name = "godot-ai" + _server_actual_version = version + var expected := _resolve_expected_version(expected_version) + _server_expected_version = expected + var compatibility := _server_version_compatibility(version, expected) + if compatibility.get("compatible", false): + _can_recover_incompatible = false + ## A verified compatible handshake ends any stale-recovery episode — + ## leftover authorized rounds must not survive into a later walk. + _stale_recovery_budget = 0 + ## Foreign-port and post-spawn handshakes both clear to READY + ## on a successful handshake. Late re-arms from READY also land + ## here and self-confirm. + transition_state(McpServerStateScript.READY) + _host._update_process_enabled() + return + ## A stale handshake is expected while the startup/recovery owner is already + ## replacing that exact old backend. Do not let the connection-side verdict + ## invalidate the startup walk and launch a second kill transaction. The + ## active owner re-probes the listener before acting and will either replace + ## it or leave the normal incompatible diagnosis on failure. + if _recovery_in_flight and version != expected: + print("MCP | stale godot-ai v%s handshake coalesced into active recovery" % version) + return + var live := {"version": version, "status_code": 200, "name": "godot-ai"} + ## Connection propagation + version-check disarm + process re-evaluation + ## all live inside _set_incompatible_server now (#691) so the startup-walk + ## recovery-failure and force-restart-failure paths get them too. + _set_incompatible_server(live, expected, ClientConfigurator.http_port()) + ## Post-update the WebSocket usually reaches the OLD backend before the + ## startup walk finishes its probes — this verdict then cancels the walk + ## (the `_invalidate_async_startup` in `_set_incompatible_server`'s + ## fire-and-forget arm) and used to strand the update at INCOMPATIBLE + ## even though the Update click already authorized replacing that + ## backend. With authorized rounds left and a VERIFIED stale version, + ## spend one and fire the same recovery flow the dock's Restart click + ## runs — via the plugin wrapper so the connection unblocks on success, + ## with `user_initiated=false` so the trigger can only spend, never + ## re-arm. The INCOMPATIBLE latch it gates on is synchronous: the + ## `_set_incompatible_server` head above runs before its first await. + if _stale_recovery_available(version, expected) and _host.has_method("recover_incompatible_server"): + _stale_recovery_budget -= 1 + print( + "MCP | stale godot-ai v%s answered the WS handshake — replacing it (update/recovery authorized, %d retry round(s) left)" + % [version, _stale_recovery_budget] + ) + ## Fire-and-forget coroutine: this verdict lands on the main thread + ## from `_process`, and the recovery owns the flow from here + ## (mirroring the recovery click). + _host.recover_incompatible_server(false, version) + + +func handle_server_version_unverified(expected_version: String) -> void: + var expected := _resolve_expected_version(expected_version) + _server_expected_version = expected + var live := {"version": "", "status_code": 0, "error": "missing_handshake_ack"} + _set_incompatible_server(live, expected, ClientConfigurator.http_port()) + + +# ---- Compatibility / version helpers (pure) --------------------------- + +## Plugin and server speak a single, version-coupled protocol — new commands +## and response fields are added together. Treating dev-mode mismatches as +## "compatible" silently adopts a stale server whose code may differ from the +## live source tree (e.g. another worktree on a different branch holding +## port 8000). Strict match in all modes routes mismatches through +## `recover_strong_port_occupant`, which kills the branded port-holder and +## lets `start_server` spawn fresh against the current source. +static func _server_version_compatibility( + actual_version: String, + expected_version: String +) -> Dictionary: + if actual_version.is_empty(): + return {"compatible": false, "reason": "unknown"} + if actual_version == expected_version: + return {"compatible": true, "reason": "exact"} + return {"compatible": false, "reason": "version_mismatch"} + + +static func _server_status_compatibility( + actual_version: String, + expected_version: String, + actual_ws_port: int, + expected_ws_port: int, +) -> Dictionary: + var version_result := _server_version_compatibility(actual_version, expected_version) + if not bool(version_result.get("compatible", false)): + return version_result + if actual_ws_port != expected_ws_port: + return {"compatible": false, "reason": "ws_port_mismatch"} + return version_result + + +static func _managed_record_has_version_drift(record_version: String, current_version: String) -> bool: + return not record_version.is_empty() and record_version != current_version + + +# ---- Incompatible-server bookkeeping ---------------------------------- + +func _set_incompatible_server( + live: Dictionary, + expected_version: String, + port: int, + caller_owns_worker_slot := false +) -> void: + ## Latches the incompatible diagnosis into manager state and asks + ## the dock to re-sweep client rows so they don't show stale green. + ## Threads the caller's `live` snapshot through the recovery proof + ## helper so we don't double-probe the port (~500ms each). + ## + ## Coroutine (#712): the recovery-proof evaluation (port scrapes + + ## per-PID brand shells) and the free-port bind probes run via + ## `_run_blocking` — these fire in exactly the contended/crashed + ## scenarios #678 de-blocked, so they must not stall the main thread + ## either. Everything user-visible (status message, connection block, + ## version-check disarm) is latched synchronously before the first + ## await; only the recovery verdict and the suggested-port diagnostic + ## arrive with the worker. + ## + ## `_run_blocking` tracks a single active worker, so the tail below + ## needs exclusive ownership of that slot. The startup walk awaits + ## this call with `caller_owns_worker_slot=true` — it already owns the + ## slot and serializes the tail behind its own blocking ops. Sync + ## callers (the handshake verdicts via `handle_server_version_*`, the + ## force-restart failure arm) fire-and-forget the tail and leave the + ## flag false, so the head takes ownership for them: a handshake + ## verdict lands from `_process` while a startup walk can still be + ## suspended in `_run_blocking`, and starting the tail's worker then + ## would steal the slot — the walk's op is orphaned from the + ## `_invalidate_async_startup` join guarantee and its resume gets a + ## null without a generation bump (the Nil-into-Dictionary crash on + ## the incompatible-occupant walk). Cancelling the walk first mirrors + ## the recovery click (#712): the diagnosis in hand supersedes + ## whatever the walk was still probing for. + if not caller_owns_worker_slot: + _invalidate_async_startup() + transition_state(McpServerStateScript.INCOMPATIBLE) + _connection_blocked = true + _server_expected_version = expected_version + _server_actual_name = str(live.get("name", "")) + _server_actual_version = _live_version_for_message(live) + _server_status_message = _incompatible_server_message( + live, expected_version, port, int(_host._resolved_ws_port) + ) + ## Conservative default until the off-thread proof lands: the dock + ## paints "not recoverable" rather than offering a kill we have not + ## yet proven ownership for. + _can_recover_incompatible = false + _host._refresh_dock_client_statuses() + ## Propagate the verdict to the live connection (#691). Pre-#678 the + ## startup walk finished synchronously before `_connection` existed, so + ## plugin.gd captured the INCOMPATIBLE verdict when constructing it. + ## Post-#678 the walk suspends at its first `_run_blocking` and the + ## plugin snapshots the pre-walk defaults (`connect_blocked=false`) — so + ## a verdict landing later (startup-walk recovery failure, handshake + ## mismatch, force-restart failure) must reach the connection here, or + ## it keeps dialing the WS port forever. Also disarm the version check: + ## the diagnosis already landed, so leaving the check armed keeps + ## per-frame `_process` on for the plugin's whole lifetime. + if _host._connection != null: + _host._connection.connect_blocked = true + _host._connection.connect_block_reason = _server_status_message + _host._connection.disconnect_from_server() + disarm_version_check() + _host._update_process_enabled() + + ## Off-thread recovery proof (#712), mirroring recover_strong_port_occupant: + ## the EditorSettings record is read on the main thread up front and + ## injected as record_override — EditorSettings is main-thread-only. + var async_gen := _async_generation + var record: Dictionary = _host._read_managed_server_record() + var proof_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {"proof": "", "pids": []} + return _host._evaluate_recovery_port_occupant_proof(port, live, record) + ) + if _async_stale(async_gen) or proof_result == null: + return + var proof: Dictionary = proof_result + var proof_name := str(proof.get("proof", "")) + _can_recover_incompatible = not proof_name.is_empty() + print("MCP | proof: %s" % (proof_name if _can_recover_incompatible else "(none)")) + if not _can_recover_incompatible: + ## Non-recoverable: a foreign / unprovable occupant holds the port and + ## we have no ownership proof, so we must NOT kill it — surface a + ## concrete free port the user can switch to instead (the same hint + ## the dock crash body renders). Logging it to the editor output also + ## lets `ci-stale-server-smoke --mode foreign` assert this upstream + ## classification from CI. Reservation-aware on Windows; the bind + ## probes behind suggest_free_port also run off-thread (#712). + var suggested_result: Variant = await _run_blocking(func() -> Variant: + return ClientConfigurator.suggest_free_port(port + 1) + ) + if _async_stale(async_gen) or suggested_result == null: + return + print("MCP | port %d occupant not recoverable (no ownership proof); suggested free port %d (set godot_ai/http_port)" % [port, int(suggested_result)]) + ## Second sweep so the dock's recovery affordance reflects the verdict + ## that just landed. + _host._refresh_dock_client_statuses() + + +static func _incompatible_server_message( + live: Dictionary, + expected_version: String, + port: int, + expected_ws_port: int +) -> String: + var version := _live_version_for_message(live) + var actual_ws_port := _live_ws_port_for_message(live) + ## `package_path` is a v2.4.4+ field — older servers omit it. Suffix + ## the message with "(loaded from )" when present so the user + ## can tell *which* `src/godot_ai/` is serving the port without + ## walking the process tree. See #416. + var package_path := _live_package_path_for_message(live) + var path_suffix := " (loaded from %s)" % package_path if not package_path.is_empty() else "" + ## After a plugin update, the usual occupant is a backend kept alive by + ## AI-client attach bridges still pinned to the previous version (their + ## leases outrank us — #669/#839, we must not kill it). Name that repair + ## first; "stop the old server" alone reads as a dead end when the server + ## respawns the moment the user kills it. + var repair := ( + "If AI-client attach bridges are keeping it alive, run Configure all to " + + "repin them, then restart those client apps — the old server exits on " + + "its own. Otherwise stop it manually or change both HTTP and WS ports." + ) + if not version.is_empty(): + if actual_ws_port > 0 and actual_ws_port != expected_ws_port: + return ( + "Port %d is occupied by godot-ai server v%s using WS port %d%s; " + + "plugin expects v%s with WS port %d. %s" + ) % [port, version, actual_ws_port, path_suffix, expected_version, expected_ws_port, repair] + return ( + "Port %d is occupied by godot-ai server v%s%s; plugin expects v%s. %s" + ) % [port, version, path_suffix, expected_version, repair] + var status_code := int(live.get("status_code", 0)) + if status_code > 0: + return ( + "Port %d is occupied by an unverified server (status endpoint returned HTTP %d); " + + "plugin expects godot-ai v%s. Stop the other server or change both HTTP and WS ports." + ) % [port, status_code, expected_version] + return ( + "Port %d is occupied by another process; plugin expects godot-ai v%s. " + + "Stop the other process or change both HTTP and WS ports." + ) % [port, expected_version] + + +static func _live_status_identifies_godot_ai(live: Dictionary) -> bool: + return str(live.get("name", "")) == "godot-ai" + + +static func _live_version_for_message(live: Dictionary) -> String: + if live.has("name") and str(live.get("name", "")) != "godot-ai": + return "" + return str(live.get("version", "")) + + +static func _live_ws_port_for_message(live: Dictionary) -> int: + if live.has("name") and str(live.get("name", "")) != "godot-ai": + return 0 + return int(live.get("ws_port", 0)) + + +static func _live_package_path_for_message(live: Dictionary) -> String: + ## Only trust the path when the live snapshot confirms a godot-ai + ## server — a probe of some unrelated HTTP service could in theory + ## return a `package_path` JSON field, and we don't want to mislabel + ## that as "godot-ai loaded from …" in the incompatible banner. + if live.has("name") and str(live.get("name", "")) != "godot-ai": + return "" + return str(live.get("package_path", "")) + + +# ---- start_server / spawn watch / respawn ----------------------------- + + +## Sets GODOT_AI_DISABLE_TELEMETRY in the process environment for the +## upcoming OS.create_process call if: (a) neither GODOT_AI_DISABLE_TELEMETRY +## nor DISABLE_TELEMETRY is already set to a *truthy* value (a falsey "0" does +## NOT count — it must not suppress a dock UI opt-out), and (b) the effective +## McpSettings.telemetry_enabled() is false. Returns true if the var was +## injected so the caller can unset it after spawning. +func _inject_telemetry_env() -> bool: + ## If telemetry is already disabled by a *truthy* env var, leave the env as + ## the user/CI set it — the post-spawn cleanup unsets what we inject, so + ## injecting here would strip their own var from the editor process. A + ## *falsey* value (e.g. DISABLE_TELEMETRY=0) must NOT count as "handled": + ## fall through so a dock UI opt-out still reaches the spawned server. The + ## truthy test mirrors McpSettings.telemetry_enabled() and the Python server. + if McpSettings.env_truthy("GODOT_AI_DISABLE_TELEMETRY") or McpSettings.env_truthy("DISABLE_TELEMETRY"): + return false + if not McpSettings.telemetry_enabled(): + OS.set_environment("GODOT_AI_DISABLE_TELEMETRY", "true") + return true + return false + + +## Set GODOT_AI_OWNER_PID to this editor's PID for the next OS.create_process, +## so the spawned server can self-reap if this editor crashes. Returns true if +## set (caller must unset right after spawning — keep it out of the persistent +## editor env). No-op on Windows, where the server's reaper is disabled. +func _set_owner_pid_env() -> bool: + if OS.get_name() == "Windows": + return false + ## keep_server_on_exit (#800): a server meant to outlive editors must not + ## self-reap when this editor dies — don't hand it an owner pid at all. + if ClientConfigurator.keep_server_on_exit(): + return false + OS.set_environment("GODOT_AI_OWNER_PID", str(OS.get_process_id())) + return true + + +## Mark the next OS.create_process as plugin-spawned so the server arms its +## session-idle self-terminate backstop (#498): with zero editor sessions for +## a grace window, it exits on its own. Unlike the owner-PID reaper this is +## pure session-count on the server side, so it is set on EVERY platform — +## including Windows, where owner-PID is skipped; this marker is what finally +## gives Windows orphan coverage (#497). Same env-channel rationale and same +## tight scoping as _set_owner_pid_env: callers unset it right after spawning +## so a later manually-started dev server can never inherit it and idle-kill +## itself. +func _set_plugin_spawned_env() -> void: + OS.set_environment("GODOT_AI_PLUGIN_SPAWNED", "1") + + +## keep_server_on_exit (#800): opt the spawned server out of the +## session-idle self-terminate backstop (#498) via its existing +## GODOT_AI_NO_IDLE_EXIT escape hatch — a keep-alive server sits at zero +## sessions between editor runs by design, which is exactly what the +## backstop reaps. Returns true if set (same tight scoping as +## _set_owner_pid_env: callers unset right after spawning, and only when +## WE set it, so a user's own NO_IDLE_EXIT env is never stripped). +func _set_keep_alive_env() -> bool: + if not ClientConfigurator.keep_server_on_exit(): + return false + OS.set_environment("GODOT_AI_NO_IDLE_EXIT", "1") + return true + + +## Generate a fresh per-launch WS handshake auth token (#690) and stage it +## in the env for the next OS.create_process, same channel and same tight +## scoping as _set_owner_pid_env (callers unset right after spawning — the +## secret must not linger in the editor env). The caller hands the returned +## token to the host on successful spawn so the connection echoes it in the +## handshake and the managed-server record persists it across reloads. +func _set_ws_token_env() -> String: + var token := Crypto.new().generate_random_bytes(32).hex_encode() + OS.set_environment("GODOT_AI_WS_TOKEN", token) + return token + + +## Branch table (recorded version is the "is this ours?" signal — uvx +## launcher PIDs go stale; #135/#137): +## port free -> spawn fresh, record PID +## port in use, record matches + live ok -> adopt port owner (heals PID) +## port in use, record drifts -> kill owner + respawn +## port in use, no verified live match -> block adoption + warn +## +## #678: this is a coroutine in production (`defer_blocking_work`) — the +## port scrapes, status probes, and kill-drain waits run off the main +## thread and the state machine resumes between frames, so the editor +## stays responsive when the port is contended. With the flag off (unit +## tests) nothing suspends and the call completes synchronously. +func start_server() -> void: + if _start_in_flight: + return + _start_in_flight = true + var gen := _async_generation + await _start_server_impl(gen) + ## Only release the guard if this walk is still the current one — a + ## cancelled (stale) walk unwinding here must not clobber the guard a + ## newer walk armed after `_invalidate_async_startup`. + if gen == _async_generation: + _start_in_flight = false + ## Walk-completion continuation lives HERE — on the RefCounted + ## manager, kept alive by its own suspended state — never on the + ## plugin: resuming a coroutine of a freed Node errors out, and + ## reload churn frees plugin instances while walks are suspended. + if is_instance_valid(_host) and _host.has_method("_finish_startup_trace_after_walk"): + _host._finish_startup_trace_after_walk() + + +func _start_server_impl(async_gen: int) -> void: + if _host._server_started_this_session: + ## Static flag persists across disable/enable cycles in one editor + ## session — re-entrant spawn guard for plugin-reload-during-update. + _startup_path = McpStartupPathScript.GUARDED + transition_state(McpServerStateScript.GUARDED) + return + + _refresh_retried = false + if _readopt_walk_pending: + ## #805: this walk was triggered by the fast-exit re-adopt arm. + ## Keep the spent budget: if this walk ends up spawning and that + ## spawn fast-exits against a live godot-ai again, the occupant is + ## flapping and the diagnosis must latch terminal instead of + ## re-walking forever. Recovery paths (adoption, healthy spawn) + ## refresh the budget explicitly. + _readopt_walk_pending = false + else: + _readopt_after_spawn_exit_retried = false + _conflict_port = 0 + + var port := ClientConfigurator.http_port() + var ws_port := ClientConfigurator.ws_port() + var current_version := _expected_server_version() + _server_expected_version = current_version + + ## The worker closures re-check the host: the plugin can be freed while + ## a bounded shell probe is still running, and the generation check only + ## protects state after resume, not calls inside the task (#682 review). + var port_in_use_result: Variant = await _run_blocking(func() -> Variant: + return is_instance_valid(_host) and _host._is_port_in_use(port) + ) + if _async_stale(async_gen) or port_in_use_result == null: + return + var port_in_use := bool(port_in_use_result) + if not port_in_use: + ## #745: after an editor crash (or under multi-editor churn) the + ## managed server keeps running, yet the bind probe can still say + ## "free" (Windows lets a SO_REUSEADDR bind succeed over a live + ## listener; the scrape fallback can fail transiently). The HTTP + ## status probe is the authoritative tie-breaker and runs + ## UNCONDITIONALLY: the pid-file evidence gate that used to guard it + ## goes stale exactly when it's needed most — same-named test + ## projects share one app_userdata dir, so another editor's walk can + ## clear or overwrite the pid-file, and blind-spawning here produced + ## the reproduced duplicate-spawn + 4003 token loop. A live godot-ai + ## answer forces the adopt/recover branch below; an unresponsive + ## port falls through to the normal spawn path at the cost of one + ## fast connection-refused probe (off-thread in production). + var evidence_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {} + return _host._probe_live_server_status_for_port(port) + ) + if _async_stale(async_gen) or evidence_result == null: + return + var evidence: Dictionary = evidence_result + if _live_status_identifies_godot_ai(evidence): + port_in_use = true + if port_in_use: + var record: Dictionary = _host._read_managed_server_record() + var record_version := str(record.get("version", "")) + var record_ws_port := int(record.get("ws_port", 0)) + _host._set_resolved_ws_port(PortResolver.resolved_ws_port_for_existing_server( + record_ws_port, + record_version, + current_version, + int(_host._resolve_ws_port()) + )) + ws_port = int(_host._resolved_ws_port) + ## Untyped first: a cancelled walk gets null back (see _run_blocking) + ## and must reach the staleness check before any typed cast. + var live_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {} + return _host._probe_live_server_status_for_port(port) + ) + if _async_stale(async_gen) or live_result == null: + return + var live: Dictionary = live_result + var live_version := str(_host._verified_status_version(live)) + var live_ws_port := int(_host._verified_status_ws_port(live)) + var compatibility: Dictionary = _server_status_compatibility( + live_version, + current_version, + live_ws_port, + ws_port, + ) + if compatibility.get("compatible", false): + _server_actual_name = "godot-ai" + _server_actual_version = live_version + _can_recover_incompatible = false + ## A matching version is compatibility evidence, not ownership + ## evidence (#759/#764). A stale EditorSettings record can name a + ## dead PID while an unrelated compatible server owns the port. + ## Retain managed ownership only when the recorded PID is itself + ## the live, branded listener. + var adoption_proof_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {"proof": "", "pids": []} + return _host._evaluate_strong_port_occupant_proof(port, live, record) + ) + if _async_stale(async_gen) or adoption_proof_result == null: + return + var adoption_proof: Dictionary = adoption_proof_result + var proof_pids: Array[int] = [] + proof_pids.assign(adoption_proof.get("pids", [])) + var owner := int(proof_pids[0]) if not proof_pids.is_empty() else 0 + var record_owns_listener := str(adoption_proof.get("proof", "")) == "managed_record" + var owner_label := adopt_compatible_server( + record_version, + current_version, + owner, + record_owns_listener + ) + _host._server_started_this_session = true + _startup_path = McpStartupPathScript.ADOPTED + transition_state(McpServerStateScript.READY) + print(_compatible_adoption_log_message( + owner_label, + int(_server_pid), + owner, + str(_server_actual_version), + live_ws_port, + current_version + )) + return + if bool(_managed_record_has_version_drift(record_version, current_version)): + print("MCP | managed server v%s does not match plugin v%s, restarting" + % [record_version, current_version]) + ## One transaction owns strong-proof recovery and the bounded stale-version + ## fallback. The WS handshake path can observe the same old server while + ## these awaits are suspended; `_recovery_in_flight` makes that verdict + ## coalesce here instead of starting a competing kill/respawn. + var recovered: bool = await _recover_startup_port_occupant( + port, live, live_version, current_version, async_gen + ) + if _async_stale(async_gen): + return + if not recovered: + _host._server_started_this_session = true + var post_recovery_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {} + return _host._probe_live_server_status_for_port(port) + ) + if _async_stale(async_gen) or post_recovery_result == null: + return + var post_recovery_live: Dictionary = post_recovery_result + ## Awaited with caller_owns_worker_slot=true (#712): the + ## diagnosis tail runs its own _run_blocking proof, and the walk + ## stays the single owner of the active-worker slot by + ## serializing that tail behind this await instead of letting it + ## re-take the slot. The status message is latched before the + ## tail's first await, so the push_warning below reads the final + ## text either way. + await _set_incompatible_server(post_recovery_live, current_version, port, true) + if _async_stale(async_gen): + return + _startup_path = McpStartupPathScript.INCOMPATIBLE + push_warning(str(_server_status_message)) + return + else: + _startup_path = McpStartupPathScript.FREE + + _host._set_resolved_ws_port(_host._resolve_ws_port()) + ws_port = _host._resolved_ws_port + + _host._startup_trace_count("server_command_discovery") + ## CLI-finder discovery shells out (which/where, login shell) on cache + ## misses — the same #238/#239 family the dock already runs off-thread. + var server_cmd_result: Variant = await _run_blocking(func() -> Variant: + return ClientConfigurator.get_server_command() + ) + if _async_stale(async_gen) or server_cmd_result == null: + return + var server_cmd: Array = server_cmd_result + if server_cmd.is_empty(): + set_terminal_diagnosis(McpServerStateScript.NO_COMMAND) + _startup_path = McpStartupPathScript.NO_COMMAND + push_warning("MCP | could not find server command") + return + + var cmd: String = server_cmd[0] + var args: Array[String] = [] + args.assign(server_cmd.slice(1)) + args.append_array(_host._build_server_flags(port, ws_port)) + + ## Wipe any stale pid-file so a failed launch can't leave last + ## session's PID for `_find_managed_pid` to read. + _host._clear_pid_file() + + ## Proactive Windows port-reservation check (#146) — bind would + ## fail silently with WinError 10013 inside a Hyper-V / WSL2 / + ## Docker exclusion range; netstat shows nothing. + if WindowsPortReservation.is_port_excluded(port): + _host._server_started_this_session = true + set_terminal_diagnosis(McpServerStateScript.PORT_EXCLUDED) + _startup_path = McpStartupPathScript.RESERVED + push_warning("MCP | port %d is reserved by Windows (Hyper-V / WSL2 / Docker)" % port) + return + + ## ---- Spawn-time env-mutation window (#691) ------------------------- + ## From here to the post-spawn unsets below, the editor's process-global + ## environment is mutated around OS.create_process (which has no + ## per-child env parameter). Two invariants keep this safe: + ## 1. The window is SYNCHRONOUS main-thread code — no `await` between + ## the first setenv and the last unsetenv — and worker dispatch also + ## only happens on the main thread, so no new worker can start inside + ## the window. + ## 2. Already-running workers never call OS.get_environment: every env + ## read reachable from a worker (path templates, config_home_override, + ## CLI finder, mode_override/startup-trace) routes through + ## McpPathTemplate.env_lookup, which serves worker threads from a + ## main-thread-warmed snapshot. A concurrent glibc getenv during + ## setenv can return a freed pointer — process-fatal. + ## Residual (accepted): a worker's own OS.execute child (CLI status + ## probe) launched while this window is open inherits the temp vars — + ## rare, and tame next to the crash class above. + var injected_telemetry_env := _inject_telemetry_env() + + ## PYTHONPATH handling for dev checkouts: when the editor is launched + ## against a worktree whose `src/godot_ai/__version__` differs from the + ## root repo's editable install, the dev-venv python's `sitecustomize` + ## adds the *root repo's* `src/` to `sys.path`. The spawned server then + ## reports the root repo's version, the plugin's compatibility check + ## flags it as incompatible, and the user gets a Restart-Server loop + ## with no exit. `start_dev_server` already prepends the worktree's + ## `src/` for its --reload spawn; mirror that here for the auto-spawn + ## path so the same worktree-vs-root version skew is impossible. Gated + ## on `is_dev_checkout()` so production user installs (no nearby `src/`) + ## are untouched. See #418. + var worktree_src := "" + var prev_pythonpath := "" + var pythonpath_set := false + if ClientConfigurator.is_dev_checkout(): + worktree_src = ClientConfigurator.find_worktree_src_dir( + ProjectSettings.globalize_path("res://") + ) + if not worktree_src.is_empty(): + prev_pythonpath = OS.get_environment("PYTHONPATH") + var sep := ";" if OS.get_name() == "Windows" else ":" + var new_pp := ( + worktree_src + if prev_pythonpath.is_empty() + else worktree_src + sep + prev_pythonpath + ) + OS.set_environment("PYTHONPATH", new_pp) + pythonpath_set = true + + ## Tell the spawned server which editor owns it so it can self-reap if we + ## die without a clean stop_server (crash / hard-kill). Passed via env, not + ## a CLI flag, so an older server (staggered user-mode upgrade) silently + ## ignores an unknown var instead of failing argparse. Scoped tightly around + ## create_process and unset right after (like PYTHONPATH below): the child + ## inherits it, but it must NOT linger in the editor env, or a later + ## non-reload `godot-ai` subprocess (dev server, future spawn) would inherit + ## it and wrongly arm a reaper keyed to this editor. + ## Skipped on Windows: the server's reaper is POSIX-only for now (Windows + ## process-liveness/self-shutdown isn't live-validated yet). The server + ## gates on this too. + var owner_env_set := _set_owner_pid_env() + _set_plugin_spawned_env() + var keep_alive_env_set := _set_keep_alive_env() + var ws_token := _set_ws_token_env() + + _server_pid = OS.create_process(cmd, args) + var spawned_pid := int(_server_pid) + + if owner_env_set: + OS.unset_environment("GODOT_AI_OWNER_PID") + OS.unset_environment("GODOT_AI_PLUGIN_SPAWNED") + if keep_alive_env_set: + OS.unset_environment("GODOT_AI_NO_IDLE_EXIT") + OS.unset_environment("GODOT_AI_WS_TOKEN") + + ## Restore PYTHONPATH immediately — the spawned child has already + ## copied the env, so the editor's own process state returns to + ## baseline. Leaving it set would leak to any later OS.create_process + ## from unrelated paths. + if pythonpath_set: + if prev_pythonpath.is_empty(): + OS.unset_environment("PYTHONPATH") + else: + OS.set_environment("PYTHONPATH", prev_pythonpath) + + if injected_telemetry_env: + OS.unset_environment("GODOT_AI_DISABLE_TELEMETRY") + + if spawned_pid > 0: + _server_spawn_ms = Time.get_ticks_msec() + _server_exit_ms = 0 + _server_pid_published_elapsed_ms = 0 + _spawn_dead_since_ms = 0 + _server_keep_alive = keep_alive_env_set + _host._server_started_this_session = true + transition_state(McpServerStateScript.SPAWNING) + ## The child copied the env, so this token is what the server will + ## verify handshakes against — adopt it BEFORE writing the record + ## (the record write persists _ws_auth_token). + _host._set_ws_auth_token(ws_token) + ## Record the launcher PID so same-session + ## prepare_for_update_reload has something to kill. The next + ## editor start's adopt branch heals it to the real port owner. + _host._write_managed_server_record(spawned_pid, current_version, _server_keep_alive) + _startup_path = McpStartupPathScript.SPAWNED + ## Log "PYTHONPATH prefix=" rather than "PYTHONPATH=" so the line + ## isn't misleading when an existing PYTHONPATH was present — + ## we prepended `worktree_src`, not replaced. Keeps the log + ## compact (worktree_src is the actionable piece; the full + ## prev_pythonpath can be 5+ entries long on dev machines). + var suffix := " (PYTHONPATH prefix=%s)" % worktree_src if not worktree_src.is_empty() else "" + print("MCP | started server (PID %d, v%s): %s %s%s" % [spawned_pid, current_version, cmd, " ".join(args), suffix]) + _host._start_server_watch() + else: + _server_status_message = "" + set_terminal_diagnosis(McpServerStateScript.CRASHED) + _startup_path = McpStartupPathScript.CRASHED + push_warning("MCP | failed to start server") + + +## Is the watched spawn PID's death still explainable as a launcher handoff +## rather than a server exit? (#797) +## +## Observed on Windows 11 with a uv-created venv: one boot in four logged +## "server exited after 5146ms" while the real server kept running and was +## then adopted. The watched PID had died on a healthy boot, and because the +## server had not yet written its pid-file there was nothing to heal onto, so +## the watch crossed SPAWN_GRACE_MS and reported an exit — rescued only by the +## crash-survivor adoption path. +## +## A uv venv's `python.exe` is a shim rather than the interpreter, and the real +## server does run under a *different* PID than the one `OS.create_process` +## hands back. But the original report's suspected mechanism — that the shim +## exits once its child is up — is **disproven**, not merely unconfirmed. A +## 12-boot run on Windows 11 with a uv venv found the spawned trampoline alive +## on every boot, with the child owning both the pid-file and the listener; a +## CI runner showed the same. The shim is a live parent for the process's whole +## life, so it is not what kills the watched PID. +## +## Two consequences worth keeping straight. First, this gate is keyed to the +## observable condition — watched PID dead, no pid-file yet — not to any theory +## of why it died, so it stays correct whatever the cause. Second, and less +## comfortable: in that same 12-boot run the false "server exited" line never +## appeared AND the watched PID never died, so the guard never fired. Those +## clean boots are evidence the symptom did not reproduce, NOT evidence this +## guard fixes it. The true cause of the original 1-in-4 report is still +## unknown; if it resurfaces, start from that rather than from the trampoline. +## +## `real_pid <= 0` means no pid-file exists yet, and that reliably means "this +## server has not published one" rather than "stale leftover": `start_server` +## wipes the pid-file immediately before every spawn. So an absent pid-file +## plus a dead spawn PID inside the window is the handoff signature. +## +## Deliberately gated to Windows. POSIX uv venvs exec rather than trampoline, +## so a dead spawn PID there really is a dead server, and delaying its +## diagnosis would only slow down honest crash reporting on the platforms +## where this cannot happen. `os_name` is a parameter rather than an +## `OS.get_name()` call so the Windows path is exercisable from any host. +static func is_spawn_handoff_pending( + os_name: String, real_pid: int, elapsed_ms: int, window_ms: int +) -> bool: + if os_name != "Windows": + return false + if real_pid > 0: + return false + return elapsed_ms < window_ms + + +## First-write-wins stamp for the elapsed time at which the spawn PID was first +## observed dead (#797). +## +## A diagnosis raised after waiting out a handoff must still report when the +## process actually exited, not when the wait gave up — the point of #797 is an +## honest log line. Returns the existing stamp once one is set, so later ticks +## in the same wait cannot overwrite it; `<= 0` means "not yet stamped", +## matching how the field is cleared per spawn. +static func first_death_stamp(current_stamp_ms: int, elapsed_ms: int) -> int: + return current_stamp_ms if current_stamp_ms > 0 else elapsed_ms + + +## One-line forensic snapshot taken the moment a spawn is judged to have +## fast-exited (#797). +## +## #797 reported `server exited after 5146ms` on a healthy Windows boot, once +## in four. It is still unexplained: a 12-boot run on the reported +## configuration reproduced neither the symptom nor its suspected mechanism — +## the uv trampoline was alive on every boot, with the child owning the +## pid-file and the listener, so the shim's exit is ruled out as the cause. +## What killed that watched PID is unknown, and the log line at the time +## carried no evidence to answer it with. +## +## So capture the state at the moment of judgement rather than asking the next +## person to reproduce a 1-in-4 bug under observation. Everything here is read +## through seams the surrounding diagnosis already uses, on a path that only +## runs when a spawn is being declared dead, so it costs nothing in the +## healthy case. +## Deliberately does NOT scrape the port for listener PIDs. This runs from the +## 1 Hz watch loop, on a live frame, so a `_find_all_pids_on_port` subprocess +## here would stall the editor for a diagnostic. Deferring it via +## `_run_blocking` was the alternative and is worse: that helper is +## `await`-based, so it would turn this, `_diagnose_spawn_fast_exit` and +## `check_server_health` into coroutines — making the watch callback resume +## across arbitrary frames while its branches set terminal state and trigger +## re-adoption walks. That is the teardown-ordering hazard +## `_invalidate_async_startup` exists to contain, and it is not worth taking +## on for a log line. +## +## Little is lost: the probe on the very next line already establishes whether +## a godot-ai server answers on the port, and `_diagnose_spawn_port_conflict` +## names a foreign occupant when there is one. If you are tempted to add the +## PID list back, put it behind that existing conflict path rather than here. +func _log_spawn_exit_forensics() -> void: + var spawn_pid := int(_server_pid) + var pid_file_pid := int(_host._read_pid_file_for_proof()) + ## Computed here rather than accepted as a parameter. The caller's + ## `elapsed` IS `_spawn_dead_since_ms` — #837 passes the true death time so + ## the user-facing "server exited after Nms" line stays honest — so taking + ## it would make these two fields report the same number, collapsing the + ## exact distinction they exist to record. + var diagnosed_at_ms := 0 + if int(_server_spawn_ms) > 0: + diagnosed_at_ms = Time.get_ticks_msec() - int(_server_spawn_ms) + _host._log_buffer.log(format_spawn_exit_forensics({ + "os": OS.get_name(), + "launch_mode": ClientConfigurator.get_server_launch_mode(), + "elapsed_ms": diagnosed_at_ms, + ## Differs from elapsed_ms when a Windows handoff window was waited out + ## (#824/#837): the true death time versus when we gave up on it. + "first_dead_ms": int(_spawn_dead_since_ms), + "spawn_pid": spawn_pid, + ## Re-read rather than trusted from the watch tick: if the spawn PID is + ## alive HERE, the death that triggered this was transient, which is a + ## different bug from a process that really exited. + "spawn_alive": spawn_pid > 0 and bool(_host._pid_alive_for_proof(spawn_pid)), + "pid_file_pid": pid_file_pid, + "pid_file_alive": pid_file_pid > 0 and bool(_host._pid_alive_for_proof(pid_file_pid)), + })) + + +## Render the forensic snapshot. Pure so the format is testable without a live +## editor, and kept to one line so it survives log truncation in a bug report. +static func format_spawn_exit_forensics(facts: Dictionary) -> String: + var spawn_pid := int(facts.get("spawn_pid", 0)) + var pid_file_pid := int(facts.get("pid_file_pid", 0)) + ## The single most diagnostic bit, stated rather than left to be inferred: + ## a live pid-file process while the watched one is gone is the launcher + ## handoff shape; both gone is a real crash. + var shape := "unknown" + var spawn_alive := bool(facts.get("spawn_alive", false)) + var file_alive := bool(facts.get("pid_file_alive", false)) + if spawn_alive: + shape = "watched_pid_still_alive" + elif file_alive and pid_file_pid != spawn_pid: + shape = "handoff_child_alive" + elif not file_alive and pid_file_pid <= 0: + shape = "no_pid_file_published" + else: + shape = "all_dead" + return ( + "#797 spawn-exit forensics: shape=%s os=%s launch=%s elapsed=%dms " + + "first_dead=%dms spawn_pid=%d(alive=%s) pid_file_pid=%d(alive=%s)" + ) % [ + shape, + str(facts.get("os", "")), + str(facts.get("launch_mode", "")), + int(facts.get("elapsed_ms", 0)), + int(facts.get("first_dead_ms", 0)), + spawn_pid, + str(spawn_alive), + pid_file_pid, + str(file_alive), + ] + + +## Watch-loop callback (1 Hz, cold-start budget until pid-file publication, +## then the warm budget from the publication tick). +## `--pid-file` is the source of truth on Windows / uvx where the +## launcher PID dies quickly after spawning the real interpreter. +func check_server_health() -> void: + if int(_server_pid) <= 0: + _host._stop_server_watch() + return + var elapsed := Time.get_ticks_msec() - int(_server_spawn_ms) + var real_pid := PortResolver.read_pid_file() + if real_pid > 0 and _server_pid_published_elapsed_ms == 0: + _server_pid_published_elapsed_ms = elapsed + var spawn_pid := int(_server_pid) + if real_pid > 0 and real_pid != spawn_pid and PortResolver.pid_alive(real_pid): + _spawn_dead_since_ms = 0 + _server_pid = real_pid + ## The spawn record initially contains the launcher PID so same-session + ## teardown can kill it. Heal it as soon as the server publishes its + ## authoritative PID; future adoption requires the recorded PID to be + ## the actual live listener (#759). + _host._write_managed_server_record(real_pid, _expected_server_version(), _server_keep_alive) + ## #805: the spawn survived to publish its pid-file — proven + ## recovery, so the fast-exit re-adopt budget refreshes. + ## + ## The stale-recovery budget is deliberately NOT reset here (#890 + ## review P1): the Python server writes its pid-file during import, + ## BEFORE uvicorn binds HTTP or the WebSocket listener starts + ## (src/godot_ai/__init__.py) — publication proves the child reached + ## that line, not that it owns either port. A bridge respawn can + ## still steal the bind after the pid-file lands, and zeroing here + ## left that fast-exit with no recovery round. The budget resets on + ## the genuinely proven recoveries: adoption and the verified + ## compatible handshake. + _readopt_after_spawn_exit_retried = false + elif not PortResolver.pid_alive(spawn_pid): + _spawn_dead_since_ms = first_death_stamp(_spawn_dead_since_ms, elapsed) + if is_spawn_handoff_pending( + OS.get_name(), real_pid, elapsed, int(_host.SPAWN_HANDOFF_MS) + ): + return + if elapsed >= int(_host.SPAWN_GRACE_MS) and not McpServerStateScript.is_terminal_diagnosis(_server_state): + _diagnose_spawn_fast_exit(_spawn_dead_since_ms) + return + var watch_elapsed := watch_window_elapsed_ms( + elapsed, real_pid, _server_pid_published_elapsed_ms + ) + if watch_elapsed >= watch_budget_ms( + real_pid, int(_host.SERVER_WATCH_MS), int(_host.SERVER_COLD_START_WATCH_MS) + ): + ## #896: past the budget we stop watching either way, but a spawn that + ## never published a pid-file did not "survive startup" — it just never + ## proved anything. Say so, or the only remaining signal is a silent + ## reconnect loop. + if real_pid <= 0: + print( + "MCP | server spawn never published a pid-file within %ds; " + % int(_host.SERVER_COLD_START_WATCH_MS / 1000) + + "no longer watching it. If the editor stays disconnected, " + + "check the Godot output log for the server's own errors." + ) + _host._stop_server_watch() + + +## How long to keep watching a spawn, given whether it has published its +## pid-file yet. +## +## Pure so tests can drive the decision without a live spawn. `pid_from_file` +## is the authoritative "the server got far enough to run" signal: the Python +## server writes it during import, before uvicorn binds. Until it appears, a +## live launcher PID proves only that `uvx` has not exited — on a cold start +## that is usually a download still in progress, not a started server. +static func watch_budget_ms(pid_from_file: int, warm_ms: int, cold_ms: int) -> int: + return warm_ms if pid_from_file > 0 else cold_ms + + +## Elapsed time in the currently-active watch window. Before startup proof, +## the window begins at process creation. Once the pid-file appears, begin a +## fresh warm watch window so a 45-second download still gets 30 seconds of +## early-exit coverage after Python starts. +static func watch_window_elapsed_ms( + spawn_elapsed_ms: int, pid_from_file: int, pid_published_elapsed_ms: int +) -> int: + if pid_from_file <= 0 or pid_published_elapsed_ms <= 0: + return spawn_elapsed_ms + return maxi(0, spawn_elapsed_ms - pid_published_elapsed_ms) + + +## The spawned server died inside the SPAWN_GRACE_MS window. Decide what +## that means, in order: +## 1. A live godot-ai server answers on the HTTP port -> our spawn lost +## a port race the bind probe never saw (#745 bind-trap: the walk +## thought the port was free, the duplicate exited unable to bind, +## and the token it staged in the record is now stale). Re-run the +## startup walk so the adopt/recover branch handles the survivor — +## latching CRASHED here left the connection redialing forever with +## a token the surviving server rejects (close code 4003). One +## re-adopt per recovery via `_readopt_after_spawn_exit_retried` +## (#805): the triggered walk preserves the spent budget, so a +## flapping occupant (alive at each fast-exit probe, gone by each +## walk's probes — sustained multi-editor churn) latches a specific +## CRASHED diagnosis on the second round instead of re-walking +## forever. Exception: a verified stale-VERSION occupant with +## `_stale_recovery_budget` rounds left keeps re-walking (each walk +## spends one round in its recovery arm), so a bridge-respawn race +## after a self-update converges instead of latching. +## 2. #647: foreign process on the HTTP or WS port -> FOREIGN_PORT with +## an actionable message (we can't read the child's "port already in +## use" stderr). Checked before the --refresh retry: respawning +## against an occupied port can only fail the same way. +## 3. #172: stale uvx index -> one `--refresh` respawn. +## 4. Otherwise -> CRASHED, pointing at the Godot output log. +func _diagnose_spawn_fast_exit(elapsed: int) -> void: + _log_spawn_exit_forensics() + var live: Dictionary = _host._probe_live_server_status_for_port( + ClientConfigurator.http_port() + ) + if _live_status_identifies_godot_ai(live): + ## Stale-version occupant with authorized recovery rounds left: allow + ## another re-adopt walk even after the #805 one-shot is spent. This is + ## the attach-bridge respawn race — a bridge pinned to the previous + ## version respawns its cached backend the instant the old server is + ## killed, and can beat our (possibly cold) spawn to the bind. Each + ## extra walk spends one `_stale_recovery_budget` round in its recovery + ## arm, so this stays bounded; the #805 flapping diagnosis below still + ## latches for same-version/unverified occupants and once the budget is + ## exhausted. + var stale_retry := _stale_recovery_available( + str(_host._verified_status_version(live)), _expected_server_version() + ) + if not _readopt_after_spawn_exit_retried or stale_retry: + if _readopt_after_spawn_exit_retried: + ## Second and later rounds ride the stale budget — spend HERE, + ## not only in the walk's recovery arm: an occupant that flaps + ## out of existence before each walk's probe (the #805 shape) + ## would otherwise re-walk without ever spending, and the + ## terminal latch below would never be reached. + _stale_recovery_budget -= 1 + _readopt_after_spawn_exit_retried = true + _readopt_walk_pending = true + _host._log_buffer.log( + "server exited after %dms but a live godot-ai server answers on port %d — re-running adoption" + % [elapsed, ClientConfigurator.http_port()] + ) + _host._stop_server_watch() + _server_pid = -1 + ## Clear the spawn guard so the re-walk isn't GUARDED away. The + ## walk's adopt arm re-sets it and fixes the stale token/record + ## (external adoption drops both; managed adoption re-records). + _host._server_started_this_session = false + ## Fire-and-forget (mirrors force_restart_server): the walk is a + ## coroutine in production; its continuation lives on the manager. + start_server() + return + ## #805: the re-adopt budget is spent and a live godot-ai still + ## answers while our spawns keep dying — a flapping occupant + ## (another editor's server starting/stopping under it). Re-walking + ## or respawning can only repeat the cycle; latch a terminal + ## diagnosis that names the actual conflict. Reload Plugin (a fresh + ## walk) refreshes the budget for a deliberate retry. + _server_exit_ms = elapsed + _server_status_message = ( + "The spawned server keeps exiting while another godot-ai server " + + "answers on port %d, and re-adoption was already attempted. " + + "Another editor may be repeatedly starting/stopping a server on " + + "this port. Stop the other process or pick a different port, " + + "then click Reload Plugin." + ) % ClientConfigurator.http_port() + set_terminal_diagnosis(McpServerStateScript.CRASHED) + disarm_version_check() + _host._update_process_enabled() + _host._log_buffer.log(str(_server_status_message)) + push_warning("MCP | %s" % _server_status_message) + _host._stop_server_watch() + return + var conflict := _diagnose_spawn_port_conflict(live) + if not conflict.is_empty(): + _server_exit_ms = elapsed + _server_status_message = str(conflict.get("message", "")) + _conflict_port = int(conflict.get("port", 0)) + set_terminal_diagnosis(McpServerStateScript.FOREIGN_PORT) + disarm_version_check() + _host._update_process_enabled() + _host._log_buffer.log(str(_server_status_message)) + push_warning("MCP | %s" % _server_status_message) + _host._stop_server_watch() + return + if bool(_host._should_retry_with_refresh()): + _refresh_retried = true + respawn_with_refresh() + return + _server_exit_ms = elapsed + ## Generic crash: clear any stale per-state message so the dock's + ## CRASHED body falls back to its launch-mode copy instead of text + ## from an earlier diagnosis. + _server_status_message = "" + set_terminal_diagnosis(McpServerStateScript.CRASHED) + disarm_version_check() + _host._update_process_enabled() + _host._log_buffer.log("server exited after %dms — see Godot output log" % int(_server_exit_ms)) + _host._stop_server_watch() + + +## #647: post-crash port-conflict probe. Returns `{}` when no foreign +## conflict is detected (fall through to the CRASHED / retry path), or +## `{"message": String, "port": int}` when the HTTP or WS port is held by +## a process we can't identify as godot-ai. An occupant that *does* +## identify as godot-ai is deliberately not diagnosed here — that's the +## stale-server / adoption territory handled by `_diagnose_spawn_fast_exit`'s +## re-adopt arm (or the next `start_server` walk), not a foreign conflict. +## `pre_probed_live`: an HTTP status snapshot the caller already has on +## hand; non-empty skips the internal ~500ms probe (the probe helper never +## returns a bare `{}`, so the sentinel is unambiguous). +func _diagnose_spawn_port_conflict(pre_probed_live: Dictionary = {}) -> Dictionary: + var http_port := ClientConfigurator.http_port() + if bool(_host._is_port_in_use(http_port)): + var live: Dictionary = ( + pre_probed_live + if not pre_probed_live.is_empty() + else _host._probe_live_server_status_for_port(http_port) + ) + if _live_status_identifies_godot_ai(live): + return {} + return { + "message": ( + "Port %d is in use by another application. Stop it or change " + + "the port in Editor Settings (godot_ai/http_port)." + ) % http_port, + "port": http_port, + } + var ws_port := int(_host._resolved_ws_port) + if ws_port > 0 and bool(_host._is_port_in_use(ws_port)): + return { + "message": ( + "WebSocket port %d is in use by another application. Stop it " + + "or change the port in Editor Settings (godot_ai/ws_port)." + ) % ws_port, + "port": ws_port, + } + return {} + + +## Retry the spawn with uvx `--refresh` prepended (PyPI index can lag a +## fresh publish ~10 min — #172). One-shot per session via _refresh_retried. +func respawn_with_refresh() -> void: + _host._startup_trace_count("server_command_discovery") + var server_cmd := ClientConfigurator.get_server_command(true) + if server_cmd.is_empty(): + return + var cmd: String = server_cmd[0] + var args: Array[String] = [] + args.assign(server_cmd.slice(1)) + args.append_array(_host._build_server_flags(ClientConfigurator.http_port(), int(_host._resolved_ws_port))) + _host._clear_pid_file() + _host._log_buffer.log("retrying with --refresh (PyPI index may be stale)") + var injected_telemetry_env := _inject_telemetry_env() + ## Set owner PID for THIS spawn too (don't rely on it lingering from + ## start_server) — and unset right after, same scoping as start_server. + var owner_env_set := _set_owner_pid_env() + _set_plugin_spawned_env() + var keep_alive_env_set := _set_keep_alive_env() + var ws_token := _set_ws_token_env() + _server_pid = OS.create_process(cmd, args) + if owner_env_set: + OS.unset_environment("GODOT_AI_OWNER_PID") + OS.unset_environment("GODOT_AI_PLUGIN_SPAWNED") + if keep_alive_env_set: + OS.unset_environment("GODOT_AI_NO_IDLE_EXIT") + OS.unset_environment("GODOT_AI_WS_TOKEN") + if injected_telemetry_env: + OS.unset_environment("GODOT_AI_DISABLE_TELEMETRY") + var spawn_pid := int(_server_pid) + if spawn_pid > 0: + _server_spawn_ms = Time.get_ticks_msec() + _server_exit_ms = 0 + _server_pid_published_elapsed_ms = 0 + _spawn_dead_since_ms = 0 + _server_keep_alive = keep_alive_env_set + var current_version := _expected_server_version() + _host._set_ws_auth_token(ws_token) + _host._write_managed_server_record(spawn_pid, current_version, _server_keep_alive) + print("MCP | retried server (PID %d, v%s): %s %s" % [spawn_pid, current_version, cmd, " ".join(args)]) + else: + ## OS.create_process returned -1 on the retry — surface CRASHED + ## rather than loop. `_refresh_retried` is already true. + _server_status_message = "" + set_terminal_diagnosis(McpServerStateScript.CRASHED) + disarm_version_check() + _host._update_process_enabled() + _host._log_buffer.log("refresh retry failed to spawn — see Godot output log") + _host._stop_server_watch() + + +func adopt_compatible_server( + record_version: String, + current_version: String, + owner: int, + record_owns_listener: bool = false +) -> String: + _server_actual_name = "godot-ai" + _can_recover_incompatible = false + ## #805: adoption (managed or external) is a proven recovery — the + ## session now has a live compatible server. Refresh the fast-exit + ## re-adopt budget so a later, unrelated port race can heal again. + _readopt_after_spawn_exit_retried = false + ## The stale-recovery episode (if any) is over: leftover authorized + ## rounds must not carry into a later, unrelated walk where they could + ## weak-proof-kill a server the user deliberately started. + _stale_recovery_budget = 0 + if record_version == current_version and owner > 0 and record_owns_listener: + ## Managed adoption keeps the record's token (loaded into + ## _ws_auth_token at plugin startup) — the running server was + ## spawned with it and still verifies against it (#690). Version + ## equality alone is deliberately insufficient: the record must also + ## identify the live branded listener (#759/#764). + _server_pid = owner + ## Recover the keep-alive launch flag from the record the spawning + ## session persisted — a keep-alive survivor adopted here must + ## detach again on THIS session's exit, and only the record knows + ## how the process was actually launched. + _server_keep_alive = bool(_host._read_managed_server_record().get("keep_alive", false)) + _host._write_managed_server_record(owner, current_version, _server_keep_alive) + return McpAdoptionLabelScript.MANAGED + _server_pid = -1 + _server_keep_alive = false + ## External server: we didn't spawn it and don't know its token (it + ## most likely has none — dev servers aren't launched with one). Drop + ## ours so the handshake omits the field instead of sending a stale + ## token the server would reject. + _host._set_ws_auth_token("") + _host._clear_managed_server_record() + _host._clear_pid_file() + return McpAdoptionLabelScript.EXTERNAL + + +static func _compatible_adoption_log_message( + owner_label: String, + owned_pid: int, + observed_owner_pid: int, + live_version: String, + live_ws_port: int, + current_version: String +) -> String: + if owner_label == McpAdoptionLabelScript.MANAGED: + return "MCP | adopted managed server (PID %d, live v%s, WS %d, plugin v%s)" % [ + owned_pid, + live_version, + live_ws_port, + current_version + ] + return "MCP | adopted external server owner_pid=%d (live v%s, WS %d, plugin v%s)" % [ + observed_owner_pid, + live_version, + live_ws_port, + current_version + ] + + +## Single-owner recovery transaction for the contended startup walk. Strong +## ownership proof gets first refusal; only a user-authorized, verified version +## drift may fall back to weak proof. Keeping the flag across both awaits is +## what lets the WS handshake path coalesce instead of cancelling this walk. +func _recover_startup_port_occupant( + port: int, + live: Dictionary, + live_version: String, + current_version: String, + async_gen: int, +) -> bool: + var owns_recovery := not _recovery_in_flight + var is_owned_startup := ( + _recovery_in_flight and async_gen == _recovery_owned_startup_generation + ) + if not owns_recovery and not is_owned_startup: + return false + if owns_recovery: + _recovery_in_flight = true + ## Forward `live` so the strong proof helper reuses our snapshot. The kill + ## invalidates it; every later consumer re-probes before using live status. + var recovered: bool = await recover_strong_port_occupant(port, 3.0, live) + if not _async_stale(async_gen) and not recovered and _stale_recovery_available( + live_version, current_version + ): + _stale_recovery_budget -= 1 + print( + "MCP | stale godot-ai v%s holds port %d — replacing it (update/recovery authorized, %d retry round(s) left)" + % [live_version, port, _stale_recovery_budget] + ) + recovered = await _recover_stale_port_occupant_impl(port, 3.0) + ## A nested recovery-owned startup must leave the outer transaction armed; + ## only the path that acquired ownership here may release it. + if owns_recovery: + _recovery_in_flight = false + return recovered + + +## `pre_kill_live` is forwarded into the proof helper so it doesn't +## re-probe a port the caller already probed. The kill invalidates the +## snapshot — callers MUST re-probe before consuming live-status data +## after this returns. +## +## #678: coroutine in production — the proof evaluation (port scrapes + +## per-PID brand shells) and the kill + port-drain wait run off the main +## thread. The EditorSettings record is read on the main thread up front +## and injected into the proof helper; record/pid-file clears stay on the +## main thread after the awaits. +func recover_strong_port_occupant(port: int, wait_s: float, pre_kill_live: Dictionary = {}) -> bool: + var async_gen := _async_generation + var record: Dictionary = _host._read_managed_server_record() + var proof_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {"proof": "", "pids": []} + return _host._evaluate_strong_port_occupant_proof(port, pre_kill_live, record) + ) + if _async_stale(async_gen) or proof_result == null: + return false + var proof: Dictionary = proof_result + var targets: Array[int] = [] + targets.assign(proof.get("pids", [])) + if targets.is_empty(): + return false + + print("MCP | strong proof: %s" % str(proof.get("proof", ""))) + var freed_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return false + ## verify_brand=true: the proof above ran in a separate _run_blocking + ## task with main-thread frames in between — re-check each target at + ## kill time so a PID recycled inside that gap isn't killed (#686). + var killed: Array = _host._kill_processes_and_windows_spawn_children(targets, true) + if not killed.is_empty(): + print("MCP | killed pids %s on port %d" % [str(killed), port]) + _host._wait_for_port_free(port, wait_s) + return not bool(_host._is_port_in_use(port)) + ) + if _async_stale(async_gen) or freed_result == null: + return false + if not bool(freed_result): + return false + + _host._clear_managed_server_record() + _host._clear_pid_file() + return true + + +## Weak-proof sibling of `recover_strong_port_occupant`, reserved for the +## bounded stale-version episode (`_stale_recovery_budget` — callers gate on +## `_stale_recovery_available` and spend a round BEFORE calling). Uses the +## recovery-tier proof (`status_name` allowed) because the target is an +## external previous-version server with no managed record or pid-file to +## prove strong ownership with — the same authority the dock's recovery +## click exercises, here spent under an equally explicit user action (the +## Update click / a recovery click's retry). The kill still brand-verifies +## every PID at kill time (#686), so a recycled or unrelated PID on the +## port is never killed. No pre-probed `live` parameter on purpose: a prior +## failed strong recovery may have partially changed the port's state, so +## the worker re-probes — and re-verifies STALENESS on that fresh snapshot +## (#890 CodeRabbit): the caller's version gate ran on an earlier probe, +## and a same-version server that took the port in the interval must abort +## this recovery, not be killed by it. +func recover_stale_port_occupant(port: int, wait_s: float) -> bool: + if _recovery_in_flight: + return false + _recovery_in_flight = true + var recovered := await _recover_stale_port_occupant_impl(port, wait_s) + _recovery_in_flight = false + return recovered + + +func _recover_stale_port_occupant_impl(port: int, wait_s: float) -> bool: + var async_gen := _async_generation + var record: Dictionary = _host._read_managed_server_record() + ## Resolved on the main thread: the worker must not touch EditorSettings. + var expected_version := _expected_server_version() + var proof_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {"proof": "", "pids": []} + var live: Dictionary = _host._probe_live_server_status_for_port(port) + var live_version := str(_host._verified_status_version(live)) + if live_version.is_empty() or live_version == expected_version: + return {"proof": "", "pids": []} + return _host._evaluate_recovery_port_occupant_proof(port, live, record) + ) + if _async_stale(async_gen) or proof_result == null: + return false + var proof: Dictionary = proof_result + var targets: Array[int] = [] + targets.assign(proof.get("pids", [])) + if targets.is_empty(): + return false + + print("MCP | stale-occupant proof: %s" % str(proof.get("proof", ""))) + var freed_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return false + ## Warm the current-version uv env in parallel with the kill + port + ## drain below (#890 review P1): on the release that first ships this + ## code the OLD updater ran the update, so no click-time pre-warm + ## happened and the respawn would resolve cold — exactly the race + ## this episode exists to win. Detached fire-and-forget via the host + ## seam (stubbed in tests); worker-safe (CliFinder is mutex-guarded, + ## no EditorSettings access). + _host._prewarm_server_package(expected_version) + var killed: Array = _host._kill_processes_and_windows_spawn_children(targets, true) + if not killed.is_empty(): + print("MCP | killed pids %s on port %d" % [str(killed), port]) + _host._wait_for_port_free(port, wait_s) + return not bool(_host._is_port_in_use(port)) + ) + if _async_stale(async_gen) or freed_result == null: + return false + if not bool(freed_result): + return false + + _host._clear_managed_server_record() + _host._clear_pid_file() + return true + + +## Editor-exit teardown chooser (#800): detach only when the RUNNING +## server was launched keep-alive (_server_keep_alive, set at spawn / +## recovered on adoption) — never on the live setting, which may have +## been toggled after spawn. Flag clear → stop_server kills as always, +## so enabling the setting mid-session takes effect on the next server +## start instead of leaving a record that points at a soon-reaped PID. +func teardown_for_editor_exit() -> void: + if _server_keep_alive: + detach_server() + return + ## #824: a backend we spawned may be keeping one or more MCP clients alive + ## through their `godot-ai attach` bridges. Killing it because *this* editor + ## is closing takes the server out from under them: an in-flight call can + ## become TRANSPORT_OUTCOME_UNKNOWN, and every bridge has to establish a new + ## backend before the next editor can reconnect. A live lease means the + ## backend has consumers beyond this editor, so hand it over instead. + var leased := active_lease_count_at_exit() + if leased > 0: + ## Give up kill authority along with the process: dropping the managed + ## record means the next editor adopts it through the external branch + ## rather than as a managed server it may kill. The server's own + ## pid-file is deliberately left in place — it is the backend's + ## publication, not our claim on it, and adoption reads it. + ## + ## The Python side remains the reaper of record: a plugin-spawned + ## backend keeps its idle backstop armed (only keep_server_on_exit + ## disarms it) and that backstop is lease-aware, so this defers the + ## stop to "no editors AND no leases AND grace elapsed" rather than + ## leaking the process. + _host._clear_managed_server_record() + detach_server( + "detaching server: %d attach lease(s) still held, leaving it to the " + % leased + + "server's own idle reaper" + ) + return + stop_server() + + +## Active attach-bridge leases on the backend this editor manages, or 0 when +## there is nothing to consult (#824). +## +## Returns 0 — preserving the historical kill-on-exit behavior — for every +## uncertain case: no managed PID, a probe that fails or times out, a server +## that does not identify as godot-ai, or one too old to publish the field. +## That direction is deliberate. A false 0 costs what today already costs +## (the backend is stopped and bridges reconnect); a false positive would +## leave a process running on a guess. +## +## Bounded by the status probe's own timeout (SERVER_STATUS_PROBE_TIMEOUT_MS), +## which is what keeps editor exit from hanging on a wedged HTTP server. +func active_lease_count_at_exit() -> int: + var pid := int(_server_pid) + if pid <= 0: + return 0 + ## Only a process we can still prove is our godot-ai server earns the + ## benefit of the doubt. The lease count comes from whoever answers on the + ## port, which is not by itself proof that it IS the process we are about + ## to stop — another editor's backend, or an attach-owned one, could hold + ## the port after ours died. Requiring the same alive+branded proof + ## `stop_server` uses before its kill closes that gap: without it, a + ## stranger's leases could talk this editor out of stopping its own server. + ## + ## Failing this check is harmless either way. A dead PID has nothing to + ## kill, and a recycled-but-unbranded PID is rejected by stop_server's own + ## gate (#686) — both land on the historical path. + if not _host._pid_alive_for_proof(pid): + return 0 + if not _host._pid_cmdline_is_godot_ai_for_proof(pid): + return 0 + return active_lease_count( + _host._probe_live_server_status_for_port(ClientConfigurator.http_port()) + ) + + +## Read the advisory lease count out of a `/godot-ai/status` payload. +## +## Gated on the payload identifying as godot-ai, so an unrelated process +## answering on the port cannot talk this editor out of a clean stop. A +## missing field means an older backend that predates #824; it reads as 0, +## which keeps that pairing on today's behavior. +static func active_lease_count(live: Dictionary) -> int: + if not _live_status_identifies_godot_ai(live): + return 0 + var raw: Variant = live.get("active_lease_count") + if raw == null: + return 0 + return maxi(0, int(raw)) + + +## keep_server_on_exit (#800): editor teardown that leaves the server +## running. Mirrors stop_server's bookkeeping — cancel in-flight async +## startup, stop the watch, settle on STOPPED — but kills nothing and +## PRESERVES the managed-server record + pid-file, so the next editor +## session's start_server walk adopts the survivor through the existing +## record-matches branch (#758/#774). Explicit stops (dock Restart, +## update reload) still route through stop_server and kill as before. +## `log_reason` names why the server is being left alive; the default is the +## keep_server_on_exit wording this function was written for. #824 reuses the +## same bookkeeping for the active-lease handover, and a shared log line would +## have reported the wrong cause for it. +func detach_server( + log_reason: String = "keep_server_on_exit: leaving server running" +) -> void: + _invalidate_async_startup() + _host._stop_server_watch() + var detached_pid := int(_server_pid) + _server_pid = -1 + _server_pid_published_elapsed_ms = 0 + transition_state(McpServerStateScript.STOPPED) + if detached_pid > 0: + print("MCP | %s (PID %d)" % [log_reason, detached_pid]) + + +func stop_server() -> void: + ## Cancel any in-flight async startup (#678): a suspended start_server + ## resuming after teardown must not resurrect state or spawn a server. + _invalidate_async_startup() + _host._stop_server_watch() + if int(_server_pid) <= 0: + transition_state(McpServerStateScript.STOPPED) + return + transition_state(McpServerStateScript.STOPPING) + ## Kill the tracked PID AND the real Python PID — they differ for the + ## uvx tier (the launcher exits before its child) and on Windows + ## `OS.kill` is `TerminateProcess` which doesn't walk the child tree. + var port := ClientConfigurator.http_port() + var killed: Array = [] + var candidates: Array[int] = [] + ## Re-verify the tracked PID at kill time (#686): nothing clears + ## `_server_pid` when the server dies mid-session (`check_server_health` + ## stops watching after SERVER_WATCH_MS), so hours later the kernel may + ## have recycled this PID to an unrelated process. Every other candidate + ## in this function is brand-gated; the tracked seed must be too. A false + ## negative is fail-safe: the port stays held and the record is preserved, + ## so the next start_server's drift branch retries the kill. + var tracked_pid := int(_server_pid) + if ( + tracked_pid > 0 + and _host._pid_alive_for_proof(tracked_pid) + and _host._pid_cmdline_is_godot_ai_for_proof(tracked_pid) + ): + candidates.append(tracked_pid) + var real_pid := int(_host._find_managed_pid(port)) + ## Add the real Python PID only if it isn't already tracked and proves out + ## as ours — re-appending an already-present PID just produces a duplicate + ## kill candidate. + if real_pid > 0 and not candidates.has(real_pid) and _host._pid_cmdline_is_godot_ai_for_proof(real_pid): + candidates.append(real_pid) + var listener_pids: Array = _host._find_all_pids_on_port(port) + for pid in listener_pids: + var listener_pid := int(pid) + if candidates.has(listener_pid): + continue + if _host._pid_cmdline_is_godot_ai_for_proof(listener_pid): + candidates.append(listener_pid) + killed = _host._kill_processes_and_windows_spawn_children(candidates) + if not killed.is_empty(): + print("MCP | stopped server (PID %s)" % str(killed)) + _server_pid = -1 + _server_keep_alive = false + _server_pid_published_elapsed_ms = 0 + _host._wait_for_port_free(port, 2.0) + ## Preserve record/pid-file when port is still held — the drift + ## branch on the next start_server retries the kill (#159 follow-up). + _host._finalize_stop_if_port_free(port) + transition_state(McpServerStateScript.STOPPED) + + ## Server's `_pydantic_core.pyd` hard-link is now released — sweep + ## stale uvx builds before they trip the next attach launcher. + UvCacheCleanup.purge_stale_builds() + + +## Kill the server, reset the re-entrancy guard so the re-enabled plugin +## spawns fresh (#132). User-mode only kills via strong proof. +func prepare_for_update_reload() -> void: + stop_server() + _host._server_started_this_session = false + if ClientConfigurator.is_dev_checkout(): + return + + var port := ClientConfigurator.http_port() + if not bool(_host._is_port_in_use(port)): + return + + var proof: Dictionary = _host._evaluate_strong_port_occupant_proof(port) + var targets: Array[int] = [] + targets.assign(proof.get("pids", [])) + if targets.is_empty(): + return + + _host._kill_processes_and_windows_spawn_children(targets) + _host._wait_for_port_free(port, 3.0) + if not bool(_host._is_port_in_use(port)): + _host._clear_managed_server_record() + _host._clear_pid_file() + + +# ---- Recovery click ---------------------------------------------------- + +## Returns true when a pure-state probe says recovery is allowed: +## current state is INCOMPATIBLE, the port is still held, and the +## incompatible diagnosis latched an ownership proof. Pure-state in the +## sense that nothing is killed — that's `recover_incompatible_server`. +## +## Consults the `_can_recover_incompatible` verdict that +## `_set_incompatible_server` computed off-thread instead of re-running +## the proof's port scrapes + per-PID brand shells on the main thread +## (#712): the dock polls this on refresh, and +## `recover_incompatible_server` re-proves at kill time anyway, so a +## stale latch can never kill an unproven occupant — worst case is a +## recovery click that comes back false. The port liveness re-check is +## a single local bind probe, cheap enough to stay synchronous. +func can_recover_incompatible_server() -> bool: + if _server_state != McpServerStateScript.INCOMPATIBLE: + return false + if not _can_recover_incompatible: + return false + return bool(_host._is_port_in_use(ClientConfigurator.http_port())) + + +func recover_incompatible_server(stale_version: String = "") -> bool: + if _recovery_in_flight: + return false + _recovery_in_flight = true + var recovered := await _recover_incompatible_server_impl(stale_version) + _recovery_in_flight = false + return recovered + + +func _recover_incompatible_server_impl(stale_version: String = "") -> bool: + if _server_state != McpServerStateScript.INCOMPATIBLE: + return false + + var port := ClientConfigurator.http_port() + ## Cancel any suspended contended-port walk BEFORE the off-thread proof + ## (#712): `_run_blocking` tracks a single active worker for the + ## teardown join, so starting ours while another walk's worker is alive + ## would orphan that thread from the join guarantee. This also releases + ## the guard so the respawn at the bottom isn't silently swallowed + ## (#682 review). The user's recovery click owns the flow from here. + _invalidate_async_startup() + var async_gen := _async_generation + ## EditorSettings record read on the main thread, injected so the + ## worker never touches EditorSettings (#712, mirroring + ## recover_strong_port_occupant). + var record: Dictionary = _host._read_managed_server_record() + var proof_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return {"proof": "", "pids": []} + var live: Dictionary = {} + if not stale_version.is_empty(): + ## Automatic recovery was authorized by a handshake from this exact + ## old version. Re-probe at proof time and refuse if that occupant has + ## already been replaced; a delayed old handshake must never target the + ## freshly-started current server via its new pid-file proof. + live = _host._probe_live_server_status_for_port(port) + var current_live_version := str(_host._verified_status_version(live)) + if current_live_version != stale_version: + return {"proof": "", "pids": []} + return _host._evaluate_recovery_port_occupant_proof(port, live, record) + ) + if _async_stale(async_gen) or proof_result == null: + return false + var proof: Dictionary = proof_result + var targets: Array[int] = [] + targets.assign(proof.get("pids", [])) + if targets.is_empty(): + return false + print("MCP | proof: %s" % str(proof.get("proof", ""))) + + ## Move into STOPPING so the post-kill respawn passes the + ## first-writer-wins guards. + transition_state(McpServerStateScript.STOPPING) + ## Main-thread read for the worker below (EditorSettings-backed). + var recovery_expected_version := _expected_server_version() + var freed_result: Variant = await _run_blocking(func() -> Variant: + if not is_instance_valid(_host): + return false + ## Warm the current-version uv env in parallel with the kill + drain + ## so the respawn below wins the bind race even when no click-time + ## pre-warm ran (#890 review P1 — the transition release's update runs + ## the OLD updater). Same rationale and seam as + ## recover_stale_port_occupant. + _host._prewarm_server_package(recovery_expected_version) + ## verify_brand=true: the proof above ran in a separate + ## _run_blocking task with main-thread frames in between — re-check + ## each target at kill time so a PID recycled inside that gap isn't + ## killed (#686, mirroring recover_strong_port_occupant). + var killed: Array = _host._kill_processes_and_windows_spawn_children(targets, true) + if not killed.is_empty(): + print("MCP | killed pids %s on port %d" % [str(killed), port]) + _host._wait_for_port_free(port, 5.0) + return not bool(_host._is_port_in_use(port)) + ) + if _async_stale(async_gen) or freed_result == null: + return false + if not bool(freed_result): + ## Kill failed; re-latch INCOMPATIBLE so the dock keeps the + ## diagnostic UI. + transition_state(McpServerStateScript.INCOMPATIBLE) + return false + + UvCacheCleanup.purge_stale_builds() + _host._clear_managed_server_record() + _host._clear_pid_file() + transition_state(McpServerStateScript.STOPPED) + _connection_blocked = false + _server_status_message = "" + _conflict_port = 0 + _server_actual_version = "" + _server_actual_name = "" + _can_recover_incompatible = false + _host._server_started_this_session = false + _server_pid = -1 + _server_pid_published_elapsed_ms = 0 + ## Await the respawn walk: the plugin gates its connection unblock on + ## the post-walk state (SPAWNING/READY), so returning true while the + ## walk is still suspended would leave the connection blocked forever + ## after a successful recovery click (#682 review). + ## NOTE: arming the stale-recovery budget for the click lives in the + ## plugin wrapper (`plugin.gd::recover_incompatible_server`), NOT here — + ## the automatic handshake-mismatch trigger reuses this manager flow and + ## must only SPEND budget; re-arming inside it would unbound the + ## kill/respawn loop against a persistent bridge respawner. + ## Keep the outer transaction armed while the respawn walk runs so stale WS + ## handshakes and unrelated recovery calls still coalesce. Grant only this + ## owned startup walk permission to spend a remaining recovery round if the + ## old attach bridge reclaims the port between the kill and the respawn. + var owned_startup_gen := _async_generation + _recovery_owned_startup_generation = owned_startup_gen + await start_server() + if _recovery_owned_startup_generation == owned_startup_gen: + _recovery_owned_startup_generation = -1 + return true + + +## Restart authorisation — a live PID means we spawned/adopted, a +## non-empty managed record is the cross-session proof used by the +## drift branch. +func can_restart_managed_server() -> bool: + if _server_pid > 0: + return true + var record: Dictionary = _host._read_managed_server_record() + return not str(record.get("version", "")).is_empty() + + +func has_managed_server() -> bool: + return _server_pid > 0 + + +## Reset state for a force-restart. Drops the managed record, clears +## the pid-file, and resets the spawn guard so the follow-up +## `start_server()` walks the spawn arm. +func reset_for_force_restart() -> void: + ## The user's explicit restart takes over: cancel any suspended + ## contended-port walk and release the re-entrancy guard so the + ## follow-up start isn't silently swallowed (#682 review). + _invalidate_async_startup() + _host._clear_managed_server_record() + _host._clear_pid_file() + _host._server_started_this_session = false + _server_pid = -1 + transition_state(McpServerStateScript.UNINITIALIZED) + + +## Ownership-checked kill of the port occupant + respawn. Driven from +## the dock's "Restart Server" button when the plugin adopted a foreign +## server whose version drifted from the plugin. +func force_restart_server() -> void: + if not can_restart_managed_server(): + push_warning("MCP | refusing to kill server on port %d without managed-server ownership proof" + % ClientConfigurator.http_port()) + return + var port := ClientConfigurator.http_port() + ## Kill every LISTENER on the port, not just the first one. A dev + ## server run via `uvicorn --reload` owns port 8000 through both a + ## reloader parent AND a worker child — killing only one (or zero, + ## if the single-pid parse fell over on multi-line lsof output) leaves + ## the other holding the port past `_wait_for_port_free`'s window. + ## + ## Brand-gate each raw listener PID (#686): `can_restart_managed_server()` + ## only proves we once managed *a* server, not that the port's current + ## occupants are ours — an adopted server that exited on its own can be + ## replaced on the port by an unrelated dev tool before the user clicks + ## Restart. Unbranded PIDs fall through to `_set_incompatible_server` + ## below instead of being killed. + transition_state(McpServerStateScript.STOPPING) + var restart_targets: Array[int] = [] + for pid in _host._find_all_pids_on_port(port): + var listener_pid := int(pid) + if _host._pid_cmdline_is_godot_ai_for_proof(listener_pid): + restart_targets.append(listener_pid) + _host._kill_processes_and_windows_spawn_children(restart_targets) + _host._wait_for_port_free(port, 5.0) + if _host._is_port_in_use(port): + ## Kill failed; clean baseline for the follow-up + ## `_set_incompatible_server`. + transition_state(McpServerStateScript.UNINITIALIZED) + _set_incompatible_server( + _host._probe_live_server_status_for_port(port), + _expected_server_version(), + port + ) + return + ## Same rationale as `stop_server`: the server child python just + ## released its `pydantic_core` mapping, so this is the only window in + ## which the hard-linked copies under `builds-v0\.tmp*` are deletable. + ## Sweep before respawning so the next uvx attach build doesn't + ## inherit the same cleanup-failure path that triggered the restart. + UvCacheCleanup.purge_stale_builds() + reset_for_force_restart() + start_server() diff --git a/addons/godot_ai/utils/server_lifecycle.gd.uid b/addons/godot_ai/utils/server_lifecycle.gd.uid new file mode 100644 index 0000000..8e62667 --- /dev/null +++ b/addons/godot_ai/utils/server_lifecycle.gd.uid @@ -0,0 +1 @@ +uid://bwfx8b0w2mgf6 diff --git a/addons/godot_ai/utils/server_version_check.gd b/addons/godot_ai/utils/server_version_check.gd new file mode 100644 index 0000000..4bb1371 --- /dev/null +++ b/addons/godot_ai/utils/server_version_check.gd @@ -0,0 +1,126 @@ +@tool +class_name McpServerVersionCheck +extends RefCounted + +## Standalone polling seam for the post-connection server-version +## handshake gate. Extracted from `plugin.gd` so the lifecycle manager +## stays focused on spawn/adopt/stop and the version-verify dance has +## its own home. +## +## The seam itself does NOT transition `McpServerState` on arm/disarm — +## the version check runs concurrently with whatever spawn-state the +## caller had latched (typically FOREIGN_PORT during adoption +## confirmation, or no-op directly to READY for a fresh spawn). Result +## transitions land on the manager via `handle_server_version_verified` +## (READY / INCOMPATIBLE) or `handle_server_version_unverified` +## (INCOMPATIBLE on deadline expiry); arm() leaves the state alone so a +## FOREIGN_PORT diagnosis isn't accidentally cleared before the +## handshake actually arrives. +## +## Owns the deadline timer (`_deadline_ms`) and requires the manager to +## feed it `tick(now_msec)` from the plugin's `_process` while +## `is_active()` is true. +## +## Decoupled from the connection's signal surface: `tick()` polls +## `_connection.is_connected` and `_connection.server_version` directly. +## A same-release signal addition plus a new consumer is shape-coupled work +## for old two-phase runners; they can parse the consumer while the +## McpConnection Script object still reflects v(N). We still null-check +## `_connection` because `disarm()` releases it. + +## How long to wait after the WebSocket opens before declaring the +## handshake_ack overdue. This is the sole owner of the 5s budget +## — kept at this layer so the version-check seam is self-contained. +const TIMEOUT_MS := 5 * 1000 + +## Untyped on purpose for the same self-update field-storage reason +## plugin.gd's fields are untyped. `_connection` is the live +## `McpConnection`; `_manager` is `McpServerLifecycleManager`. +## `_connection` is null between disarm() and the next arm() — the +## seam can spend most of the plugin's life dormant and we don't want +## to pin a Node that may be queue_freed in `_exit_tree`. `_manager` is +## set once at construction and held for the seam's lifetime (the +## manager owns this instance, so the cycle is short). +var _connection +var _manager +var _active: bool = false +var _deadline_ms: int = 0 +var _expected_version: String = "" + + +func _init(manager) -> void: + _manager = manager + + +## Arm the version-check. Marks the seam active, (re)attaches the +## connection it should poll, and starts watching for +## `_connection.server_version`. Does NOT transition manager state — +## the version check runs concurrently with whatever spawn-state was +## latched (e.g. FOREIGN_PORT during adoption confirmation, READY for +## a fresh spawn). Result transitions land on the manager via +## `handle_server_version_verified` / `_unverified` once the handshake +## (or its deadline) lands. +## +## The deadline starts the moment the connection actually opens, not at +## arm-time, because uvx cold-starts can take ~30s to bind the +## WebSocket and we don't want to count that against the handshake. +func arm(connection, expected_version: String) -> void: + _active = true + _deadline_ms = 0 + _expected_version = expected_version + _connection = connection + + +## Disarm without firing a verdict. Used when the manager moves on +## (e.g. recovery click → STOPPING). Releases the connection / +## manager references so the seam doesn't pin them past the active +## window — the plugin can spend most of its life with the version +## check disarmed, and `_connection` is a Node that may be queue_free'd +## by `_exit_tree`. Caller has already transitioned state, so we don't +## touch the manager. +func disarm() -> void: + _active = false + _deadline_ms = 0 + _connection = null + + +## True while the version-check needs `_process` ticks. Plugin uses +## this to gate `set_process(true)`. +func is_active() -> bool: + return _active + + +## Per-frame tick from the plugin's `_process`. No-op when disarmed. +## Returns true when the check finished this tick (verified or +## unverified) so the plugin can re-evaluate `set_process` enable. +func tick(now_msec: int) -> bool: + if not _active: + return false + if _connection == null: + return false + if not bool(_connection.is_connected): + return false + if _deadline_ms == 0: + _deadline_ms = now_msec + TIMEOUT_MS + var server_version := str(_connection.server_version) + if not server_version.is_empty(): + _complete_with_version(server_version) + return true + if now_msec >= _deadline_ms: + _complete_unverified() + return true + return false + + +func _complete_with_version(version: String) -> void: + _active = false + _deadline_ms = 0 + if _manager != null: + _manager.handle_server_version_verified(_expected_version, version) + + +func _complete_unverified() -> void: + _active = false + _deadline_ms = 0 + if _manager != null: + _manager.handle_server_version_unverified(_expected_version) diff --git a/addons/godot_ai/utils/server_version_check.gd.uid b/addons/godot_ai/utils/server_version_check.gd.uid new file mode 100644 index 0000000..7baacfd --- /dev/null +++ b/addons/godot_ai/utils/server_version_check.gd.uid @@ -0,0 +1 @@ +uid://ciqldbuaq8i8u diff --git a/addons/godot_ai/utils/settings.gd b/addons/godot_ai/utils/settings.gd new file mode 100644 index 0000000..9ce2c68 --- /dev/null +++ b/addons/godot_ai/utils/settings.gd @@ -0,0 +1,135 @@ +@tool +class_name McpSettings +extends RefCounted + +## Shared EditorSettings key constants for the godot_ai/* namespace. +## +## Centralised here so lightweight files (e.g. telemetry.gd) can reference +## settings keys without pulling in the full client_configurator.gd dep tree. +## All keys must keep their raw string values stable across releases because +## they are persisted in the user's editor_settings-4.tres. + +const SETTING_HTTP_PORT := "godot_ai/http_port" +## Comma-separated list of tool domains excluded from the server at spawn time. +const SETTING_EXCLUDED_DOMAINS := "godot_ai/excluded_domains" +const SETTING_TELEMETRY_ENABLED := "godot_ai/telemetry_enabled" +## Comma-separated CIDRs / bare IPs passed to the server as `--allow-host` +## at spawn time (#507, server core #421). Empty means loopback-only. +const SETTING_ALLOW_HOSTS := "godot_ai/allow_remote_hosts" +## Whether MCP log lines echo to the Godot console (dock "Log" toggle). +## The dock's ring-buffer log panel keeps recording regardless. +const SETTING_MCP_LOGGING := "godot_ai/mcp_logging" +## Which scope CLI-configured clients register the server in. Claude Code's +## `--scope user` writes the global block of ~/.claude.json, which that client +## loads in EVERY workspace — so the server gets spawned in unrelated, +## non-Godot projects. `project` writes /.mcp.json instead, so the +## entry travels with the project. Defaults to `user` to preserve the +## historical behaviour for existing installs. +const SETTING_CLIENT_SCOPE := "godot_ai/mcp_client_scope" + +## Scopes accepted for SETTING_CLIENT_SCOPE. These are the values the Claude +## Code CLI's `--scope` flag takes; an unrecognised setting falls back to +## DEFAULT_CLIENT_SCOPE rather than passing junk to the CLI. +const CLIENT_SCOPES := ["user", "project", "local"] +const DEFAULT_CLIENT_SCOPE := "user" + + +## Returns true if the string value is truthy +## ("1", "true", "yes", "on", case-insensitive, whitespace-trimmed). +static func truthy(value: String) -> bool: + return value.strip_edges().to_lower() in ["1", "true", "yes", "on"] + + +## Returns true if the named environment variable is set to a truthy value. +static func env_truthy(var_name: String) -> bool: + return truthy(OS.get_environment(var_name)) + + +## #691: EditorInterface / EditorSettings are not thread-safe, and the dock +## runs Configure / Remove on a worker Thread (mcp_dock.gd +## `_run_client_action_worker` -> McpClientConfigurator -> McpCliStrategy +## `_format_args` -> client_scope()). Same contract as +## McpClientConfigurator._editor_setting_lookup: the main thread does a live +## read and refreshes the snapshot; worker threads read the snapshot only, so +## a never-warmed value reads as null (unset) rather than touching +## EditorInterface off-thread. Warmed on the main thread by +## McpClientConfigurator.warm_env_snapshot() before each worker dispatch. +## +## Kept here rather than reusing the configurator's `_editor_setting_lookup` +## so utils/settings.gd stays free of the client_configurator.gd dep tree — +## see this file's header. +static var _client_scope_snapshot: Variant = null +static var _client_scope_mutex := Mutex.new() + + +static func _client_scope_setting() -> Variant: + if OS.get_thread_caller_id() == OS.get_main_thread_id(): + var live: Variant = null + if Engine.is_editor_hint(): + var es := EditorInterface.get_editor_settings() + if es != null and es.has_setting(SETTING_CLIENT_SCOPE): + live = es.get_setting(SETTING_CLIENT_SCOPE) + _client_scope_mutex.lock() + _client_scope_snapshot = live + _client_scope_mutex.unlock() + return live + _client_scope_mutex.lock() + var cached: Variant = _client_scope_snapshot + _client_scope_mutex.unlock() + return cached + + +## Main-thread pre-warm of the scope snapshot so the dock's Configure/Remove +## worker resolves `{scope}` from a value captured while EditorSettings access +## was safe. Idempotent; called from warm_env_snapshot(). +static func warm_client_scope() -> void: + _client_scope_setting() + + +## Returns the scope CLI clients should register the MCP server in, as +## substituted into `{scope}` in a descriptor's cli_register_template / +## cli_unregister_template. Safe to call from either thread (see +## _client_scope_setting). Unrecognised values fall back to +## DEFAULT_CLIENT_SCOPE so a hand-edited editor_settings-4.tres can never make +## the plugin shell out with a bad flag. +static func client_scope() -> String: + var value: Variant = _client_scope_setting() + ## String(null) is a hard error (#850) — an unset/never-warmed key must + ## short-circuit before the cast. + if value == null: + return DEFAULT_CLIENT_SCOPE + var raw := String(value).strip_edges().to_lower() + if raw in CLIENT_SCOPES: + return raw + return DEFAULT_CLIENT_SCOPE + + +## Returns true if telemetry should be active, checking in priority order: +## 1. GODOT_AI_DISABLE_TELEMETRY / DISABLE_TELEMETRY env vars +## 2. The godot_ai/telemetry_enabled EditorSetting written by the dock UI +## Defaults to true when neither source has set a preference. +static func telemetry_enabled() -> bool: + if env_truthy("GODOT_AI_DISABLE_TELEMETRY") or env_truthy("DISABLE_TELEMETRY"): + return false + var es := EditorInterface.get_editor_settings() + if es != null and es.has_setting(SETTING_TELEMETRY_ENABLED): + return bool(es.get_setting(SETTING_TELEMETRY_ENABLED)) + return true + + +## Returns whether MCP log lines should echo to the Godot console. Read at +## plugin startup (to apply the persisted choice to the log buffer and +## dispatcher) and by the dock's LogViewer toggle for its initial state. +## Defaults to true when the user has never touched the toggle. +static func mcp_logging_enabled() -> bool: + var es := EditorInterface.get_editor_settings() + if es != null and es.has_setting(SETTING_MCP_LOGGING): + return bool(es.get_setting(SETTING_MCP_LOGGING)) + return true + + +## Persist the dock "Log" toggle so the choice survives editor restarts (#626). +static func set_mcp_logging_enabled(enabled: bool) -> void: + var es := EditorInterface.get_editor_settings() + if es != null: + es.set_setting(SETTING_MCP_LOGGING, enabled) diff --git a/addons/godot_ai/utils/settings.gd.uid b/addons/godot_ai/utils/settings.gd.uid new file mode 100644 index 0000000..b8b1547 --- /dev/null +++ b/addons/godot_ai/utils/settings.gd.uid @@ -0,0 +1 @@ +uid://pefrtofs7ijw diff --git a/addons/godot_ai/utils/structured_log_ring.gd b/addons/godot_ai/utils/structured_log_ring.gd new file mode 100644 index 0000000..3e00b4e --- /dev/null +++ b/addons/godot_ai/utils/structured_log_ring.gd @@ -0,0 +1,156 @@ +@tool +class_name McpStructuredLogRing +extends RefCounted + +## Head-indexed circular buffer of structured log entries shared by +## game_log_buffer and editor_log_buffer. +## +## Once `_max_lines` (set in subclass `_init`) is reached, new appends +## overwrite the oldest slot at `_head`, keeping append O(1) on overflow +## — the previous slice() approach reallocated the full retained array +## on every drop, which a chatty game would pay for thousands of times +## per second. +## +## Lockless. Subclasses needing thread-safety (editor_log_buffer is +## written from any thread a Godot Logger virtual can fire on) wrap each +## public method with their own Mutex around the `_*_unlocked` helpers. +## Keeping the base lockless means the hot game-side path (single thread, +## called from _process) doesn't pay an unused mutex cost. +## +## Entry shape is owned by subclasses — `_append_entry` takes a +## ready-built Dictionary so each buffer can carry the fields it needs +## (game: `source/level/text`; editor: adds `path/line/function`). + +const VALID_LEVELS := ["info", "warn", "error"] + +var _max_lines: int +var _storage: Array[Dictionary] = [] +## Next write position within `_storage`. While filling (before first +## wrap) equals `_storage.size()`; once full, points at the oldest entry +## (the one about to be overwritten). +var _head := 0 +var _dropped_count := 0 +## Monotonic number of entries appended since this ring was created. Unlike +## `_storage.size()` and `_dropped_count`, this intentionally survives clear() +## so callers can use it as a stable "next entry to read" cursor. +var _appended_total := 0 + + +func _init(max_lines: int) -> void: + _max_lines = max_lines + + +## Append `entry` to the ring, evicting the oldest slot when full. +## Subclasses build the dict with their per-source shape and pass it in. +func _append_entry(entry: Dictionary) -> void: + if _storage.size() < _max_lines: + _storage.append(entry) + _head = _storage.size() % _max_lines + else: + ## Full — overwrite oldest in place, advance head, count the drop. + _storage[_head] = entry + _head = (_head + 1) % _max_lines + _dropped_count += 1 + _appended_total += 1 + + +## Lockless slice. Subclasses with a mutex wrap their `get_range` / +## `get_recent` overrides around this; the lockless base implementations +## of those public methods just delegate here. +func _get_range_unlocked(offset: int, count: int) -> Array[Dictionary]: + var size := _storage.size() + var start := maxi(0, offset) + var stop := mini(size, start + count) + var out: Array[Dictionary] = [] + for i in range(start, stop): + out.append(_storage[_logical_to_physical(i)]) + return out + + +func get_range(offset: int, count: int) -> Array[Dictionary]: + return _get_range_unlocked(offset, count) + + +func get_recent(count: int) -> Array[Dictionary]: + var size := _storage.size() + var start := maxi(0, size - count) + return _get_range_unlocked(start, size - start) + + +## Lockless cursor read. The cursor is the next sequence to read: calling +## get_since(appended_total()) after a snapshot returns only later appends. +func _get_since_unlocked(since_seq: int, limit: int = -1) -> Dictionary: + var size := _storage.size() + var oldest_seq := _appended_total - size + var start_seq := mini(maxi(since_seq, oldest_seq), _appended_total) + var start := start_seq - oldest_seq + var available := maxi(0, size - start) + var count := available + if limit >= 0: + count = mini(available, limit) + var entries := _get_range_unlocked(start, count) + var next_cursor := start_seq + entries.size() + return { + "cursor": since_seq, + "oldest_cursor": oldest_seq, + "next_cursor": next_cursor, + "appended_total": _appended_total, + "truncated": since_seq < oldest_seq, + "has_more": next_cursor < _appended_total, + "entries": entries, + } + + +func get_since(since_seq: int, limit: int = -1) -> Dictionary: + return _get_since_unlocked(since_seq, limit) + + +## Lockless accessors. Subclasses with a mutex use these under their lock +## so the field reads stay encapsulated in the base instead of leaking +## `_storage` / `_dropped_count` reach-through into the subclass. +func _total_count_unlocked() -> int: + return _storage.size() + + +func _dropped_count_unlocked() -> int: + return _dropped_count + + +func _appended_total_unlocked() -> int: + return _appended_total + + +func total_count() -> int: + return _total_count_unlocked() + + +func dropped_count() -> int: + return _dropped_count_unlocked() + + +func appended_total() -> int: + return _appended_total_unlocked() + + +## Translate a logical index (0 = oldest retained) to a physical +## `_storage` slot. Before the first wrap, storage-order is logical- +## order. After wrapping, the oldest entry lives at `_head`. +func _logical_to_physical(logical: int) -> int: + if _storage.size() < _max_lines: + return logical + return (_head + logical) % _max_lines + + +## Reset the ring to empty. Subclasses with a mutex wrap this with their +## lock; subclasses that surface `clear` to callers (McpEditorLogBuffer) +## return the prior size from their wrapper. +func _clear_storage() -> void: + _storage.clear() + _head = 0 + _dropped_count = 0 + + +## Coerce unknown levels to "info" so a misbehaving sender can't poison +## downstream filters with arbitrary strings. +static func _coerce_level(level: String) -> String: + return level if level in VALID_LEVELS else "info" diff --git a/addons/godot_ai/utils/structured_log_ring.gd.uid b/addons/godot_ai/utils/structured_log_ring.gd.uid new file mode 100644 index 0000000..57012ba --- /dev/null +++ b/addons/godot_ai/utils/structured_log_ring.gd.uid @@ -0,0 +1 @@ +uid://c4yh3jqfn6dwe diff --git a/addons/godot_ai/utils/surfaced_error_tracker.gd b/addons/godot_ai/utils/surfaced_error_tracker.gd new file mode 100644 index 0000000..5bd3022 --- /dev/null +++ b/addons/godot_ai/utils/surfaced_error_tracker.gd @@ -0,0 +1,642 @@ +@tool +class_name McpSurfacedErrorTracker +extends RefCounted + +## Central source for "errors the agent should know exist". +## +## Editor log cursors only cover McpEditorLogBuffer. Runtime errors from the +## game subprocess can land solely in the Debugger Errors tab, so this tracker +## promotes visible Debugger-tab rows into a monotonic sequence before the +## dispatcher stamps a watermark on each response envelope. + +const MAX_PROMOTED_DEBUGGER_ENTRIES := 500 +const MAX_PROMOTED_DEBUGGER_KEYS := 5000 +const DEBUGGER_REFRESH_MIN_INTERVAL_MS := 250 +const DEBUGGER_SCAN_AFTER_STOP_MS := 5000 +## #641: delays for the self-scheduled forced scans armed on run stop (and on +## game-helper hello, via McpDebuggerPlugin). Two ticks: an early one for rows +## the remote debugger delivers right around the event, and a late one past +## Godot's per-frame Errors-tab insertion throttle for error floods. +const DEFERRED_SCAN_DELAYS_SEC: Array[float] = [1.0, 5.0] +## #635: cap on accounted per-key row-time signatures. The live Errors tab is +## itself bounded, so this only guards a pathological flood of same-keyed rows +## with distinct time texts; past the cap the set resets to the current scan. +const MAX_ACCOUNTED_ROW_TIMES_PER_KEY := 512 + +var _editor_log_buffer +var _game_log_buffer +var _debugger_errors_root: Node +var _debugger_search_root_cache: Node +var _promoted_debugger_keys: Dictionary = {} +## #635: per-key set of Errors-tab row time texts already promoted, so a row +## observed after a clear+repopulate that no scan saw as empty still counts as +## new (see the re-promotion comment in refresh_debugger_errors). +var _promoted_debugger_row_times: Dictionary = {} +var _promoted_debugger_key_order: Array[String] = [] +var _promoted_debugger_entries: Array[Dictionary] = [] +var _debugger_promoted_total := 0 +var _run_seq := 0 +var _oldest_retained_debugger_sequence := 1 +var _last_debugger_refresh_msec := -DEBUGGER_REFRESH_MIN_INTERVAL_MS +var _debugger_scan_active := false +var _debugger_scan_until_msec := 0 +var _deferred_scans_scheduled_total := 0 + + +func _init(editor_log_buffer = null, game_log_buffer = null, debugger_errors_root: Node = null) -> void: + _editor_log_buffer = editor_log_buffer + _game_log_buffer = game_log_buffer + _debugger_errors_root = debugger_errors_root + + +func note_game_run_started(sticky_scan: bool = true) -> void: + _run_seq += 1 + _debugger_scan_active = sticky_scan + _debugger_scan_until_msec = 0 + if not sticky_scan: + _debugger_scan_until_msec = Time.get_ticks_msec() + DEBUGGER_SCAN_AFTER_STOP_MS + refresh_debugger_errors(true) + + +func note_game_run_stopped() -> void: + _debugger_scan_active = false + _debugger_scan_until_msec = Time.get_ticks_msec() + DEBUGGER_SCAN_AFTER_STOP_MS + schedule_deferred_scans() + + +## #641: promotion into the watermark used to depend on a tool call arriving +## while the scan gate was open (run active, or within DEBUGGER_SCAN_AFTER_STOP_MS +## of stop). Boot parse errors that landed in the Errors tab with no tool call +## in that window were never promoted, so the agent never got the +## new_errors_since_last_call hint. These editor-side timers force a scan +## regardless of tool-call cadence; the next stamped response then carries the +## already-promoted count even after the gate closes. Scans are content-keyed +## and idempotent, so a timer firing after an unrelated new run is harmless. +func schedule_deferred_scans(delays: Array = DEFERRED_SCAN_DELAYS_SEC) -> void: + var tree := Engine.get_main_loop() as SceneTree + if tree == null: + return + for delay in delays: + var timer := tree.create_timer(maxf(0.05, float(delay))) + timer.timeout.connect(_on_deferred_scan_timeout) + _deferred_scans_scheduled_total += 1 + + +func deferred_scans_scheduled_total() -> int: + return _deferred_scans_scheduled_total + + +func _on_deferred_scan_timeout() -> void: + refresh_debugger_errors(true) + + +func refresh_debugger_errors(force: bool = true) -> void: + var now := Time.get_ticks_msec() + if not force and not _should_scan_debugger_for_cached_watermark(now): + return + _last_debugger_refresh_msec = now + var current_by_key: Dictionary = {} + for entry in _raw_debugger_error_entries(): + if str(entry.get("level", "")) != "error": + continue + var key := _log_entry_key(entry) + var info: Dictionary = current_by_key.get(key, {"count": 0, "entry": entry, "times": {}}) + info["count"] = int(info.get("count", 0)) + 1 + var time_text := _row_time_text(entry) + if not time_text.is_empty(): + (info["times"] as Dictionary)[time_text] = true + current_by_key[key] = info + for key in _promoted_debugger_keys.keys(): + if not current_by_key.has(key): + _promoted_debugger_keys[key] = 0 + for key in current_by_key.keys(): + var info: Dictionary = current_by_key[key] + var current := int(info.get("count", 0)) + var stored := int(_promoted_debugger_keys.get(key, 0)) + ## #635: a count increase alone misses rows observed after a run + ## boundary. Godot clears the Errors tab at run start; when the new run + ## re-fires an error identical to one promoted before the clear, and no + ## scan happened to observe the tab empty in between, the per-key count + ## never dips — so the row kept its pre-run sequence and run-scoping + ## (editor_entries_since against the run-start cursor) misclassified an + ## in-run error as retained_recent. Each Errors-tab row carries its own + ## time text; an unaccounted (key, time) signature is a row we have not + ## promoted yet, so it earns a fresh sequence even at an equal or lower + ## count. Boundary condition: rows with an empty time text, or a + ## repopulated row whose time text is byte-identical to a pre-clear row, + ## fall back to count-only dedup and can still be missed. + var unseen_times := _unaccounted_row_times(key, info.get("times", {})) + var delta := current - stored + if delta <= 0 and not unseen_times.is_empty(): + delta = mini(unseen_times.size(), current) + if delta <= 0: + if current != stored: + _promoted_debugger_keys[key] = current + continue + if not _promoted_debugger_keys.has(key): + _promoted_debugger_key_order.append(key) + _promoted_debugger_keys[key] = current + _account_row_times(key, info.get("times", {})) + _debugger_promoted_total += delta + var source_entry: Dictionary = info.get("entry", {}) + var promoted := source_entry.duplicate(true) + promoted["_debugger_key"] = key + promoted["_debugger_occurrences"] = current + promoted["_debugger_sequence"] = _debugger_promoted_total + _remove_promoted_debugger_entry(key) + _promoted_debugger_entries.append(promoted) + _trim_promoted_debugger_entries() + _trim_promoted_debugger_key_counts() + + +## #645: promote an error record that has no Errors-tab row to scrape — e.g. a +## boot-time parse error that parked the game in a remote-debugger break before +## any surface got a record. The entry joins the same promoted sequence as +## scraped Debugger rows, so run-scoping (editor_entries_since), the retained +## fallback, and the response watermark all see it with no extra plumbing. +## Re-recording the same key later (the same script still broken on the next +## run) re-promotes it with a fresh sequence, mirroring how re-appearing +## Errors-tab rows behave; scan reconciliation zeroes the key's count once the +## break ends since the row never exists in the live tab. +func record_synthetic_error(entry: Dictionary) -> void: + var key := _log_entry_key(entry) + var occurrences := int(_promoted_debugger_keys.get(key, 0)) + 1 + if not _promoted_debugger_keys.has(key): + _promoted_debugger_key_order.append(key) + _promoted_debugger_keys[key] = occurrences + _debugger_promoted_total += 1 + var promoted := entry.duplicate(true) + promoted["_debugger_key"] = key + promoted["_debugger_occurrences"] = occurrences + promoted["_debugger_sequence"] = _debugger_promoted_total + promoted["_debugger_synthetic"] = true + _remove_promoted_debugger_entry(key) + _promoted_debugger_entries.append(promoted) + _trim_promoted_debugger_entries() + _trim_promoted_debugger_key_counts() + + +## Monotonicity contract (#767): run_seq and the session-scoped components +## (editor_ring, debugger_promoted, editor_ring_warn) must NEVER decrease +## within an editor session, and the per-run components (game_error_warn, +## game_warn) must never decrease within a run — they may reset only when +## run_seq increments in the same stamp (the run boundary that rotates the +## game buffer's counters). Released servers diff consecutive stamps +## (websocket.py::_sync_error_watermark_for_session) and treat any other +## decrease as a counter reset, counting the FULL current value as new — one +## dip makes every old server out there over-report errors. Any future +## hold/classification feature must therefore DEFER an increment until its +## entry is released, never subtract an already-stamped one: a stamp like +## `raw_total - currently_held_entries` is exactly the regression this +## guards against. Producer-side coverage: +## test_editor.gd::test_surfaced_error_tracker_watermark_components_never_decrease. +func watermark(force_debugger_scan: bool = false) -> Dictionary: + refresh_debugger_errors(force_debugger_scan) + return { + "run_seq": _run_seq, + "editor_ring": _error_appended_total(), + "debugger_promoted": _debugger_promoted_total, + ## Historically misnamed: carries game-process ERROR counts only. + "game_error_warn": _game_error_total(), + ## Warn-level components, parallel to the error counts above. The server + ## diffs these into `new_warnings_since_last_call` so a warning-only run + ## surfaces instead of reading as clean. Debugger Errors-tab warning rows + ## are not promoted here yet (buffers cover push_warning from the game and + ## editor parse/@tool warnings) — tracked as a follow-up. + "editor_ring_warn": _warn_appended_total(), + "game_warn": _game_warn_total(), + } + + +static func stamp_watermark(response: Dictionary, tracker) -> void: + if tracker == null: + return + if not tracker.has_method("watermark"): + return + response["error_watermark"] = tracker.watermark() + + +func debugger_promoted_total(force_debugger_scan: bool = true) -> int: + refresh_debugger_errors(force_debugger_scan) + return _debugger_promoted_total + + +func collect_editor_log_entries() -> Array[Dictionary]: + refresh_debugger_errors(true) + var entries: Array[Dictionary] = [] + var seen_keys: Dictionary = {} + if _editor_log_buffer != null: + for entry in _editor_log_buffer.get_range(0, _editor_log_buffer.total_count()): + seen_keys[_log_entry_key(entry)] = true + entries.append(entry) + for entry in read_debugger_error_entries(): + var key := _log_entry_key(entry) + if seen_keys.has(key): + continue + seen_keys[key] = true + entries.append(entry) + ## #645: synthesized break records have no live Errors-tab row to scrape — + ## merge them from the promoted list so logs_read(source="editor") shows + ## the record that run/game responses point at. + for entry in _promoted_debugger_entries: + if not bool(entry.get("_debugger_synthetic", false)): + continue + var key := _log_entry_key(entry) + if seen_keys.has(key): + continue + seen_keys[key] = true + entries.append(_strip_promotion_bookkeeping(entry)) + return entries + + +static func _strip_promotion_bookkeeping(entry: Dictionary) -> Dictionary: + var clean := entry.duplicate(true) + for key in ["_debugger_key", "_debugger_occurrences", "_debugger_sequence", "_debugger_synthetic"]: + clean.erase(key) + return clean + + +func editor_entries_since(editor_cursor: int, debugger_cursor: int, force_debugger_scan: bool = true) -> Dictionary: + refresh_debugger_errors(force_debugger_scan) + var entries: Array[Dictionary] = [] + var seen_keys: Dictionary = {} + var truncated := false + if _editor_log_buffer != null: + var captured: Dictionary = _editor_log_buffer.get_since(maxi(0, editor_cursor), -1) + truncated = bool(captured.get("truncated", false)) + for entry in captured.get("entries", []): + seen_keys[_log_entry_key(entry)] = true + entries.append(entry) + if debugger_cursor < _oldest_retained_debugger_sequence - 1: + truncated = true + for entry in _promoted_debugger_entries: + if int(entry.get("_debugger_sequence", 0)) <= debugger_cursor: + continue + var key := _log_entry_key(entry) + if seen_keys.has(key): + continue + seen_keys[key] = true + entries.append(entry) + return { + "entries": entries, + "truncated": truncated, + } + + +func retained_recent_editor_entries() -> Array[Dictionary]: + ## There is no shared timestamp across the editor logger ring and Godot's + ## Debugger Errors tree. Preserve the pre-PR fallback contract: newest + ## buffered editor entries first, then debugger-only rows that were not in + ## the ring, so stale Debugger rows cannot outrank newer ring entries. + var entries: Array[Dictionary] = [] + var seen_keys: Dictionary = {} + if _editor_log_buffer != null: + entries = _editor_log_buffer.get_recent(_editor_log_buffer.total_count()) + entries.reverse() + for entry in entries: + seen_keys[_log_entry_key(entry)] = true + for entry in collect_editor_log_entries(): + var key := _log_entry_key(entry) + if seen_keys.has(key): + continue + seen_keys[key] = true + entries.append(entry) + return entries + + +func read_debugger_error_entries() -> Array[Dictionary]: + var entries: Array[Dictionary] = [] + var seen_keys: Dictionary = {} + for entry in _raw_debugger_error_entries(): + var key := _log_entry_key(entry) + if seen_keys.has(key): + continue + seen_keys[key] = true + entries.append(entry) + return entries + + +func locate_debugger_error_trees() -> Array[Tree]: + var trees: Array[Tree] = [] + var root: Node = _debugger_errors_root + ## #641: a deferred-scan timer can outlive an injected root (tests, + ## teardown). A freed root must not fall through to the live editor UI — + ## that would promote unrelated real errors into a tracker scoped to the + ## dead root — so treat it as "nothing to scan". + if root != null and not is_instance_valid(root): + return trees + if root == null: + root = _debugger_search_root() + if root == null: + return trees + _collect_debugger_error_trees(root, trees) + return trees + + +func clear_debugger_error_trees() -> int: + var cleared := 0 + for tree in locate_debugger_error_trees(): + cleared += entries_from_debugger_error_tree(tree).size() + if not _press_debugger_clear_button(tree): + ## Synthetic roots in tests do not have Godot's Clear button. + tree.clear() + return cleared + + +func _debugger_search_root() -> Node: + if is_instance_valid(_debugger_search_root_cache): + return _debugger_search_root_cache + _debugger_search_root_cache = null + var base := EditorInterface.get_base_control() + if base == null: + return null + _debugger_search_root_cache = _find_first_of_class(base, "EditorDebuggerNode") + if _debugger_search_root_cache == null: + return base + return _debugger_search_root_cache + + +static func _find_first_of_class(node: Node, klass: String) -> Node: + if node.get_class() == klass: + return node + for child in node.get_children(): + var found := _find_first_of_class(child, klass) + if found != null: + return found + return null + + +static func _collect_debugger_error_trees(node: Node, out: Array[Tree]) -> void: + if node is Tree and _tree_has_debugger_errors(node as Tree): + out.append(node as Tree) + for child in node.get_children(): + if child is Node: + _collect_debugger_error_trees(child as Node, out) + + +static func _tree_has_debugger_errors(tree: Tree) -> bool: + var root := tree.get_root() + if root == null: + return false + var item := root.get_first_child() + while item != null: + if _is_debugger_error_item(item): + return true + item = item.get_next() + return false + + +static func _press_debugger_clear_button(tree: Tree) -> bool: + var parent := tree.get_parent() + if parent == null: + return false + var stack: Array[Node] = [parent] + while not stack.is_empty(): + var node: Node = stack.pop_back() + if node is BaseButton: + for conn in node.get_signal_connection_list("pressed"): + if str(conn.get("callable", "")).contains("_clear_errors_list"): + node.emit_signal("pressed") + return true + for child in node.get_children(): + stack.push_back(child) + return false + + +static func entries_from_debugger_error_tree(tree: Tree) -> Array[Dictionary]: + var entries: Array[Dictionary] = [] + var root := tree.get_root() + if root == null: + return entries + var item := root.get_first_child() + while item != null: + if _is_debugger_error_item(item): + entries.append(_entry_from_debugger_error_item(item)) + item = item.get_next() + return entries + + +static func _entry_from_debugger_error_item(item: TreeItem) -> Dictionary: + var title := item.get_text(1) + var loc := _location_from_metadata(item.get_metadata(0)) + var function := _function_from_title(title) + return { + "source": "editor", + "level": "warn" if item.has_meta("_is_warning") else "error", + "text": title, + "path": str(loc.get("path", "")), + "line": int(loc.get("line", 0)), + "function": function, + "details": _details_from_debugger_error_item(item, loc, function), + } + + +static func _details_from_debugger_error_item(item: TreeItem, loc: Dictionary, function: String) -> Dictionary: + var children: Array[Dictionary] = [] + var child := item.get_first_child() + while child != null: + var child_loc := _location_from_metadata(child.get_metadata(0)) + children.append({ + "label": child.get_text(0), + "text": child.get_text(1), + "path": str(child_loc.get("path", "")), + "line": int(child_loc.get("line", 0)), + }) + child = child.get_next() + return { + "debugger_tab": "Errors", + "time": item.get_text(0), + "message": item.get_text(1), + "error_type_name": "warning" if item.has_meta("_is_warning") else "error", + "source": { + "path": str(loc.get("path", "")), + "line": int(loc.get("line", 0)), + "function": function, + }, + "resolved": { + "path": str(loc.get("path", "")), + "line": int(loc.get("line", 0)), + "function": function, + }, + "children": children, + "frames": _frames_from_error_children(children), + } + + +static func _is_debugger_error_item(item: TreeItem) -> bool: + return item.has_meta("_is_warning") or item.has_meta("_is_error") + + +static func _frames_from_error_children(children: Array[Dictionary]) -> Array[Dictionary]: + var start := -1 + for i in children.size(): + if str(children[i].label).contains("Stack Trace"): + start = i + break + if start < 0: + for i in children.size(): + if str(children[i].label).is_empty() and not str(children[i].path).is_empty(): + start = maxi(i - 1, 0) + break + if start < 0: + return [] + var frames: Array[Dictionary] = [] + for i in range(start, children.size()): + if str(children[i].path).is_empty(): + continue + frames.append({ + "path": children[i].path, + "line": children[i].line, + "function": _function_from_frame_text(children[i].text), + }) + return frames + + +static func _location_from_metadata(meta: Variant) -> Dictionary: + if meta is Array and meta.size() >= 2: + return {"path": str(meta[0]), "line": int(meta[1])} + return {"path": "", "line": 0} + + +static func _function_from_title(title: String) -> String: + var colon := title.find(": ") + if colon <= 0: + return "" + return title.substr(0, colon) + + +static func _function_from_frame_text(text: String) -> String: + var marker := text.find(" @ ") + if marker < 0: + return "" + var fn := text.substr(marker + 3).strip_edges() + if fn.ends_with("()"): + fn = fn.substr(0, fn.length() - 2) + return fn + + +## Shared one-line rendering of a compact editor-error entry for messages and +## hints ("text (path:line)"). Single home so the debugger plugin, project +## handler, and editor handler can't drift apart. +static func format_editor_error_summary(entry: Dictionary) -> String: + var text := str(entry.get("text", "editor error")) + var path := str(entry.get("path", "")) + var line := int(entry.get("line", 0)) + if not path.is_empty() and line > 0: + return "%s (%s:%d)" % [text, path, line] + if not path.is_empty(): + return "%s (%s)" % [text, path] + return text + + +static func _log_entry_key(entry: Dictionary) -> String: + return "%s|%s|%s|%s" % [ + str(entry.get("level", "")), + str(entry.get("text", "")), + str(entry.get("path", "")), + str(entry.get("line", 0)), + ] + + +func _error_appended_total() -> int: + if _editor_log_buffer == null: + return 0 + if _editor_log_buffer.has_method("error_appended_total"): + return int(_editor_log_buffer.call("error_appended_total")) + return 0 + + +func _game_error_total() -> int: + if _game_log_buffer == null: + return 0 + if _game_log_buffer.has_method("error_total"): + return int(_game_log_buffer.call("error_total")) + return 0 + + +func _warn_appended_total() -> int: + if _editor_log_buffer == null: + return 0 + if _editor_log_buffer.has_method("warn_appended_total"): + return int(_editor_log_buffer.call("warn_appended_total")) + return 0 + + +func _game_warn_total() -> int: + if _game_log_buffer == null: + return 0 + if _game_log_buffer.has_method("warn_total"): + return int(_game_log_buffer.call("warn_total")) + return 0 + + +func _should_scan_debugger_for_cached_watermark(now_msec: int) -> bool: + if not _debugger_scan_active and now_msec > _debugger_scan_until_msec: + return false + return now_msec - _last_debugger_refresh_msec >= DEBUGGER_REFRESH_MIN_INTERVAL_MS + + +func _trim_promoted_debugger_entries() -> void: + while _promoted_debugger_entries.size() > MAX_PROMOTED_DEBUGGER_ENTRIES: + _promoted_debugger_entries.pop_front() + if _promoted_debugger_entries.is_empty(): + _oldest_retained_debugger_sequence = _debugger_promoted_total + 1 + else: + _oldest_retained_debugger_sequence = int(_promoted_debugger_entries[0].get("_debugger_sequence", 1)) + + +func _trim_promoted_debugger_key_counts() -> void: + while _promoted_debugger_key_order.size() > MAX_PROMOTED_DEBUGGER_KEYS: + var key := _promoted_debugger_key_order.pop_front() + _promoted_debugger_keys.erase(key) + _promoted_debugger_row_times.erase(key) + + +## #635: per-row time text from a scraped Errors-tab entry (column 0 of the +## row, carried in details.time). Empty when the entry has no details — e.g. +## synthetic records — which keeps those on count-only dedup. +static func _row_time_text(entry: Dictionary) -> String: + var details: Variant = entry.get("details", {}) + if details is Dictionary: + return str((details as Dictionary).get("time", "")) + return "" + + +func _unaccounted_row_times(key: String, times: Dictionary) -> Array: + var accounted: Dictionary = _promoted_debugger_row_times.get(key, {}) + var unseen := [] + for time_text in times.keys(): + if not accounted.has(time_text): + unseen.append(time_text) + return unseen + + +func _account_row_times(key: String, times: Dictionary) -> void: + if times.is_empty(): + return + var accounted: Dictionary = _promoted_debugger_row_times.get(key, {}) + for time_text in times.keys(): + accounted[time_text] = true + ## Enforce the bound AFTER merging: a pre-merge `>` check let the set + ## reach the cap and keep growing (and a batch of new times could jump + ## past it). Past the cap, reset to just this scan's times — the live + ## Errors tab is itself bounded, so this only fires under a pathological + ## same-key flood, where "recent scan only" is an acceptable memory of + ## what was promoted (worst case: a re-observed ancient row re-promotes). + if accounted.size() > MAX_ACCOUNTED_ROW_TIMES_PER_KEY: + accounted = times.duplicate() + _promoted_debugger_row_times[key] = accounted + + +func _remove_promoted_debugger_entry(key: String) -> void: + for i in range(_promoted_debugger_entries.size() - 1, -1, -1): + if str(_promoted_debugger_entries[i].get("_debugger_key", "")) == key: + _promoted_debugger_entries.remove_at(i) + return + + +func _raw_debugger_error_entries() -> Array[Dictionary]: + var entries: Array[Dictionary] = [] + for tree in locate_debugger_error_trees(): + entries.append_array(entries_from_debugger_error_tree(tree)) + return entries diff --git a/addons/godot_ai/utils/surfaced_error_tracker.gd.uid b/addons/godot_ai/utils/surfaced_error_tracker.gd.uid new file mode 100644 index 0000000..433a191 --- /dev/null +++ b/addons/godot_ai/utils/surfaced_error_tracker.gd.uid @@ -0,0 +1 @@ +uid://o0ulahkt83re diff --git a/addons/godot_ai/utils/update_manager.gd b/addons/godot_ai/utils/update_manager.gd new file mode 100644 index 0000000..65de4ee --- /dev/null +++ b/addons/godot_ai/utils/update_manager.gd @@ -0,0 +1,843 @@ +@tool +class_name McpUpdateManager +extends Node + +## Self-update manager for pre-runner work. Owns release checks, HTTP ZIP +## download, the install-in-flight gate, and install state signals back to +## the dock. Once `_install_zip()` calls +## `plugin.gd::install_downloaded_update(...)`, ownership transfers to +## `update_reload_runner.gd`, which owns extract, scan, plugin re-enable, +## and detached-dock cleanup. +## +## The dock owns banner rendering and forwards button clicks. The split +## exists because the dock script is one of the files overwritten on disk +## during install — keeping pipeline state on a separate Node lets the dock +## tear down cleanly without losing the in-flight gate that other dock spawn +## paths consult. +## +## `class_name McpUpdateManager` is retained because it shipped in a +## published release. If this class is ever retired, follow CLAUDE.md's +## never-delete-published-class_name shim policy instead of deleting the +## declaration. +## +## `_plugin` and `_dock` are deliberately untyped: the same self-update +## window that overwrites this script also overwrites the dock and plugin +## scripts, and a static-typed reference into a script being hot-reloaded +## crashes inside `GDScriptFunction::call`. `server_lifecycle.gd` follows +## the same convention. + +const RELEASES_URL := ( + "https://api.github.com/repos/hi-godot/godot-ai/releases/latest" +) +const RELEASES_PAGE := "https://github.com/hi-godot/godot-ai/releases/latest" +const UPDATE_TEMP_DIR := "user://godot_ai_update/" +const UPDATE_TEMP_ZIP := "user://godot_ai_update/update.zip" +const ClientConfigurator := preload("res://addons/godot_ai/client_configurator.gd") +const PortResolver := preload("res://addons/godot_ai/utils/port_resolver.gd") + +## RSA-4096 public key for release-signature verification (#687). The paired +## private key exists only in the GitHub Actions secret RELEASE_SIGNING_KEY_PEM +## (plus the maintainer's offline backup) — deliberately outside the repo +## token's scope, because the threat model is release-asset substitution by a +## leaked token or compromised workflow, and a token that can rewrite assets +## still cannot read secrets. Rotation requires shipping a new plugin release +## embedding the new key (and bumping SIGNING_REQUIRED_FROM_VERSION past the +## last release signed with the old one). +const RELEASE_SIGNING_PUBLIC_KEY_PEM := """-----BEGIN PUBLIC KEY----- +MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAr4OmbONFTONGFcXSUQ2p +e54YaUhWDA75wxeDWhOc476vsdo53YnXEFT7EPr2hUKqeNxv++LqKOkFuAsxSNZy +wBe6P1tmQA4Og6Ezv4CGnZdEj1uhlDJFK9ShQ29oWfC6bf/84625SvvBxZos2Br9 +yPKl7h5wzqDoeUSpv+f0ynTiC0i/HAUo/NQBlkgGwkomK2Fr3pP1VDxxq2xvgHSk +lU6Qcomr9WjJxI+HkDN5tRPPn0pDrg6YFx2J18OfD8KIa/kMGxuXOcHlPyRYpjyu +qTtg2oL0NyUIG+1TmJ3DcN4GlKC55eOrkfJ04vudS5pxdnUIFRmkGBXZLdaetoPc +ixtlD4w6gi8KIH1CTG+/TtHP1KVdOogCWDcjRCAmMJPFZe6eEKXmGQUZDb9wfnbx +h++XiVe5tq83BTLWmaFTy+fZbNo12uhNCNS1LJ42/yj+S1xvo0yMbkkNr1hIYk0P +584XnBQeBSVJDf3667NZXaxnWv94K9zbb+1OvOvPwhbOdgi2Ymcw5QEOQIavtg86 +XLLcWzG+SJsycz1imikjv6sStWh8WHneKSTMq6A7V6PBj7oJyEJp10696BDw287k +YlH+9VGqowPEMXpWX57wOBKiWb4K1kw1LfxjT8W1e/pcX9pJqiv0DkjTXUxo9CDG +1X1+ZXBBR3MkGuFAOCjy0x8CAwEAAQ== +-----END PUBLIC KEY----- +""" + +## Every release at or above this version ships a signed sidecar +## (release.yml hard-fails without the signing secret). At or above it, a +## missing `.sha256.sig` asset is treated as tampering — an attacker who can +## rewrite release assets could otherwise just strip the signature to skip +## verification. Below it (releases published before signing existed), the +## legacy checksum-only path still installs. +const SIGNING_REQUIRED_FROM_VERSION := "2.9.3" + +## Host -> required path prefix for self-update downloads (ZIP and checksum +## sidecar). The URLs are taken verbatim from the GitHub Releases API's +## `browser_download_url`, so before fetching we pin them to https on a +## GitHub-owned host AND to this repo's release-asset path (#599) — a +## tampered or unexpected API response can't point the in-editor updater at +## an arbitrary origin, nor at a release asset of a *different* repo on a +## trusted host. +## +## In practice `browser_download_url` is always the +## `https://github.com/hi-godot/godot-ai/releases/download//` +## shape; HTTPRequest then follows the github.com -> *.githubusercontent.com +## redirect internally (this guard validates the entry point, not each hop). +## The CDN hosts are kept as defense-in-depth should the API ever hand back +## a direct CDN URL — their object keys carry the repo *id*, not the repo +## name, so the tightest checkable prefix there is the release-asset key +## namespace. +const _TRUSTED_DOWNLOAD_PATH_PREFIXES := { + "github.com": "/hi-godot/godot-ai/releases/download/", + "www.github.com": "/hi-godot/godot-ai/releases/download/", + "api.github.com": "/repos/hi-godot/godot-ai/releases/assets/", + "objects.githubusercontent.com": "/github-production-release-asset-", + "release-assets.githubusercontent.com": "/github-production-release-asset-", +} + +## Emitted after `check_for_updates()` resolves a newer remote version. +## Payload mirrors the Dictionary returned by `parse_releases_response`: +## {has_update, version, forced, label_text, download_url} +signal update_check_completed(result: Dictionary) + +## Emitted at every UI-relevant step of the install pipeline. Payload +## keys are all optional and apply on top of the current banner state: +## label_text: String ## banner label override +## button_text: String ## update button text override +## button_disabled: bool ## update button disabled state +## banner_visible: bool ## banner visibility override +## outcome: String ## "success" -> dock paints green +signal install_state_changed(state: Dictionary) + +var _plugin +var _dock + +var _http_request: HTTPRequest +var _download_request: HTTPRequest +var _verify_request: HTTPRequest +var _signature_request: HTTPRequest +var _latest_download_url: String = "" +## URL of the `godot-ai-plugin.zip.sha256` sidecar asset. Used to verify the +## downloaded archive's integrity before extract (#523). Verification is +## mandatory (#599): when a release ships no sidecar this stays empty and +## `_verify_then_install` refuses the install. +var _latest_checksum_url: String = "" +## URL of the `godot-ai-plugin.zip.sha256.sig` signature asset (#687). Empty +## on releases published before signing existed; `_verify_then_install` +## refuses an empty URL once the remote version is inside the signing era +## (see SIGNING_REQUIRED_FROM_VERSION). +var _latest_signature_url: String = "" +## Remote version from the last update check — drives the +## signature-required compat gate in `_verify_then_install`. +var _latest_remote_version: String = "" +## Sidecar bytes + parsed digest held between the checksum download and the +## signature verdict, so the signature is checked against exactly the bytes +## the digest was parsed from. +var _pending_sidecar_body := PackedByteArray() +var _pending_expected_digest: String = "" + +## Set for the duration of `_install_zip` — extract-overwrite of plugin +## scripts on disk would crash any worker mid-`GDScriptFunction::call` +## (confirmed via SIGABRT in the dock's refresh worker). Dock spawn paths +## consult this via `is_install_in_flight()`; in-flight workers are +## drained before any disk write. +var _install_in_flight: bool = false + + +# ---- Setup ------------------------------------------------------------- + +func setup(plugin, dock) -> void: + _plugin = plugin + _dock = dock + + +# ---- Public API --------------------------------------------------------- + +## Kick off the GitHub Releases API check. No-ops in dev checkouts — +## `addons/godot_ai/` is a symlink into canonical `plugin/` source there, +## and an extract would clobber tracked files (#116). `is_dev_checkout()` +## honours the mode override (EditorSetting `godot_ai/mode_override` > +## `GODOT_AI_MODE` env), so +## testers can force `user` to exercise the AssetLib flow from a dev tree; +## `_install_zip` still gates on the physical symlink check so a forced- +## user mode can never clobber source. +func check_for_updates() -> void: + if ClientConfigurator.is_dev_checkout(): + return + if _http_request == null: + _http_request = HTTPRequest.new() + _http_request.request_completed.connect(_on_update_check_completed) + add_child(_http_request) + _http_request.request(RELEASES_URL, ["Accept: application/vnd.github+json"]) + + +## Cancel any in-flight check so a follow-up check_for_updates() can't +## hit ERR_BUSY on the shared HTTPRequest. No current dock caller — the +## mode-override dropdown that used it was removed in #408; kept as +## published API of the update flow. +func cancel_check() -> void: + if _http_request != null: + _http_request.cancel_request() + + +## Reset the cached download/checksum URLs so a fresh check paints over +## a clean banner. No current production caller — the mode-override +## dropdown that used it was removed in #408; kept for tests and any +## future re-check path. +func clear_pending_download() -> void: + _latest_download_url = "" + _latest_checksum_url = "" + _latest_signature_url = "" + _latest_remote_version = "" + _pending_sidecar_body = PackedByteArray() + _pending_expected_digest = "" + + +## True when the running Godot is within the supported self-update floor. +## Godot < 4.5 must not be offered a one-click update to a release whose +## always-loaded scripts depend on 4.5 APIs/classes. +## Guards `major` too so a future Godot 5.x (minor 0) isn't misclassified. +func _can_self_update() -> bool: + var v := Engine.get_version_info() + return _version_can_self_update(int(v.get("major", 0)), int(v.get("minor", 0))) + + +## Pure version predicate, split out so it's testable without faking the +## running engine. In-editor self-update needs Godot >= 4.5. +static func _version_can_self_update(major: int, minor: int) -> bool: + return major > 4 or (major == 4 and minor >= 5) + + +## Banner guidance for engines below the support floor. Shown up-front at +## check time so those users do not install an incompatible latest release. +static func _manual_update_label(version: String) -> String: + var release_noun := "release" + var suffix := "" + if not version.is_empty(): + release_noun = "version" + suffix = " (latest: v%s)" % version + return ( + "This is the last Godot AI %s for this Godot%s. " % [release_noun, suffix] + + "Upgrade to Godot 4.5+ to keep receiving updates." + ) + + +## PID of the detached package pre-warm started alongside the zip download, +## or <= 0 when none is running (no uvx tier, unusable version pin, or it has +## already been waited out). See `_wait_for_prewarm_before_install`. +var _prewarm_pid := -1 +## When the install first found the pre-warm still running, so the wait below +## is bounded from the first check rather than re-armed on every poll. +var _prewarm_wait_started_ms := 0 +## Ceiling on how long install will wait for the pre-warm. Matches the budget +## the Configure-time pre-warm allows for the same download. +const PREWARM_WAIT_BUDGET_MS := 180 * 1000 +## Poll interval while waiting. Deliberately not sub-second: `pid_alive` shells +## out to `tasklist` on Windows via a blocking `OS.execute` on the main thread, +## so a tight poll would make the editor sluggish for the whole wait. +const PREWARM_POLL_SECONDS := 2.0 + + +## Driven by the dock's Update button. On Godot < 4.5 (see _can_self_update) +## the in-editor install is disabled so users cannot install an incompatible +## latest release. With no resolved download URL, falls back to opening the +## release page. Otherwise kicks off the download -> extract -> reload pipeline. +func start_install() -> void: + if not _can_self_update(): + install_state_changed.emit({ + "button_text": "Upgrade Godot", + "button_disabled": true, + "label_text": _manual_update_label(""), + "banner_visible": true, + }) + return + + if _latest_download_url.is_empty(): + OS.shell_open(RELEASES_PAGE) + return + + ## Pin the resolved asset URL to https on a GitHub host AND to this + ## repo's release-asset path before fetching (#523, #599). Fall back to + ## the release page (a user-driven browser download) rather than pulling + ## an executable plugin payload from an unexpected origin. + if not _is_trusted_download_url(_latest_download_url): + push_error( + "MCP | refusing self-update download from untrusted URL: %s" + % _latest_download_url + ) + OS.shell_open(RELEASES_PAGE) + install_state_changed.emit({ + "button_text": "Update via download page", + "button_disabled": false, + }) + return + + install_state_changed.emit({ + "button_text": "Downloading...", + "button_disabled": true, + }) + + ## Warm the uv cache for the NEW server version while the plugin zip + ## downloads (see prewarm_server_package): the post-update walk must win + ## a port bind race against attach bridges respawning the cached OLD + ## version, and a cold uvx resolve loses that race every time. uvx is + ## almost always cached in the CliFinder by now (the dock's setup probe); + ## a cold lookup is the same bounded main-thread cost as + ## `_reprobe_uv_if_negative`, on the same rare click-driven path. + _prewarm_pid = ClientConfigurator.prewarm_server_package(_latest_remote_version) + _prewarm_wait_started_ms = 0 + + if _download_request != null: + _download_request.queue_free() + _download_request = HTTPRequest.new() + var global_zip := ProjectSettings.globalize_path(UPDATE_TEMP_ZIP) + var global_dir := ProjectSettings.globalize_path(UPDATE_TEMP_DIR) + DirAccess.make_dir_recursive_absolute(global_dir) + _download_request.download_file = global_zip + _download_request.max_redirects = 10 + _download_request.request_completed.connect(_on_download_completed) + add_child(_download_request) + var err := _download_request.request(_latest_download_url) + if err != OK: + ## `request_completed` never fires when `request()` itself errors, + ## so cleanup (queue_free + null + drop the staged zip) has to land + ## inline — otherwise the HTTPRequest stays parented under the + ## manager until the next click. + _download_request.queue_free() + _download_request = null + DirAccess.remove_absolute(global_zip) + install_state_changed.emit({ + "button_text": "Request failed", + "button_disabled": false, + }) + +## Consulted by the dock's spawn paths (focus-in refresh, manual button, +## deferred initial refresh) — true while plugin scripts are being +## overwritten. A worker mid-`GDScriptFunction::call` into a half- +## overwritten script SIGABRTs the editor. +func is_install_in_flight() -> bool: + return _install_in_flight + + +# ---- Releases-API parse (pure, testable) ------------------------------- + +## Parses the GitHub Releases API JSON response. Returns: +## has_update: bool ## true if remote tag > local version +## version: String ## remote tag minus leading "v" +## forced: bool ## mode_override() == "user" (banner-only hint) +## label_text: String ## "Update available: vX.Y.Z" + " (forced)" +## download_url: String ## matching `godot-ai-plugin.zip` asset URL +## checksum_url: String ## `godot-ai-plugin.zip.sha256` asset URL ("" if absent) +## signature_url: String ## `godot-ai-plugin.zip.sha256.sig` asset URL ("" if absent) +## +## Static so tests drive it without instancing the manager. +static func parse_releases_response( + result: int, response_code: int, body: PackedByteArray +) -> Dictionary: + var out := { + "has_update": false, + "version": "", + "forced": false, + "label_text": "", + "download_url": "", + "checksum_url": "", + "signature_url": "", + } + if result != HTTPRequest.RESULT_SUCCESS or response_code != 200: + return out + var parsed = JSON.parse_string(body.get_string_from_utf8()) + if parsed == null or not (parsed is Dictionary): + return out + var json: Dictionary = parsed + var tag: String = String(json.get("tag_name", "")) + if tag.is_empty(): + return out + var remote_version := tag.trim_prefix("v") + var local_version := ClientConfigurator.get_plugin_version() + if not _is_newer(remote_version, local_version): + return out + + var url := "" + var checksum_url := "" + var signature_url := "" + var assets: Array = json.get("assets", []) + for asset in assets: + var asset_dict: Dictionary = asset + var asset_name := String(asset_dict.get("name", "")) + if asset_name == "godot-ai-plugin.zip": + url = String(asset_dict.get("browser_download_url", "")) + elif asset_name == "godot-ai-plugin.zip.sha256": + checksum_url = String(asset_dict.get("browser_download_url", "")) + elif asset_name == "godot-ai-plugin.zip.sha256.sig": + signature_url = String(asset_dict.get("browser_download_url", "")) + + var forced := ClientConfigurator.mode_override() == "user" + var label_text := "Update available: v%s" % remote_version + if forced: + ## Forced-user mode (EditorSetting or env) is the only way the banner + ## lights up in a dev tree; suffix so the operator notices. + label_text += " (forced)" + + out["has_update"] = true + out["version"] = remote_version + out["forced"] = forced + out["label_text"] = label_text + out["download_url"] = url + out["checksum_url"] = checksum_url + out["signature_url"] = signature_url + return out + + +## True only for an `https://` URL whose host is a key of +## `_TRUSTED_DOWNLOAD_PATH_PREFIXES` AND whose path starts with that host's +## required prefix — trusted host alone is not enough; the URL must be a +## hi-godot/godot-ai release asset (#599). Parses the authority by hand +## (GDScript has no URL parser): strips userinfo via the LAST `@` so a spoof +## like `https://github.com@evil.com/...` resolves to `evil.com` (rejected), +## and strips any `:port`. The path is compared case-sensitively (GitHub +## release paths are case-sensitive). Static so the guard is unit-testable +## without instancing the manager. +static func _is_trusted_download_url(url: String) -> bool: + const SCHEME := "https://" + if not url.begins_with(SCHEME): + return false + if url.find("\\") >= 0: + return false + var rest := url.substr(SCHEME.length()) + var authority := rest + var path := "" + var slash := rest.find("/") + if slash >= 0: + authority = rest.substr(0, slash) + path = rest.substr(slash) + ## Host is everything after the LAST '@' (userinfo precedes it). + var at := authority.rfind("@") + if at >= 0: + authority = authority.substr(at + 1) + var colon := authority.find(":") + if colon >= 0: + authority = authority.substr(0, colon) + var host := authority.to_lower() + if not _TRUSTED_DOWNLOAD_PATH_PREFIXES.has(host): + return false + ## Scope the checks below to the path proper (#713): direct CDN asset + ## URLs carry signed query params (X-Amz-Credential=...%2F...) whose + ## legitimate %2F tokens made every CDN prefix unreachable when the + ## needle scan covered the query string. Routing is decided by the + ## path, so the query is safe to ignore. + var qmark := path.find("?") + if qmark >= 0: + path = path.substr(0, qmark) + ## Reject dot-segments (and their percent-encoded forms) anywhere in the + ## path: "/hi-godot/godot-ai/releases/download/../../evil/..." passes a + ## raw string-prefix test but normalizes server-side to a different repo, + ## defeating the scoping (#599 review). Also reject percent-encoded + ## slashes, which some servers decode before routing. + var lower_path := path.to_lower() + for needle in ["/../", "/..", "%2e", "%2f", "%5c"]: + if lower_path.contains(needle): + return false + return path.begins_with(String(_TRUSTED_DOWNLOAD_PATH_PREFIXES[host])) + + +static func _is_newer(remote: String, local: String) -> bool: + var r := remote.split(".") + var l := local.split(".") + for i in range(max(r.size(), l.size())): + var rv := int(r[i]) if i < r.size() else 0 + var lv := int(l[i]) if i < l.size() else 0 + if rv > lv: + return true + if rv < lv: + return false + return false + + +# ---- HTTPRequest callbacks (instance-side) ----------------------------- + +func _on_update_check_completed( + result: int, + response_code: int, + _headers: PackedStringArray, + body: PackedByteArray +) -> void: + var parsed := parse_releases_response(result, response_code, body) + if not bool(parsed.get("has_update", false)): + return + if not _can_self_update(): + install_state_changed.emit({ + "button_text": "Upgrade Godot", + "button_disabled": true, + "label_text": _manual_update_label(String(parsed.get("version", ""))), + "banner_visible": true, + }) + return + _latest_download_url = String(parsed.get("download_url", "")) + _latest_checksum_url = String(parsed.get("checksum_url", "")) + _latest_signature_url = String(parsed.get("signature_url", "")) + _latest_remote_version = String(parsed.get("version", "")) + update_check_completed.emit(parsed) + + +func _on_download_completed( + result: int, + response_code: int, + _headers: PackedStringArray, + _body: PackedByteArray +) -> void: + if _download_request != null: + _download_request.queue_free() + _download_request = null + + if result != HTTPRequest.RESULT_SUCCESS or response_code != 200: + print("MCP | update download failed: result=%d code=%d" % [result, response_code]) + ## Failure parity with _fail_verification (#713): HTTPRequest's + ## download_file mode leaves whatever partial/error bytes it wrote + ## staged at UPDATE_TEMP_ZIP — drop them so no later step can ever + ## pick up a half-downloaded archive. + DirAccess.remove_absolute(ProjectSettings.globalize_path(UPDATE_TEMP_ZIP)) + install_state_changed.emit({ + "button_text": "Download failed (%d)" % response_code, + "button_disabled": false, + }) + return + + # Deferred so the HTTPRequest callback returns before the next step starts. + _verify_then_install.call_deferred() + + +# ---- Integrity verification (#523, #599, #687) -------------------------- + +## Gate the extract on (1) an RSA signature over the checksum sidecar and +## (2) a SHA-256 match of the archive against that sidecar. TLS + host +## pinning constrain where the bytes came from; the digest verifies the +## bytes themselves (in-transit corruption, single-object substitution); +## the signature verifies the digest's *provenance*. Both `download_url` +## and `checksum_url` come from the same GitHub Releases API response over +## the same channel, so anyone able to modify the release's assets (leaked +## repo token, compromised release workflow) can regenerate the sidecar to +## match a tampered zip — but cannot forge the `.sha256.sig` signature, +## whose private key lives only in an Actions secret outside the repo +## token's scope (#687). +## +## Verification is MANDATORY (#599): no `.sha256` sidecar — mistake or +## tamper — refuses to install. The signature is mandatory for every +## release at or above SIGNING_REQUIRED_FROM_VERSION: a missing signature +## there is a strip-attack signal, not a compat case, and hard-fails. Only +## releases predating signing take the legacy checksum-only path. +func _verify_then_install() -> void: + _pending_sidecar_body = PackedByteArray() + _pending_expected_digest = "" + + if _latest_checksum_url.is_empty(): + _fail_verification( + "release published no godot-ai-plugin.zip.sha256 sidecar; " + + "refusing unverified install (#599)" + ) + return + + ## A present-but-untrusted checksum URL is a tamper signal, not a + ## backward-compat case — refuse rather than silently skip. Trusted + ## means a GitHub host AND this repo's release-asset path (#599). + if not _is_trusted_download_url(_latest_checksum_url): + _fail_verification("checksum URL is not a trusted hi-godot/godot-ai release asset") + return + + if _latest_signature_url.is_empty(): + if _signature_required(_latest_remote_version): + _fail_verification( + "release v%s ships no godot-ai-plugin.zip.sha256.sig signature. " + % _latest_remote_version + + "Every release from v%s on is signed" % SIGNING_REQUIRED_FROM_VERSION + + " — a missing signature means a stripped or tampered release (#687)" + ) + return + print( + "MCP | self-update: release v%s predates signing; " % _latest_remote_version + + "using legacy checksum-only verification (#687)" + ) + elif not _is_trusted_download_url(_latest_signature_url): + _fail_verification("signature URL is not a trusted hi-godot/godot-ai release asset") + return + + install_state_changed.emit({"button_text": "Verifying..."}) + if _verify_request != null: + _verify_request.queue_free() + _verify_request = HTTPRequest.new() + _verify_request.max_redirects = 10 + _verify_request.request_completed.connect(_on_checksum_completed) + add_child(_verify_request) + var err := _verify_request.request(_latest_checksum_url) + if err != OK: + _verify_request.queue_free() + _verify_request = null + _fail_verification("could not request checksum (error %d)" % err) + + +func _on_checksum_completed( + result: int, + response_code: int, + _headers: PackedStringArray, + body: PackedByteArray +) -> void: + if _verify_request != null: + _verify_request.queue_free() + _verify_request = null + + if result != HTTPRequest.RESULT_SUCCESS or response_code != 200: + _fail_verification("checksum download failed (result=%d code=%d)" % [result, response_code]) + return + + var expected := _parse_sha256_digest(body.get_string_from_utf8()) + if expected.is_empty(): + _fail_verification("malformed checksum file") + return + + ## Signature verification (when armed) runs over the exact sidecar bytes + ## the digest was parsed from — hold both until the signature verdict. + if not _latest_signature_url.is_empty(): + _pending_sidecar_body = body + _pending_expected_digest = expected + _fetch_signature() + return + + ## Legacy pre-signing release: `_verify_then_install` already gated this + ## on the remote version predating SIGNING_REQUIRED_FROM_VERSION. + _finish_digest_check_and_install(expected) + + +## Download the `.sha256.sig` release asset; `_on_signature_completed` +## verifies it over the held sidecar bytes before the digest is trusted. +func _fetch_signature() -> void: + if _signature_request != null: + _signature_request.queue_free() + _signature_request = HTTPRequest.new() + _signature_request.max_redirects = 10 + _signature_request.request_completed.connect(_on_signature_completed) + add_child(_signature_request) + var err := _signature_request.request(_latest_signature_url) + if err != OK: + _signature_request.queue_free() + _signature_request = null + _fail_verification("could not request signature (error %d)" % err) + + +func _on_signature_completed( + result: int, + response_code: int, + _headers: PackedStringArray, + body: PackedByteArray +) -> void: + if _signature_request != null: + _signature_request.queue_free() + _signature_request = null + + if result != HTTPRequest.RESULT_SUCCESS or response_code != 200: + _fail_verification( + "signature download failed (result=%d code=%d)" % [result, response_code] + ) + return + + if not _verify_sidecar_signature(RELEASE_SIGNING_PUBLIC_KEY_PEM, _pending_sidecar_body, body): + _fail_verification( + "release signature does not verify against the embedded public key — " + + "the checksum sidecar was not produced by the release pipeline (#687)" + ) + return + + print("MCP | self-update release signature verified (rsa-4096/sha256)") + _finish_digest_check_and_install(_pending_expected_digest) + + +## Final gate shared by the signed and legacy paths: the staged archive's +## SHA-256 must match the (now-trusted) sidecar digest before extract. +func _finish_digest_check_and_install(expected: String) -> void: + _pending_sidecar_body = PackedByteArray() + _pending_expected_digest = "" + + var zip_path := ProjectSettings.globalize_path(UPDATE_TEMP_ZIP) + var actual := FileAccess.get_sha256(zip_path).to_lower() + if actual.is_empty(): + _fail_verification("could not hash the downloaded archive") + return + if actual != expected: + _fail_verification( + "checksum mismatch (expected %s…, got %s…)" + % [expected.substr(0, 12), actual.substr(0, 12)] + ) + return + + print("MCP | self-update checksum verified (sha256 %s)" % actual) + install_state_changed.emit({"button_text": "Installing..."}) + _install_zip.call_deferred() + + +## True when `remote_version` falls inside the signing era — every release +## at or above SIGNING_REQUIRED_FROM_VERSION ships a signed sidecar, so a +## missing signature there must hard-fail rather than fall back to the +## legacy checksum-only path. An empty/unknown version fails closed. Static +## so it's unit-testable. +static func _signature_required(remote_version: String) -> bool: + if remote_version.strip_edges().is_empty(): + return true + return not _is_newer(SIGNING_REQUIRED_FROM_VERSION, remote_version) + + +## PKCS#1 v1.5 RSA verification of `signature` over SHA-256(`sidecar`) — +## the exact output of release.yml's `openssl dgst -sha256 -sign`. Takes +## the PEM as a parameter (rather than reading the const) so tests can +## exercise both verdicts with a generated throwaway keypair. Static so +## it's unit-testable without instancing the manager. +static func _verify_sidecar_signature( + public_key_pem: String, sidecar: PackedByteArray, signature: PackedByteArray +) -> bool: + if sidecar.is_empty() or signature.is_empty(): + return false + var key := CryptoKey.new() + if key.load_from_string(public_key_pem, true) != OK: + return false + var ctx := HashingContext.new() + if ctx.start(HashingContext.HASH_SHA256) != OK: + return false + ctx.update(sidecar) + var digest := ctx.finish() + var crypto := Crypto.new() + return crypto.verify(HashingContext.HASH_SHA256, digest, signature, key) + + +## Surface an integrity-check failure and drop the staged zip so the bad +## bytes can never reach the extract path. Keeps the button enabled for retry. +func _fail_verification(reason: String) -> void: + _pending_sidecar_body = PackedByteArray() + _pending_expected_digest = "" + push_error( + "MCP | self-update integrity check failed: %s. The download was not installed." + % reason + ) + print("MCP | self-update aborted (integrity): %s" % reason) + DirAccess.remove_absolute(ProjectSettings.globalize_path(UPDATE_TEMP_ZIP)) + install_state_changed.emit({ + "button_text": "Verification failed — retry", + "button_disabled": false, + }) + + +## Extract the hex digest from a `sha256sum`-style file (" ") or a +## bare digest line. Returns lowercase 64-char hex, or "" if the content isn't +## a valid SHA-256 digest. Static so it's unit-testable. See #523. +static func _parse_sha256_digest(text: String) -> String: + var trimmed := text.strip_edges() + if trimmed.is_empty(): + return "" + ## First whitespace-delimited token; `sha256sum` separates digest and + ## filename with two spaces, but some tools use tabs. + var normalized := trimmed.replace("\t", " ").replace("\n", " ").replace("\r", " ") + var tokens := normalized.split(" ", false) + if tokens.is_empty(): + return "" + var digest := String(tokens[0]).strip_edges().to_lower() + if digest.length() != 64: + return "" + for i in digest.length(): + var c := digest[i] + if not ((c >= "0" and c <= "9") or (c >= "a" and c <= "f")): + return "" + return digest + + +# ---- Install orchestration --------------------------------------------- + +## True when install may proceed now. False means "come back later" — this +## call has already scheduled the retry. +## +## Deliberately placed AFTER the symlink check in `_install_zip` so a dev +## checkout (which never installs) is never delayed by it. +func _wait_for_prewarm_before_install() -> bool: + if _prewarm_pid <= 0 or not PortResolver.pid_alive(_prewarm_pid): + _prewarm_pid = -1 + return true + if _prewarm_wait_started_ms == 0: + _prewarm_wait_started_ms = Time.get_ticks_msec() + if Time.get_ticks_msec() - _prewarm_wait_started_ms >= PREWARM_WAIT_BUDGET_MS: + ## Proceed rather than strand the update: a pre-warm this slow means the + ## post-update spawn will be cold, which is now survivable — the startup + ## watch stays alive until the pid-file appears (#896). + print( + "MCP | self-update: package pre-warm still running after %ds; " + % int(PREWARM_WAIT_BUDGET_MS / 1000) + + "installing anyway, the new server may start cold" + ) + _prewarm_pid = -1 + return true + install_state_changed.emit({"button_text": "Preparing packages...", "button_disabled": true}) + if is_inside_tree(): + get_tree().create_timer(PREWARM_POLL_SECONDS).timeout.connect( + _install_zip, CONNECT_ONE_SHOT + ) + return false + ## Detached from the tree (dock teardown mid-update): no timer to re-arm on, + ## so let the install proceed rather than silently dropping it. + _prewarm_pid = -1 + return true + + +func _install_zip() -> void: + ## Symlinked addons dir means an extract would clobber canonical + ## `plugin/` source through the link. Symlink detection is independent + ## of the mode override: even forced-user aborts here. See #116. + if ClientConfigurator.addons_dir_is_symlink(): + install_state_changed.emit({ + "button_text": "Dev checkout — update via git", + "button_disabled": true, + "banner_visible": false, + }) + return + + ## #896: do not tear the old server down until the NEW version's uv + ## environment is actually built. `install_downloaded_update` below kills + ## the server and hands off to the reload runner; the new plugin instance + ## then spawns a server that, on a cold cache, is still downloading ~67 + ## packages. The pre-warm was started alongside the zip download precisely + ## to cover this, but nothing waited for it — so on a slow link the update + ## proceeded while the environment was still being fetched, which is the + ## window where a failed spawn goes undiagnosed. + ## + ## Non-blocking: re-arms itself on a timer rather than stalling the main + ## thread, and gives up after PREWARM_WAIT_BUDGET_MS so a wedged pre-warm + ## cannot strand the update. Fully inert when no pre-warm is running. + if not _wait_for_prewarm_before_install(): + return + + ## Drain in-flight workers + block new ones BEFORE any disk write. + ## Without this, focus-in landing in the extract -> reload window spawns + ## a worker that walks into a partially-overwritten script and + ## SIGABRTs in `GDScriptFunction::call`. + _install_in_flight = true + _drain_dock_workers() + + var has_runner: bool = ( + _plugin != null + and _plugin.has_method("install_downloaded_update") + ) + if has_runner: + install_state_changed.emit({"button_text": "Reloading..."}) + ## Runner takes over: plugin tears down, runner extracts + scans + + ## re-enables. `install_downloaded_update` calls + ## `prepare_for_update_reload()` internally (kills the server, + ## resets the spawn guard) - see plugin.gd::install_downloaded_update. + _plugin.install_downloaded_update(UPDATE_TEMP_ZIP, UPDATE_TEMP_DIR, _dock) + return + + DirAccess.remove_absolute(ProjectSettings.globalize_path(UPDATE_TEMP_ZIP)) + DirAccess.remove_absolute(ProjectSettings.globalize_path(UPDATE_TEMP_DIR)) + _install_in_flight = false + install_state_changed.emit({ + "button_text": "Reload runner missing", + "button_disabled": false, + }) + + +func _reload_after_update() -> void: + EditorInterface.set_plugin_enabled("res://addons/godot_ai/plugin.cfg", false) + EditorInterface.set_plugin_enabled("res://addons/godot_ai/plugin.cfg", true) + + +func _drain_dock_workers() -> void: + if _dock != null and _dock.has_method("prepare_for_self_update_drain"): + _dock.prepare_for_self_update_drain() diff --git a/addons/godot_ai/utils/update_manager.gd.uid b/addons/godot_ai/utils/update_manager.gd.uid new file mode 100644 index 0000000..4089a72 --- /dev/null +++ b/addons/godot_ai/utils/update_manager.gd.uid @@ -0,0 +1 @@ +uid://cegiyw3fjcwev diff --git a/addons/godot_ai/utils/update_mixed_state.gd b/addons/godot_ai/utils/update_mixed_state.gd new file mode 100644 index 0000000..96d0024 --- /dev/null +++ b/addons/godot_ai/utils/update_mixed_state.gd @@ -0,0 +1,140 @@ +@tool +extends RefCounted + +## Scanner that detects whether `addons/godot_ai/` is in a half-installed +## state left behind by a self-update whose rollback couldn't restore the +## previous addon contents (`UpdateReloadRunner.InstallStatus.FAILED_MIXED`). +## +## Without this surface the user sees "plugin won't start" with no actionable +## context, re-runs the update, and compounds the mismatch (issue #354 / +## audit-v2 #10). The dock paints a banner from `diagnose()` and +## `editor_handler.gd::get_editor_state` includes the same Dictionary so an +## MCP agent can see and report the state. + +const ADDON_DIR := "res://addons/godot_ai/" +## Producer is `update_reload_runner.gd::INSTALL_BACKUP_SUFFIX`. Inlined as a +## literal because old two-phase runners can parse this diagnostic script +## against stale runner Script-object content during their mixed-snapshot +## scan. `test_update_backup_suffix_stays_in_sync` guards against drift. +const BACKUP_SUFFIX := ".update_backup" +## Cap so a runaway addons tree (someone parented the wrong dir, an old +## crashed install left thousands of artifacts) can't blow the +## `editor_state` payload size or freeze the editor on first paint. +const MAX_BACKUP_RESULTS := 200 +## TTL for the `diagnose()` cache. `editor_state` is one of the highest- +## traffic MCP tools (agents poll it constantly) and a recursive +## `DirAccess` walk on every call would put I/O on the 4ms `_process()` +## budget. Mixed-state is rare and persistent across editor restarts, so +## a few seconds of staleness is acceptable; the dock's Re-scan button +## bypasses the cache via `force=true` for immediate feedback. +const CACHE_TTL_MSEC := 5000 + +static var _cache_value: Dictionary = {} +static var _cache_timestamp_msec: int = -1 + + +## Walk `dir` recursively and return every `res://`-relative path that ends +## in `.update_backup`, sorted ascending. Truncates at `MAX_BACKUP_RESULTS` +## — the truncation flag is exposed via `diagnose()`. +## +## Walk order is deterministic: entries within each directory are sorted +## alphabetically, subdirs pushed reverse-sorted so DFS pops them in +## ascending order. Without this two scans of the same mixed tree could +## return different 200-file slices when truncation kicks in (Godot's +## `list_dir` order isn't guaranteed stable across filesystems). +static func find_backups(dir: String = ADDON_DIR) -> Array: + var results: Array = [] + var stack: Array = [dir] + while not stack.is_empty(): + if results.size() >= MAX_BACKUP_RESULTS: + break + var current: String = stack.pop_back() + var d := DirAccess.open(current) + ## Missing dir, permission error, or unreadable junction — skip + ## silently. A missing addons dir is the bare-clone case; mid-walk + ## errors stay quiet so a single permission glitch can't block the + ## diagnostic the rest of the scan would have produced. + if d == null: + continue + var entries: Array = [] + d.list_dir_begin() + while true: + var entry := d.get_next() + if entry.is_empty(): + break + if entry == "." or entry == "..": + continue + entries.append({"name": entry, "is_dir": d.current_is_dir()}) + d.list_dir_end() + entries.sort_custom(func(a, b): return a["name"] < b["name"]) + ## Push subdirs reverse-sorted so the next outer iteration pops + ## them in ascending order — see method docstring for why this + ## determinism matters for the truncated case. + for i in range(entries.size() - 1, -1, -1): + var entry: Dictionary = entries[i] + if entry["is_dir"]: + stack.append(current.path_join(entry["name"])) + for entry in entries: + if entry["is_dir"]: + continue + if not String(entry["name"]).ends_with(BACKUP_SUFFIX): + continue + results.append(current.path_join(entry["name"])) + if results.size() >= MAX_BACKUP_RESULTS: + break + results.sort() + return results + + +## Build the structured diagnostic Dictionary surfaced via `editor_state` +## and the dock banner. Empty when the addons tree is clean — callers +## gate banner visibility / response field on `is_empty()`. +## +## Cached for `CACHE_TTL_MSEC` when scanning the default `ADDON_DIR` so +## per-`editor_state` polls don't re-walk the addons tree every frame. +## Tests passing a custom `dir` always see a fresh scan (cache only +## tracks the production path). `force=true` bypasses the cache — used +## by the dock's Re-scan button so a manual fix is reflected immediately. +static func diagnose(dir: String = ADDON_DIR, force: bool = false) -> Dictionary: + var use_cache := dir == ADDON_DIR and not force + if use_cache and _cache_timestamp_msec >= 0: + if Time.get_ticks_msec() - _cache_timestamp_msec < CACHE_TTL_MSEC: + return _cache_value.duplicate(true) + + var backups := find_backups(dir) + var result: Dictionary = {} + if not backups.is_empty(): + ## Most commonly produced by `_rollback_paths_written` returning + ## FAILED_MIXED, but `_finalize_install_success` removes backups on + ## a best-effort basis so a successful install can also leave them + ## behind if the cleanup `remove_absolute` hit a permission error. + ## The recovery action — delete the *.update_backup files — is the + ## same in both cases, so the message acknowledges both + ## possibilities rather than asserting the alarming one. + result = { + "addon_dir": dir, + "backup_files": backups, + "backup_count": backups.size(), + "truncated": backups.size() >= MAX_BACKUP_RESULTS, + "message": ( + "Found .update_backup files in addons/godot_ai/. This usually" + + " means a self-update rollback couldn't restore the previous" + + " addon contents (FAILED_MIXED) — the plugin may load a mix" + + " of old and new files. Restore the addon from your VCS or a" + + " fresh release ZIP, then delete the listed *.update_backup" + + " files. If the plugin runs without issues these are likely" + + " stale from a successful install and safe to delete." + ), + } + if use_cache: + _cache_value = result.duplicate(true) + _cache_timestamp_msec = Time.get_ticks_msec() + return result + + +## Reset the `diagnose()` cache. Tests that flip the addons-tree state +## between calls use this to avoid TTL-bound flakiness; the dock's +## Re-scan button uses `force=true` instead. +static func clear_cache() -> void: + _cache_value = {} + _cache_timestamp_msec = -1 diff --git a/addons/godot_ai/utils/update_mixed_state.gd.uid b/addons/godot_ai/utils/update_mixed_state.gd.uid new file mode 100644 index 0000000..6d608d9 --- /dev/null +++ b/addons/godot_ai/utils/update_mixed_state.gd.uid @@ -0,0 +1 @@ +uid://dd5rti52vgs71 diff --git a/addons/godot_ai/utils/uv_cache_cleanup.gd b/addons/godot_ai/utils/uv_cache_cleanup.gd new file mode 100644 index 0000000..86edbe1 --- /dev/null +++ b/addons/godot_ai/utils/uv_cache_cleanup.gd @@ -0,0 +1,161 @@ +@tool +class_name McpUvCacheCleanup +extends RefCounted + +## Sweeps stale `.tmp*` build venvs out of `%LOCALAPPDATA%\uv\cache\builds-v0`. +## +## Background +## ---------- +## When an MCP client's attach launcher invokes +## `uvx --from godot-ai==VERSION godot-ai attach ...`, uv builds an ephemeral venv under +## `builds-v0\.tmpXXXXXX\`. To save disk it hard-links shared C extensions +## (notably `pydantic_core/_pydantic_core.cp313-win_amd64.pyd`) from +## `archive-v0\\Lib\site-packages\...` into the build venv. +## +## If the godot-ai server's own Python child has that same `.pyd` mapped via +## `LoadLibrary` (it does — godot-ai imports pydantic), the file is locked +## under BOTH paths because hard links share the inode and Windows tracks +## handles per-file, not per-path. uv's post-install cleanup of the build +## venv then dies with: +## +## Failed to install: pywin32-311-cp313-cp313-win_amd64.whl (pywin32==311) +## Caused by: failed to remove directory `...\.tmpXXXXXX\Lib\site-packages\pywin32-311.data` +## 다른 프로세스가 파일을 사용 중이기 때문에 ... (os error 32) +## +## (the `pywin32` mention is incidental — the actual lock is on the earlier +## hard-linked `_pydantic_core.pyd`; pywin32 is just the last install step +## in the wheel-resolution order that triggers the cleanup pass). +## +## What this does +## -------------- +## After the plugin stops/restarts the managed server — i.e. the moment when +## the archive-v0 `.pyd` mappings drop and the hard-linked builds-v0 copy +## becomes deletable — sweep `builds-v0\` for `.tmp*` orphans: +## +## 1. Rename each `.tmpXXX` to `_dead_.tmpXXX`. Rename succeeds even when +## AV scanners hold the file open without `FILE_SHARE_DELETE` (Defender +## and Softcamp SDS both do this), so this step always advances. +## 2. Recursively remove the renamed dir, swallowing per-file +## access-denied. Anything still genuinely locked is left for the next +## sweep — uv won't reuse the renamed name, so no future build collides. +## +## No-op on non-Windows (uv's hard-link strategy only causes this lock +## pattern on NTFS) and when the cache directory doesn't exist. + +const DEAD_PREFIX := "_dead_" +const TMP_PREFIX := ".tmp" + + +## Live entrypoint. Resolves `%LOCALAPPDATA%\uv\cache\builds-v0` and runs +## the sweep. Returns the same counts the testable `purge_directory` returns, +## or all zeros on non-Windows / missing cache. +static func purge_stale_builds() -> Dictionary: + if OS.get_name() != "Windows": + return _empty_result() + var local_appdata := OS.get_environment("LOCALAPPDATA") + if local_appdata.is_empty(): + return _empty_result() + var builds_root := local_appdata.replace("\\", "/").path_join("uv/cache/builds-v0") + return purge_directory(builds_root) + + +## Pure-ish entrypoint that takes a directory path. Returns +## `{ "scanned": int, "renamed": int, "deleted": int, "remaining": int }`. +## - `scanned`: how many `.tmp*` subdirs we saw on entry. +## - `renamed`: how many we successfully renamed to `_dead_*`. +## - `deleted`: how many we then fully removed. +## - `remaining`: how many `_dead_*` dirs are still on disk after the sweep +## (left for the next call to retry). +## +## Errors are swallowed — the caller is on a server-stop hot path and +## must not raise. +static func purge_directory(builds_root: String) -> Dictionary: + var result := _empty_result() + if not DirAccess.dir_exists_absolute(builds_root): + return result + var dir := DirAccess.open(builds_root) + if dir == null: + return result + dir.include_hidden = true + + ## Pass 1: collect names. Iterating + renaming in the same walk would + ## confuse DirAccess's internal cursor on NTFS. + var tmp_names: Array[String] = [] + var dead_names: Array[String] = [] + dir.list_dir_begin() + var entry := dir.get_next() + while entry != "": + if dir.current_is_dir() and not (entry == "." or entry == ".."): + if entry.begins_with(TMP_PREFIX): + tmp_names.append(entry) + elif entry.begins_with(DEAD_PREFIX): + dead_names.append(entry) + entry = dir.get_next() + dir.list_dir_end() + result.scanned = tmp_names.size() + + ## Pass 2: rename `.tmp*` → `_dead_.tmp*`. Rename works even on + ## AV-locked files (Defender opens without FILE_SHARE_DELETE, but rename + ## doesn't need delete share). Any rename failure is non-fatal. + for name in tmp_names: + var src := builds_root.path_join(name) + var dst := builds_root.path_join(DEAD_PREFIX + name) + if dir.rename(src, dst) == OK: + result.renamed += 1 + dead_names.append(DEAD_PREFIX + name) + + ## Pass 3: best-effort recursive delete of every `_dead_*`, including + ## ones left over from earlier sweeps that couldn't be cleaned then. + for name in dead_names: + var path := builds_root.path_join(name) + if _remove_recursive(path): + result.deleted += 1 + + ## Final pass: count `_dead_*` survivors so the caller (and tests) can + ## see how many genuinely-locked dirs we couldn't reach. + var dir2 := DirAccess.open(builds_root) + if dir2 != null: + dir2.include_hidden = true + dir2.list_dir_begin() + var e := dir2.get_next() + while e != "": + if dir2.current_is_dir() and e.begins_with(DEAD_PREFIX): + result.remaining += 1 + e = dir2.get_next() + dir2.list_dir_end() + + return result + + +## Recursive `rm -rf` that swallows access-denied per-file. Returns true +## only when the target directory itself was removed. +static func _remove_recursive(path: String) -> bool: + var dir := DirAccess.open(path) + if dir == null: + ## Already gone, or unreadable — try a direct remove just in case + ## (an empty dir handle-leak path) and report based on existence. + DirAccess.remove_absolute(path) + return not DirAccess.dir_exists_absolute(path) + dir.include_hidden = true + dir.list_dir_begin() + var entry := dir.get_next() + while entry != "": + if entry == "." or entry == "..": + entry = dir.get_next() + continue + var child := path.path_join(entry) + if dir.current_is_dir(): + _remove_recursive(child) + else: + DirAccess.remove_absolute(child) + entry = dir.get_next() + dir.list_dir_end() + ## Remove the (hopefully now empty) dir itself. If a hard-linked .pyd is + ## still mapped by a surviving process, this fails silently and the + ## caller sees `remaining > 0` so it can retry on the next sweep. + DirAccess.remove_absolute(path) + return not DirAccess.dir_exists_absolute(path) + + +static func _empty_result() -> Dictionary: + return { "scanned": 0, "renamed": 0, "deleted": 0, "remaining": 0 } diff --git a/addons/godot_ai/utils/uv_cache_cleanup.gd.uid b/addons/godot_ai/utils/uv_cache_cleanup.gd.uid new file mode 100644 index 0000000..321659d --- /dev/null +++ b/addons/godot_ai/utils/uv_cache_cleanup.gd.uid @@ -0,0 +1 @@ +uid://d33ukg65qf7q0 diff --git a/addons/godot_ai/utils/variant_serializer.gd b/addons/godot_ai/utils/variant_serializer.gd new file mode 100644 index 0000000..21d8c6e --- /dev/null +++ b/addons/godot_ai/utils/variant_serializer.gd @@ -0,0 +1,102 @@ +@tool +extends RefCounted + +## Converts Godot Variants into values that can be encoded as JSON. + + +## Non-finite floats (NaN/INF) have no JSON representation: JSON.stringify +## emits them as the bare tokens `inf`/`nan`, which are invalid JSON — the +## server drops the whole frame and the pending request times out (#688). +## Serialize them as null instead (the same choice web JSON.stringify makes), +## applied uniformly across the supported 4.5+ floor — no version gate, so +## wire output is identical on every supported engine. +static func _safe_float(f: float) -> Variant: + return f if is_finite(f) else null + + +static func serialize(value: Variant) -> Variant: + if value == null: + return null + match typeof(value): + TYPE_BOOL, TYPE_INT, TYPE_STRING: + return value + TYPE_FLOAT: + return _safe_float(value) + TYPE_STRING_NAME: + return str(value) + # Integer vector types are listed separately from their float twins so + # int components stay ints on the wire (no float coercion via + # _safe_float's typed parameter). + TYPE_VECTOR2I: + return {"x": value.x, "y": value.y} + TYPE_VECTOR2: + return {"x": _safe_float(value.x), "y": _safe_float(value.y)} + TYPE_VECTOR3I: + return {"x": value.x, "y": value.y, "z": value.z} + TYPE_VECTOR3: + return {"x": _safe_float(value.x), "y": _safe_float(value.y), "z": _safe_float(value.z)} + TYPE_VECTOR4I: + return {"x": value.x, "y": value.y, "z": value.z, "w": value.w} + TYPE_VECTOR4, TYPE_QUATERNION: + return { + "x": _safe_float(value.x), + "y": _safe_float(value.y), + "z": _safe_float(value.z), + "w": _safe_float(value.w), + } + TYPE_COLOR: + return { + "r": _safe_float(value.r), + "g": _safe_float(value.g), + "b": _safe_float(value.b), + "a": _safe_float(value.a), + } + TYPE_RECT2, TYPE_RECT2I, TYPE_AABB: + return { + "position": serialize(value.position), + "size": serialize(value.size), + } + TYPE_PLANE: + return {"normal": serialize(value.normal), "d": _safe_float(value.d)} + TYPE_BASIS: + return { + "x": serialize(value.x), + "y": serialize(value.y), + "z": serialize(value.z), + } + TYPE_TRANSFORM2D: + return { + "x": serialize(value.x), + "y": serialize(value.y), + "origin": serialize(value.origin), + } + TYPE_TRANSFORM3D: + return { + "basis": serialize(value.basis), + "origin": serialize(value.origin), + } + TYPE_PROJECTION: + return { + "x": serialize(value.x), + "y": serialize(value.y), + "z": serialize(value.z), + "w": serialize(value.w), + } + TYPE_NODE_PATH: + return str(value) + TYPE_ARRAY, TYPE_PACKED_BYTE_ARRAY, TYPE_PACKED_INT32_ARRAY, TYPE_PACKED_INT64_ARRAY, TYPE_PACKED_FLOAT32_ARRAY, TYPE_PACKED_FLOAT64_ARRAY, TYPE_PACKED_STRING_ARRAY, TYPE_PACKED_VECTOR2_ARRAY, TYPE_PACKED_VECTOR3_ARRAY, TYPE_PACKED_VECTOR4_ARRAY, TYPE_PACKED_COLOR_ARRAY: + var arr: Array = [] + for item in value: + arr.append(serialize(item)) + return arr + TYPE_DICTIONARY: + var out := {} + for key in value: + out[str(key)] = serialize(value[key]) + return out + TYPE_OBJECT: + if value is Resource and value.resource_path: + return value.resource_path + return str(value) + _: + return str(value) diff --git a/addons/godot_ai/utils/variant_serializer.gd.uid b/addons/godot_ai/utils/variant_serializer.gd.uid new file mode 100644 index 0000000..b8e0a28 --- /dev/null +++ b/addons/godot_ai/utils/variant_serializer.gd.uid @@ -0,0 +1 @@ +uid://cte37mtbd61n3 diff --git a/addons/godot_ai/utils/windows_port_reservation.gd b/addons/godot_ai/utils/windows_port_reservation.gd new file mode 100644 index 0000000..23b4f43 --- /dev/null +++ b/addons/godot_ai/utils/windows_port_reservation.gd @@ -0,0 +1,146 @@ +@tool +class_name McpWindowsPortReservation +extends RefCounted + +## Detects whether Windows has reserved a TCP port range that covers the +## plugin's server port. Hyper-V, WSL2, Docker Desktop, and Windows +## Sandbox all grab port ranges at boot via the winnat service. When a +## user's chosen port sits inside a reserved range, bind(2) fails with +## WinError 10013 ("forbidden by its access permissions") rather than +## 10048 ("address in use") — `netstat` shows nothing because no process +## owns the port, making the failure invisible. See issue #146. + +const NETSH_ARGS := ["interface", "ipv4", "show", "excludedportrange", "protocol=tcp"] + +## Session-lifetime cache. winnat establishes its excluded-port ranges at +## boot, so the table is effectively static for an editor session — while +## a `netsh` spawn costs ~250ms (measured), which the old 2s TTL re-paid +## on every startup walk (and could even re-pay *within* one walk when +## server-command discovery ran long between the two netsh consumers). +## Staleness risk is bounded: a mid-session winnat change (Docker/WSL2 +## start) at worst yields the same failure mode as the pre-#146 code for +## the remainder of the session, and only if a spawn happens after it. +static var _netsh_cache_text := "" +static var _netsh_cache_valid := false +static var _netsh_query_count := 0 + + +## Returns true if `port` falls inside a currently-reserved range on this +## Windows host. No-op on non-Windows (returns false). +static func is_port_excluded(port: int) -> bool: + if OS.get_name() != "Windows": + return false + var cached := _get_cached_excluded_output() + if bool(cached.get("hit", false)): + return parse_excluded(str(cached.get("text", "")), port) + var output: Array = [] + var exit_code := _execute_netsh_excluded_ranges(output) + if exit_code != 0 or output.is_empty(): + return false + var text := str(output[0]) + _store_excluded_output(text) + return parse_excluded(text, port) + + +static func _store_excluded_output(text: String) -> void: + _netsh_cache_text = text + _netsh_cache_valid = true + + +static func _get_cached_excluded_output() -> Dictionary: + if not _netsh_cache_valid: + return {"hit": false, "text": ""} + return {"hit": true, "text": _netsh_cache_text} + + +static func _clear_cache_for_tests() -> void: + _netsh_cache_text = "" + _netsh_cache_valid = false + + +static func netsh_query_count() -> int: + return _netsh_query_count + + +static func _execute_netsh_excluded_ranges(output: Array) -> int: + _netsh_query_count += 1 + return OS.execute("netsh", NETSH_ARGS, output, true) + + +## Parse the `netsh` excluded-port-range output and return true if `port` +## sits inside any reserved range. Exposed for testing; the live check +## uses `is_port_excluded`. Expected input format: +## +## Protocol tcp Port Exclusion Ranges +## +## Start Port End Port +## ---------- -------- +## 80 80 +## 5040 5040 +## 8000 8099 +## +## * - Administered port exclusions. +static func parse_excluded(text: String, port: int) -> bool: + return _ranges_contain(parse_excluded_ranges(text), port) + + +## Parse the `netsh` excluded-port-range output once into inclusive ranges. +static func parse_excluded_ranges(text: String) -> Array[Vector2i]: + var ranges: Array[Vector2i] = [] + for line in text.split("\n"): + var trimmed := line.strip_edges() + if trimmed.is_empty() or trimmed.begins_with("-") or trimmed.begins_with("*"): + continue + var parts: PackedStringArray = trimmed.split(" ", false) + if parts.size() < 2: + continue + if not parts[0].is_valid_int() or not parts[1].is_valid_int(): + continue + var start_p := int(parts[0]) + var end_p := int(parts[1]) + ranges.append(Vector2i(start_p, end_p)) + return ranges + + +static func _ranges_contain(ranges: Array[Vector2i], port: int) -> bool: + for r in ranges: + if port >= r.x and port <= r.y: + return true + return false + + +## Return the first port in `start`..`start+span-1` that is not excluded by +## Windows' port reservation table. Runs `netsh` once, unlike probing every +## candidate with `is_port_excluded`, which keeps fallback port selection cheap +## when Hyper-V / WSL2 / Docker reserve many adjacent ranges. +static func suggest_non_excluded_port(start: int, span: int = 2048, max_port: int = 65535) -> int: + if OS.get_name() != "Windows": + return start + var cached := _get_cached_excluded_output() + if bool(cached.get("hit", false)): + return suggest_non_excluded_port_from_output(str(cached.get("text", "")), start, span, max_port) + var output: Array = [] + var exit_code := _execute_netsh_excluded_ranges(output) + if exit_code != 0 or output.is_empty(): + return start + var text := str(output[0]) + _store_excluded_output(text) + return suggest_non_excluded_port_from_output(text, start, span, max_port) + + +## Pure parser-backed helper for tests and for `suggest_non_excluded_port`. +static func suggest_non_excluded_port_from_output(text: String, start: int, span: int = 2048, max_port: int = 65535) -> int: + var ranges := parse_excluded_ranges(text) + var limit := mini(start + span - 1, max_port) + var p := start + while p <= limit: + var advanced := false + for r in ranges: + if p >= r.x and p <= r.y: + p = r.y + 1 + advanced = true + break + if not advanced: + return p + return start + diff --git a/addons/godot_ai/utils/windows_port_reservation.gd.uid b/addons/godot_ai/utils/windows_port_reservation.gd.uid new file mode 100644 index 0000000..ffc5746 --- /dev/null +++ b/addons/godot_ai/utils/windows_port_reservation.gd.uid @@ -0,0 +1 @@ +uid://bt7mxpjcdrobq diff --git a/addons/godot_ai/vision_routing.gd b/addons/godot_ai/vision_routing.gd new file mode 100644 index 0000000..2f42cef --- /dev/null +++ b/addons/godot_ai/vision_routing.gd @@ -0,0 +1,1043 @@ +@tool +extends RefCounted + +## Vision Routing - route screenshot-tool images through a curated vision API. +## +## Models without image support (e.g. DeepSeek) cannot read the image blocks the +## screenshot tool returns. When routing is enabled, every single-image capture is sent to a +## vision model on a worker thread and the resulting text description is +## returned to the AI instead: +## +## - Editor (non-game) screenshots are captured normally by +## editor_handler.gd, then described on a worker thread; the reply is +## deferred until the description is ready. +## - Game screenshots are intercepted in mcp_debugger_plugin.gd the same way. +## - On success the response keeps a valid but tiny 2x2 placeholder image and +## carries the description as text metadata (`vision_description` plus a +## `note`, which the server forwards to the model). +## - On failure (missing key, network, API error) the original image payload +## passes through unchanged, so the screenshot tool never breaks. +## +## Providers are curated: label, API dialect, endpoint shape, environment +## variable and encrypted key slot are fixed in the PROVIDERS table. The model +## id is NOT - it is required per provider and entered by the user (stored in +## Editor Settings next to the key), because third-party model ids retire and +## only the account holder gets notified. Switching providers switches to that +## provider's entered model, so the software never guesses a model name: +## - Groq (free tier) - OpenAI chat-completions +## - Google Gemini (free tier, AI Studio key) - generateContent REST +## - xAI Grok (paid) - OpenAI chat-completions +## Both dialects are handled in this file. +## +## Settings live in Editor Settings (`vision_routing/enabled`, +## `vision_routing/provider`, plus one encrypted key slot and one model-id +## slot per provider). Keys are stored encrypted (AES-256-CBC, key derived +## from this machine) rather than in plain text, and each provider's +## environment variable (GROQ_API_KEY / GOOGLE_API_KEY / XAI_API_KEY) takes +## priority over the stored key. +## +## UI: a "Vision Routing" section inside the Clients & Tools Settings tab. + +## Curated providers: label, dialect, endpoint shape, env var and key/model +## setting slots are fixed here. The model id itself is user-entered per +## provider (see `_resolved_model`), so provider rows carry a `model_setting` +## slot and a `model_placeholder` suggestion instead of a baked-in id - +## third-party model ids retire, and only the account holder gets notified +## when one does. +const PROVIDERS := { + "groq": { + "label": "Groq", + "dialect": "openai", + "model_setting": "vision_routing/groq_model", + "model_placeholder": "qwen/qwen3.6-27b", + "host": "api.groq.com", + "port": 443, + "path": "/openai/v1/chat/completions", + "env": "GROQ_API_KEY", + "setting": "vision_routing/api_key_enc", + "placeholder": "gsk_...", + "key_label": "Groq API key (free tier: console.groq.com)", + "reasoning_effort": "none", + }, + "google": { + "label": "Google Gemini", + "dialect": "gemini", + "host": "generativelanguage.googleapis.com", + "port": 443, + "path": "/v1beta/models/{model}:generateContent", + "model_setting": "vision_routing/google_model", + "model_placeholder": "gemini-flash-latest", + "env": "GOOGLE_API_KEY", + "setting": "vision_routing/google_api_key_enc", + "placeholder": "AIza...", + "key_label": "Google AI Studio API key (free tier: aistudio.google.com)", + }, + "grok": { + "label": "xAI Grok", + "dialect": "openai", + "model_setting": "vision_routing/grok_model", + "model_placeholder": "grok-4.5", + "host": "api.x.ai", + "port": 443, + "path": "/v1/chat/completions", + "env": "XAI_API_KEY", + "setting": "vision_routing/grok_api_key_enc", + "placeholder": "xai-...", + "key_label": "xAI API key (api.x.ai)", + }, +} +const PROVIDER_ORDER := ["groq", "google", "grok"] + +const SETTING_ENABLED := "vision_routing/enabled" +const SETTING_PROVIDER := "vision_routing/provider" +const SETTING_API_KEY_ENC := "vision_routing/api_key_enc" +const TAB_NAME := "Vision Routing" + +const MAX_IMAGE_EDGE := 1024 +const CONNECT_TIMEOUT_MS := 4000 +const REQUEST_TIMEOUT_MS := 8000 +## Total budget for the whole provider exchange (connect + request + body). +## Kept under the server's 15s editor_screenshot window so the fallback +## pass-through always lands before the server gives up on slow providers. +const TOTAL_ROUTE_BUDGET_MS := 10000 +## Response body cap: the deadline bounds time but not bytes, and the socket +## talks to third-party hosts - a faulty or hostile provider must not be able +## to stream an unbounded body inside the window. +const MAX_RESPONSE_BODY_BYTES := 1048576 +## Output-token budget shared by both dialects (OpenAI `max_tokens`, +## Gemini `generationConfig.maxOutputTokens`) so routed descriptions +## stay bounded. +const MAX_OUTPUT_TOKENS := 512 + +const _ENC_PREFIX := "v1" +const _SALT := "vision_routing::v1::godot-ai" +const _PLACEHOLDER_PNG := "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAALSURBVBhXY2BABwAAEgABp3qZbgAAAABJRU5ErkJggg==" + +## Plugin log buffer (McpLogBuffer), set by plugin.gd; null-safe. +var log_buffer: Object = null + +var _active := true +var _route_done: Callable +var _pending: Dictionary = {} # request_id -> {payload, data, connection, provider_id, provider, params} +var _threads: Dictionary = {} # request_id -> Thread ("_test" = ping thread) +var _ui_loading := false + +# UI references, kept in sync by _sync_ui_states(). +var _tab_provider: OptionButton = null +var _tab_enable: CheckButton = null +var _tab_key_label: Label = null +var _tab_key_hint: Label = null +var _tab_key_edit: LineEdit = null +var _tab_model_label: Label = null +var _tab_model_hint: Label = null +var _tab_model_edit: LineEdit = null +var _tab_status: Label = null +var _tab_test_button: Button = null + + +func _init() -> void: + _route_done = Callable(self, "_on_route_complete") + + +## Plugin teardown: stop workers and join in-flight threads so Godot never +## destroys a Thread mid-execution during a plugin reload. +func shutdown() -> void: + _active = false + ## Workers poll _active between HTTP polls, so this returns within one + ## poll interval (~50ms) unless a request is mid-flight in the OS; worst + ## case is a connect/request timeout. + for rid in _threads: + var thread: Thread = _threads[rid] + if thread != null and thread.is_started(): + thread.wait_to_finish() + _threads.clear() + _pending.clear() + _tab_provider = null + _tab_enable = null + _tab_key_label = null + _tab_key_hint = null + _tab_key_edit = null + _tab_status = null + _tab_test_button = null + _tab_model_label = null + _tab_model_hint = null + _tab_model_edit = null + + +# --- routing ------------------------------------------------------------------ + +## Entry point called from editor_handler.take_screenshot when routing is +## enabled. Runs the real capture (via `original`), then routes the image +## through the selected provider's vision API on a worker thread. Returns the deferred-response sentinel +## when the worker owns the reply, otherwise the capture result unchanged. +func route_editor_screenshot(params: Dictionary, original: Callable, connection: Object) -> Dictionary: + var rid := str(params.get("_request_id", "")) + if rid.is_empty(): + ## No deferred channel (e.g. batch_execute / dispatch_direct) - keep + ## the original synchronous result untouched. + return original.call(params) + var result := original.call(params) + if not (result is Dictionary) or not result.has("data"): + ## Deferred capture (source="game"): the frame arrives later through + ## route_game_payload. Stash the caller params (e.g. user_prompt) by + ## request id so the routed description keeps the agent's context. + if result is Dictionary and result.get("_deferred", false): + _pending[rid] = {"params": params} + return result + var data: Variant = result["data"] + if not (data is Dictionary) or not data.has("image_base64"): + return result + if _start_route(rid, str(params.get("source", "viewport")), result, data, connection, params): + ## Keep the deferred ledger inside the server's 15s editor_screenshot + ## window (the worker itself is capped at TOTAL_ROUTE_BUDGET_MS), so + ## a hung provider surfaces as a clean plugin timeout, not a + ## server-side abort. + return {"_deferred": true, "_deferred_timeout_ms": 13000} + return result + + +## Entry point called from McpDebuggerPlugin._on_screenshot_response before +## the frame is sent. Returns true when a worker owns the reply (the caller +## must NOT send the payload itself); false means pass through unchanged. +func route_game_payload(connection: Object, rid: String, payload: Dictionary) -> bool: + var data: Variant = payload.get("data") + if not (data is Dictionary) or not data.has("image_base64"): + ## Not a routeable frame - drop any params stashed by + ## route_editor_screenshot for this request id. + _pending.erase(rid) + return false + ## The editor handler stashed the caller params (user_prompt etc.) by + ## request id when it deferred the capture; hand them to the prompt + ## builder. Absent (older helper, direct call) = generic prompt. + var params: Dictionary = _pending.get(rid, {}).get("params", {}) + return _start_route(rid, "game", payload, data, connection, params) + + +## Returns true when a worker owns the reply; false means the caller should +## pass the original payload through unchanged. +func _start_route(rid: String, source: String, payload: Dictionary, data: Dictionary, connection: Object, params: Dictionary) -> bool: + var provider_id := _active_provider_id() + var base_provider: Dictionary = PROVIDERS.get(provider_id, PROVIDERS["groq"]) + ## Worker-thread snapshot: the entered model id is resolved into the + ## provider dict here, once, so the thread sees a stable copy and + ## routed_via can report the exact model that was pinged. + var provider := _provider_with_model(provider_id) + var api_key := _resolved_api_key(provider_id) + if api_key.is_empty(): + _log("vision routing: no API key for %s (set %s or paste one in the Vision Routing section) - screenshot %s passed through" % [provider_id, base_provider.get("env", ""), rid]) + _pending.erase(rid) + return false + if str(provider.get("model", "")).is_empty(): + ## Empty model behaves exactly like empty key: routing declines, the + ## image passes through, and the log line says what is missing. + _log("vision routing: no model id set for %s - screenshot %s passed through (set a model id in the Vision Routing section)" % [provider_id, rid]) + _pending.erase(rid) + return false + _pending[rid] = {"payload": payload, "data": data, "connection": connection, "provider_id": provider_id, "provider": provider, "params": params} + var prompt := _build_prompt(params) + var thread := Thread.new() + var start_err := thread.start(_route_worker.bind(provider, str(data.get("image_base64", "")), prompt, api_key, rid)) + if start_err != OK: + _pending.erase(rid) + _log("vision routing: could not start worker for %s: %s - screenshot %s passed through" % [rid, error_string(start_err), source]) + return false + _threads[rid] = thread + _log("vision routing: routing %s screenshot %s (%d b64 chars) via %s (%s)" % [source, rid, str(data.get("image_base64", "")).length(), base_provider.get("label", provider_id), provider.get("model", "")]) + return true + + +func _on_route_complete(rid: String, result: Variant) -> void: + _join_thread(rid) + if not _active: + _pending.erase(rid) + return + var entry: Dictionary = _pending.get(rid, {}) + _pending.erase(rid) + if entry.is_empty(): + return + var connection: Object = entry.get("connection") + if connection == null or not is_instance_valid(connection): + return + var provider_id := str(entry.get("provider_id", "groq")) + ## Provider snapshot taken at route start (with the entered model id); + ## falls back to a fresh resolve if absent (direct test callers). + var provider: Dictionary = entry.get("provider", {}) + if provider.is_empty(): + provider = _provider_with_model(provider_id) + ## Workers return {"desc": ..., "error": ...}; plain strings are accepted + ## for backwards compatibility (tests / older callers). + var description_str := "" + var error_str := "" + if result is Dictionary: + description_str = str(result.get("desc", "")) + error_str = str(result.get("error", "")) + elif result != null: + description_str = str(result) + if description_str.is_empty(): + if error_str.is_empty(): + error_str = "unknown error" + _log("vision routing: %s failed for %s (%s) - returning original image with failure note" % [provider_id, rid, error_str]) + ## Append a short templated reason to the note so text-only agents + ## (who otherwise just receive a useless image block) learn the + ## feature is down and why. + var failed_data: Dictionary = entry.get("data", {}).duplicate() + var failure_note := "Vision routing unavailable (%s): %s" % [provider_id, error_str] + var existing_note := str(failed_data.get("note", "")) + failed_data["note"] = (existing_note + " | " if not existing_note.is_empty() else "") + failure_note + _pass_through(connection, rid, {"data": failed_data}) + return + var data: Dictionary = entry.get("data", {}).duplicate() + var routed_via := "%s:%s" % [provider_id, provider.get("model", "")] + ## The server forwards a fixed whitelist of metadata keys into the text + ## result; `note` is the free-form one, so a self-attributing description + ## rides there (plus an explicit `vision_description` key) so text-only + ## models can read it. The label keeps provider text from reading as if + ## the plugin said it. The image is replaced by a valid 2x2 placeholder + ## so the payload stays well-formed. + data["vision_description"] = description_str + data["routed_via"] = routed_via + var original_note := str(data.get("note", "")) + var labeled := "Vision description (%s): %s" % [routed_via, description_str] + data["note"] = (original_note + " | " if not original_note.is_empty() else "") + labeled + data["image_base64"] = _PLACEHOLDER_PNG + data["format"] = "png" + _log("vision routing: description ready for %s (%d chars)" % [rid, description_str.length()]) + _pass_through(connection, rid, {"data": data}) + + +func _pass_through(connection: Object, rid: String, payload: Dictionary) -> void: + if connection != null and is_instance_valid(connection): + connection.send_deferred_response(rid, payload) + + +func _build_prompt(params: Dictionary) -> String: + var lines := PackedStringArray([ + "You are the vision module of a text-only AI agent driving the Godot editor through MCP.", + "Describe this screenshot so the agent can act without seeing it. Report:", + "- What is shown: Godot editor viewport, game window, 2D/3D scene, UI panel, dialog, or other.", + "- Objects/nodes: what they are, position, color, size, and any labels or text (quote text exactly).", + "- UI text: menus, buttons, error dialogs, console output, warnings, line numbers.", + "- State: selected node outlines, gizmos, play/stop status, panels that are open.", + "- Problems: errors, red highlights, missing textures, black screens, glitches, stretching.", + "Be concise (under 200 words), factual, and use exact quotes instead of paraphrase. Do not give advice.", + ]) + var user_prompt := str(params.get("user_prompt", "")) + if not user_prompt.is_empty(): + lines.append("Context from the agent that requested this screenshot: %s" % user_prompt) + return "\n".join(lines) + + +# --- routing worker (thread) --------------------------------------------------- + +func _route_worker(provider: Dictionary, image_b64: String, prompt: String, api_key: String, rid: String) -> void: + var result := _describe_blocking(provider, image_b64, prompt, api_key) + _route_done.call_deferred(rid, result) + + +## Returns {"desc": String, "error": String}; "desc" is empty on failure and +## "error" carries the reason. Runs on a worker thread, so it never writes +## shared state - everything it needs is passed in and returned. `provider` +## is the route-start snapshot (includes the entered model id). +func _describe_blocking(provider: Dictionary, image_b64: String, prompt: String, api_key: String) -> Dictionary: + var b64 := _downscale_image_if_needed(image_b64) + var body := _build_request_body(provider, prompt, b64) + var headers := _build_headers(provider, api_key) + var response := _http_post_json(str(provider.get("host", "")), int(provider.get("port", 443)), _resolve_path(provider), headers, body) + return _parse_description(provider, response) + + +## Provider paths may carry a {model} placeholder (Gemini's endpoint embeds +## the model id); substitute the entered model id verbatim. +func _resolve_path(provider: Dictionary) -> String: + return str(provider.get("path", "")).replace("{model}", str(provider.get("model", ""))) + + +func _build_request_body(provider: Dictionary, prompt: String, image_b64: String) -> String: + var model := str(provider.get("model", "")) + if str(provider.get("dialect", "")) == "gemini": + return JSON.stringify({ + "contents": [{ + "role": "user", + "parts": [ + {"text": prompt}, + {"inline_data": {"mime_type": "image/png", "data": image_b64}}, + ], + }], + "generationConfig": {"maxOutputTokens": MAX_OUTPUT_TOKENS}, + }) + var payload := { + "model": model, + "messages": [{ + "role": "user", + "content": [ + {"type": "text", "text": prompt}, + {"type": "image_url", "image_url": {"url": "data:image/png;base64," + image_b64}}, + ], + }], + "max_tokens": MAX_OUTPUT_TOKENS, + "temperature": 0.2, + } + if provider.has("reasoning_effort"): + payload["reasoning_effort"] = provider["reasoning_effort"] + return JSON.stringify(payload) + + +func _build_headers(provider: Dictionary, api_key: String) -> PackedStringArray: + if str(provider.get("dialect", "")) == "gemini": + return PackedStringArray([ + "Content-Type: application/json", + "x-goog-api-key: %s" % api_key, + ]) + return PackedStringArray([ + "Content-Type: application/json", + "Authorization: Bearer %s" % api_key, + ]) + + +func _parse_description(provider: Dictionary, response: Dictionary) -> Dictionary: + var code: int = int(response.get("code", 0)) + var label := str(provider.get("label", str(provider.get("model", "?")))) + if code == 0: + return {"desc": "", "error": str(response.get("error", "HTTP request failed"))} + if code != 200: + return {"desc": "", "error": "%s HTTP %d: %s" % [label, code, _body_snippet(str(response.get("text", "")))]} + var parsed: Variant = JSON.parse_string(str(response.get("text", ""))) + if not (parsed is Dictionary): + return {"desc": "", "error": "%s response was not JSON: %s" % [label, _body_snippet(str(response.get("text", "")))]} + if str(provider.get("dialect", "")) == "gemini": + return _parse_gemini(parsed, label, response) + return _parse_openai(parsed, label, response) + + +func _parse_openai(parsed: Dictionary, label: String, response: Dictionary) -> Dictionary: + var choices: Variant = parsed.get("choices") + if not (choices is Array) or choices.is_empty(): + return {"desc": "", "error": "%s response had no choices: %s" % [label, _body_snippet(str(response.get("text", "")))]} + if not (choices[0] is Dictionary): + return {"desc": "", "error": "%s response choice was not an object: %s" % [label, _body_snippet(str(response.get("text", "")))]} + var message: Variant = choices[0].get("message", {}) + if not (message is Dictionary): + return {"desc": "", "error": "%s response message was not an object: %s" % [label, _body_snippet(str(response.get("text", "")))]} + var content: Variant = message.get("content", "") + if content == null: + return {"desc": "", "error": "%s response content was null: %s" % [label, _body_snippet(str(response.get("text", "")))]} + return {"desc": _strip_think(str(content)), "error": ""} + + +func _parse_gemini(parsed: Dictionary, label: String, response: Dictionary) -> Dictionary: + var candidates: Variant = parsed.get("candidates") + if not (candidates is Array) or candidates.is_empty(): + var reason := "" + var feedback: Variant = parsed.get("promptFeedback") + if feedback is Dictionary: + reason = str(feedback.get("blockReason", "")) + var reason_part := "" + if not reason.is_empty(): + reason_part = " (blocked: %s)" % reason + return {"desc": "", "error": "%s response had no candidates%s: %s" % [label, reason_part, _body_snippet(str(response.get("text", "")))]} + if not (candidates[0] is Dictionary): + return {"desc": "", "error": "%s response candidate was not an object: %s" % [label, _body_snippet(str(response.get("text", "")))]} + var content: Variant = candidates[0].get("content", {}) + if not (content is Dictionary): + return {"desc": "", "error": "%s response content was missing: %s" % [label, _body_snippet(str(response.get("text", "")))]} + var parts: Variant = content.get("parts") + if not (parts is Array) or parts.is_empty(): + return {"desc": "", "error": "%s response had no parts: %s" % [label, _body_snippet(str(response.get("text", "")))]} + var texts := PackedStringArray() + for part in parts: + if part is Dictionary: + var part_text := str(part.get("text", "")) + if not part_text.is_empty(): + texts.append(part_text) + if texts.is_empty(): + return {"desc": "", "error": "%s response parts had no text: %s" % [label, _body_snippet(str(response.get("text", "")))]} + return {"desc": _strip_think("\n".join(texts)), "error": ""} + + +func _strip_think(text: String) -> String: + var out := text.strip_edges() + ## Reasoning models may wrap their answer in ... blocks. + var think_end := out.rfind("") + if think_end != -1: + out = out.substr(think_end + "".length()).strip_edges() + return out + + +## Minimal vision call used by the "Test connection" button. Sends the same +## image-bearing body shape as real routing (with the 2x2 placeholder PNG), +## so one click validates key + model existence + image capability - a +## text-only or retired model id fails loudly here instead of at screenshot +## time. `provider` is the route-style snapshot (includes the model id). +func _ping_blocking(provider: Dictionary, api_key: String) -> Dictionary: + var body := _build_request_body(provider, "Reply with exactly: OK", _PLACEHOLDER_PNG) + var response := _http_post_json(str(provider.get("host", "")), int(provider.get("port", 443)), _resolve_path(provider), _build_headers(provider, api_key), body) + var code: int = int(response.get("code", 0)) + if code == 200: + return {"ok": true, "error": ""} + if code == 0: + return {"ok": false, "error": str(response.get("error", "request failed"))} + return {"ok": false, "error": "%s HTTP %d: %s" % [provider.get("label", "provider"), code, _body_snippet(str(response.get("text", "")))]} + + +func _http_post_json(host: String, port: int, path: String, headers: PackedStringArray, body: String) -> Dictionary: + if host.is_empty() or body.is_empty(): + return {"code": 0, "error": "invalid request (empty host or body)"} + var http := HTTPClient.new() + var connect_err := http.connect_to_host(host, port, TLSOptions.client()) + if connect_err != OK: + http.close() + return {"code": 0, "error": "connect_to_host failed: %s" % error_string(connect_err)} + ## One total deadline for the whole exchange (see TOTAL_ROUTE_BUDGET_MS), + ## so connect + request + body can never exceed it. + var budget_deadline := Time.get_ticks_msec() + TOTAL_ROUTE_BUDGET_MS + var deadline := mini(Time.get_ticks_msec() + CONNECT_TIMEOUT_MS, budget_deadline) + var first_poll := true + var connected := false + var last_status := -1 + while Time.get_ticks_msec() < deadline: + if not _active: + http.close() + return {"code": 0, "error": "aborted (plugin teardown)"} + http.poll() + var status := http.get_status() + last_status = status + if status == HTTPClient.STATUS_CONNECTED: + connected = true + break + if status == HTTPClient.STATUS_DISCONNECTED and not first_poll: + break + first_poll = false + OS.delay_msec(50) + if not connected: + http.close() + return {"code": 0, "error": "could not connect (status %d)" % last_status} + if http.request(HTTPClient.METHOD_POST, path, headers, body) != OK: + http.close() + return {"code": 0, "error": "request() failed"} + deadline = mini(Time.get_ticks_msec() + REQUEST_TIMEOUT_MS, budget_deadline) + var timed_out := false + var status_at_timeout := -1 + while http.get_status() == HTTPClient.STATUS_REQUESTING: + if not _active: + http.close() + return {"code": 0, "error": "aborted (plugin teardown)"} + http.poll() + if Time.get_ticks_msec() > deadline: + timed_out = true + status_at_timeout = http.get_status() + break + OS.delay_msec(50) + if timed_out: + http.close() + return {"code": 0, "error": "request timed out (status %d)" % status_at_timeout} + if not http.has_response(): + var st := http.get_status() + http.close() + return {"code": 0, "error": "no HTTP response (status %d)" % st} + var code := http.get_response_code() + var chunks := PackedByteArray() + var body_deadline := mini(Time.get_ticks_msec() + REQUEST_TIMEOUT_MS, budget_deadline) + while http.get_status() == HTTPClient.STATUS_BODY: + if not _active: + http.close() + return {"code": 0, "error": "aborted (plugin teardown)"} + chunks.append_array(http.read_response_body_chunk()) + if chunks.size() > MAX_RESPONSE_BODY_BYTES: + http.close() + return {"code": 0, "error": "response body exceeded %d bytes" % MAX_RESPONSE_BODY_BYTES} + http.poll() + if Time.get_ticks_msec() > body_deadline: + break + OS.delay_msec(10) + http.close() + return {"code": code, "text": chunks.get_string_from_utf8()} + + +func _body_snippet(text: String) -> String: + if text.is_empty(): + return "(empty body)" + if text.length() > 300: + return text.substr(0, 300) + "..." + return text + + +func _join_thread(rid: String) -> void: + ## Join the worker before dropping the Thread reference, otherwise Godot + ## warns "Thread object destroyed without completion". + var thread: Thread = _threads.get(rid) + if thread != null and thread.is_started(): + thread.wait_to_finish() + _threads.erase(rid) + + +func _downscale_image_if_needed(image_b64: String) -> String: + if image_b64.is_empty(): + return image_b64 + var raw := Marshalls.base64_to_raw(image_b64) + if raw.is_empty(): + return image_b64 + var image := Image.new() + if image.load_png_from_buffer(raw) != OK: + return image_b64 + var width := image.get_width() + var height := image.get_height() + if width <= MAX_IMAGE_EDGE and height <= MAX_IMAGE_EDGE: + return image_b64 + if width >= height: + height = maxi(1, int(round(height * MAX_IMAGE_EDGE / float(width)))) + width = MAX_IMAGE_EDGE + else: + width = maxi(1, int(round(width * MAX_IMAGE_EDGE / float(height)))) + height = MAX_IMAGE_EDGE + image.resize(width, height, Image.INTERPOLATE_BILINEAR) + var out := image.save_png_to_buffer() + if out.is_empty(): + return image_b64 + return Marshalls.raw_to_base64(out) + + +func _ping_worker(provider: Dictionary, api_key: String, status_label: Label, key_source: String) -> void: + var result := _ping_blocking(provider, api_key) + Callable(self, "_on_ping_done").call_deferred(result, provider, status_label, key_source) + + +func _on_ping_done(result: Dictionary, provider: Dictionary, status_label: Label, key_source: String) -> void: + _join_thread("_test") + if _tab_test_button != null and is_instance_valid(_tab_test_button): + _tab_test_button.disabled = false + if status_label != null and is_instance_valid(status_label): + var label := str(provider.get("label", "provider")) + if result.get("ok", false): + status_label.text = "OK - %s responded (%s)." % [label, key_source] + else: + status_label.text = "FAILED - %s (%s)." % [result.get("error", "unknown error"), key_source] + _log("vision routing: ping result: %s" % status_label.text) + + +# --- settings / key storage --------------------------------------------------- + +func _settings() -> EditorSettings: + return EditorInterface.get_editor_settings() + + +func is_routing_enabled() -> bool: + var es := _settings() + if es == null or not es.has_setting(SETTING_ENABLED): + return false + var value = es.get_setting(SETTING_ENABLED) + return value != null and value + + +func _active_provider_id() -> String: + var es := _settings() + if es == null: + return "groq" + var stored := "" + if es.has_setting(SETTING_PROVIDER): + stored = str(es.get_setting(SETTING_PROVIDER)) + if stored.is_empty() or not PROVIDERS.has(stored): + return "groq" + return stored + + +func _provider_setting(provider_id: String) -> String: + return str(PROVIDERS.get(provider_id, PROVIDERS["groq"]).get("setting", SETTING_API_KEY_ENC)) + + +func _resolved_api_key(provider_id: String) -> String: + ## Environment variable takes priority over the stored (encrypted) key. + var provider: Dictionary = PROVIDERS.get(provider_id, PROVIDERS["groq"]) + var env_key := OS.get_environment(str(provider.get("env", ""))) + if not env_key.is_empty(): + return env_key + var es := _settings() + if es == null: + return "" + var setting := _provider_setting(provider_id) + var blob := "" + if es.has_setting(setting): + blob = str(es.get_setting(setting)) + if blob.is_empty(): + return "" + return _decrypt(blob) + + +func _decrypted_key(provider_id: String) -> String: + var es := _settings() + if es == null: + return "" + var setting := _provider_setting(provider_id) + if not es.has_setting(setting): + return "" + return _decrypt(str(es.get_setting(setting))) + + +func set_api_key(provider_id: String, plain: String) -> void: + var es := _settings() + if es == null: + return + if plain.is_empty(): + es.set_setting(_provider_setting(provider_id), "") + return + var blob := _encrypt(plain) + if blob.is_empty(): + _log("vision routing: cannot store %s key - this machine reports no unique id; set %s instead" % [provider_id, PROVIDERS.get(provider_id, PROVIDERS["groq"]).get("env", "")]) + return + es.set_setting(_provider_setting(provider_id), blob) + + +## The model id is stored per provider next to the key (a plain Editor +## Setting - it is not a secret). Empty clears the slot. +func set_model_id(provider_id: String, model: String) -> void: + var es := _settings() + if es == null: + return + es.set_setting(_model_setting(provider_id), model.strip_edges()) + + +func _model_setting(provider_id: String) -> String: + return str(PROVIDERS.get(provider_id, PROVIDERS["groq"]).get("model_setting", "")) + + +func _resolved_model(provider_id: String) -> String: + var es := _settings() + if es == null: + return "" + var setting := _model_setting(provider_id) + if not es.has_setting(setting): + return "" + return str(es.get_setting(setting)).strip_edges() + + +## Route-start snapshot: the curated provider table plus the user's entered +## model id. Used by the worker thread and by _on_route_complete for the +## routed_via label, so it always reports the model that was actually pinged. +func _provider_with_model(provider_id: String) -> Dictionary: + var provider: Dictionary = PROVIDERS.get(provider_id, PROVIDERS["groq"]).duplicate() + provider["model"] = _resolved_model(provider_id) + return provider + + +## Machine-derived key: not a password, but enough that a casually-opened +## editor_settings-4.tres does not reveal the key in plain text. Separate +## domain tags give AES and HMAC independent keys so neither reuses the +## other's bytes. +func _derive_key(tag: String) -> PackedByteArray: + var parts := PackedStringArray([ + OS.get_unique_id(), + OS.get_environment("USERNAME"), + OS.get_environment("USERPROFILE"), + OS.get_environment("USER"), + OS.get_environment("HOME"), + OS.get_name(), + _SALT, + tag, + ]) + var ctx := HashingContext.new() + ctx.start(HashingContext.HASH_SHA256) + ctx.update(("|".join(parts)).to_utf8_buffer()) + return ctx.finish() + + +func _encrypt(plain: String) -> String: + if OS.get_unique_id().is_empty(): + ## Without a machine id the key would be near-constant across users + ## on the same machine - refuse, and let callers fall back to the + ## provider's environment variable. + return "" + var aes_key := _derive_key("aes") + var mac_key := _derive_key("mac") + var iv := Crypto.new().generate_random_bytes(16) + var raw := plain.to_utf8_buffer() + ## PKCS7 padding. + var pad := 16 - (raw.size() % 16) + var padded := raw.duplicate() + for i in pad: + padded.append(pad) + var aes := AESContext.new() + aes.start(AESContext.MODE_CBC_ENCRYPT, aes_key, iv) + var cipher := aes.update(padded) + aes.finish() + var hmac := HMACContext.new() + hmac.start(HashingContext.HASH_SHA256, mac_key) + hmac.update(iv) + hmac.update(cipher) + var mac := hmac.finish() + return "%s:%s:%s:%s" % [_ENC_PREFIX, Marshalls.raw_to_base64(iv), Marshalls.raw_to_base64(mac), Marshalls.raw_to_base64(cipher)] + + +func _decrypt(blob: String) -> String: + var parts := blob.split(":") + if parts.size() != 4 or parts[0] != _ENC_PREFIX: + return "" + var iv := Marshalls.base64_to_raw(parts[1]) + var mac := Marshalls.base64_to_raw(parts[2]) + var cipher := Marshalls.base64_to_raw(parts[3]) + if iv.size() != 16 or cipher.is_empty() or cipher.size() % 16 != 0: + return "" + var aes_key := _derive_key("aes") + var mac_key := _derive_key("mac") + var hmac := HMACContext.new() + hmac.start(HashingContext.HASH_SHA256, mac_key) + hmac.update(iv) + hmac.update(cipher) + var expected := hmac.finish() + if expected != mac: + return "" + var aes := AESContext.new() + aes.start(AESContext.MODE_CBC_DECRYPT, aes_key, iv) + var padded := aes.update(cipher) + aes.finish() + if padded.is_empty(): + return "" + var pad := int(padded[padded.size() - 1]) + if pad < 1 or pad > 16 or pad > padded.size(): + return "" + var raw := padded.slice(0, padded.size() - pad) + return raw.get_string_from_utf8() + + +# --- UI: tab in Clients & Tools ------------------------------------------------- + +## Builds the "Vision Routing" section inside the Clients & Tools Settings +## tab. Called by mcp_dock._build_settings_tab; `refresh_ui()` re-syncs the +## controls from Editor Settings each time the window opens. +func build_section(parent: VBoxContainer) -> void: + var box := VBoxContainer.new() + box.add_theme_constant_override("separation", 8) + parent.add_child(box) + + var header := Label.new() + header.text = "Vision Routing" + header.add_theme_font_size_override("font_size", 18) + box.add_child(header) + + var provider_row := HBoxContainer.new() + var provider_label := Label.new() + provider_label.text = "Provider" + provider_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + provider_row.add_child(provider_label) + _tab_provider = OptionButton.new() + _tab_provider.tooltip_text = "Which vision provider routes the screenshots. The model id is required per provider and is yours to maintain." + var active_provider := _active_provider_id() + for provider_index in PROVIDER_ORDER.size(): + var provider_item: Dictionary = PROVIDERS[PROVIDER_ORDER[provider_index]] + _tab_provider.add_item(str(provider_item.get("label", PROVIDER_ORDER[provider_index])), provider_index) + if PROVIDER_ORDER[provider_index] == active_provider: + _tab_provider.select(provider_index) + _tab_provider.item_selected.connect(_on_provider_changed) + provider_row.add_child(_tab_provider) + box.add_child(provider_row) + + var enable_row := HBoxContainer.new() + var enable_label := Label.new() + enable_label.text = "Enable routing" + enable_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL + enable_row.add_child(enable_label) + _tab_enable = CheckButton.new() + _tab_enable.button_pressed = is_routing_enabled() + _tab_enable.toggled.connect(_on_enable_toggled) + enable_row.add_child(_tab_enable) + box.add_child(enable_row) + + var description := Label.new() + description.text = ( + "When enabled, every single-image screenshot the AI model takes through " + + "the godot-ai screenshot tool is sent to the selected provider's vision model (see " + + "the Provider dropdown) for a text description. The description is " + + "returned to the AI instead of the raw image, so models without image " + + "support (e.g. DeepSeek) can still \"see\" the editor and game. When " + + "the connected model analyzes images itself, switch this off here so " + + "screenshots pass through unchanged." + ) + description.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + description.size_flags_horizontal = Control.SIZE_EXPAND_FILL + box.add_child(description) + + _tab_key_label = Label.new() + box.add_child(_tab_key_label) + + var key_row := HBoxContainer.new() + _tab_key_edit = LineEdit.new() + _tab_key_edit.secret = true + _tab_key_edit.size_flags_horizontal = Control.SIZE_EXPAND_FILL + ## Persist on commit (Enter / focus loss) instead of per keystroke, so + ## pasting a key does not re-encrypt and rewrite Editor Settings dozens + ## of times. + _tab_key_edit.text_submitted.connect(_on_key_committed) + _tab_key_edit.focus_exited.connect(func() -> void: _on_key_committed(_tab_key_edit.text)) + key_row.add_child(_tab_key_edit) + var show_button := CheckButton.new() + show_button.tooltip_text = "Show / hide key" + show_button.toggled.connect(func(show: bool) -> void: _tab_key_edit.secret = not show) + key_row.add_child(show_button) + box.add_child(key_row) + + _tab_key_hint = Label.new() + _tab_key_hint.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _tab_key_hint.add_theme_color_override("font_color", Color(0.55, 0.55, 0.55)) + box.add_child(_tab_key_hint) + + _tab_model_label = Label.new() + box.add_child(_tab_model_label) + + var model_row := HBoxContainer.new() + _tab_model_edit = LineEdit.new() + _tab_model_edit.size_flags_horizontal = Control.SIZE_EXPAND_FILL + ## Persist on commit (Enter / focus loss), same pattern as the key field. + _tab_model_edit.text_submitted.connect(_on_model_committed) + _tab_model_edit.focus_exited.connect(func() -> void: _on_model_committed(_tab_model_edit.text)) + model_row.add_child(_tab_model_edit) + box.add_child(model_row) + + _tab_model_hint = Label.new() + _tab_model_hint.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + _tab_model_hint.add_theme_color_override("font_color", Color(0.55, 0.55, 0.55)) + box.add_child(_tab_model_hint) + + var test_row := HBoxContainer.new() + var test_button := Button.new() + test_button.text = "Test connection" + test_button.pressed.connect(_on_test_connection) + _tab_test_button = test_button + test_row.add_child(test_button) + _tab_status = Label.new() + _tab_status.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _tab_status.add_theme_color_override("font_color", Color(0.55, 0.55, 0.55)) + test_row.add_child(_tab_status) + box.add_child(test_row) + + refresh_ui() + + +## Re-syncs every control from Editor Settings. Called after the section is +## built and again by mcp_dock each time the Clients & Tools window opens, +## so a change made in another editor instance (or a hand-edit of +## editor_settings-4.tres) is reflected. +func refresh_ui() -> void: + _sync_ui_states() + _sync_provider_ui() + _ui_loading = true + if _tab_key_edit != null and is_instance_valid(_tab_key_edit): + _tab_key_edit.text = _decrypted_key(_active_provider_id()) + if _tab_model_edit != null and is_instance_valid(_tab_model_edit): + _tab_model_edit.text = _resolved_model(_active_provider_id()) + _ui_loading = false + + +func _on_key_committed(_new_text: String) -> void: + if _ui_loading: + return + set_api_key(_active_provider_id(), _tab_key_edit.text) + + +func _on_model_committed(_new_text: String) -> void: + if _ui_loading: + return + set_model_id(_active_provider_id(), _tab_model_edit.text) + + +func _on_provider_changed(index: int) -> void: + if index < 0 or index >= PROVIDER_ORDER.size(): + return + var provider_id: String = PROVIDER_ORDER[index] + var es := _settings() + if es != null: + es.set_setting(SETTING_PROVIDER, provider_id) + _ui_loading = true + if _tab_key_edit != null and is_instance_valid(_tab_key_edit): + _tab_key_edit.text = _decrypted_key(provider_id) + if _tab_model_edit != null and is_instance_valid(_tab_model_edit): + _tab_model_edit.text = _resolved_model(provider_id) + _ui_loading = false + _sync_provider_ui() + _log("vision routing: provider changed to %s (%s)" % [provider_id, PROVIDERS[provider_id].get("label", provider_id)]) + + +func _sync_provider_ui() -> void: + var provider_id := _active_provider_id() + var provider: Dictionary = PROVIDERS.get(provider_id, PROVIDERS["groq"]) + if _tab_provider != null and is_instance_valid(_tab_provider): + var provider_index := PROVIDER_ORDER.find(provider_id) + if provider_index != -1 and _tab_provider.selected != provider_index: + _tab_provider.select(provider_index) + if _tab_key_label != null and is_instance_valid(_tab_key_label): + _tab_key_label.text = str(provider.get("key_label", "API key")) + if _tab_key_hint != null and is_instance_valid(_tab_key_hint): + var hint := ( + "Stored encrypted (AES-256, key derived from this machine) in Editor Settings " + + "- not plain text, but local obfuscation only. You can also set the " + + "%s environment variable; it takes priority over this field." + ) % provider.get("env", "") + if OS.get_unique_id().is_empty(): + hint += " This machine reports no unique id, so keys cannot be stored locally - use the %s environment variable." % provider.get("env", "") + _tab_key_hint.text = hint + if _tab_key_edit != null and is_instance_valid(_tab_key_edit): + _tab_key_edit.placeholder_text = str(provider.get("placeholder", "")) + if _tab_model_label != null and is_instance_valid(_tab_model_label): + _tab_model_label.text = "Model id (required) - %s" % provider.get("label", provider_id) + if _tab_model_edit != null and is_instance_valid(_tab_model_edit): + _tab_model_edit.placeholder_text = str(provider.get("model_placeholder", "")) + _tab_model_edit.tooltip_text = "The vision model this provider should ping. Yours to maintain: when a model id retires, replace it here." + if _tab_model_hint != null and is_instance_valid(_tab_model_hint): + _tab_model_hint.text = ( + "Required per provider; empty behaves like an empty key (routing " + + "declines and screenshots pass through). Suggested id (as of " + + "2026-08 - check your provider console, ids retire): %s." + ) % provider.get("model_placeholder", "") + + +func _on_test_connection() -> void: + if _tab_status == null: + return + var provider_id := _active_provider_id() + var provider := _provider_with_model(provider_id) + var env_name := str(PROVIDERS.get(provider_id, PROVIDERS["groq"]).get("env", "")) + if str(provider.get("model", "")).is_empty(): + _tab_status.text = "No model id set for %s - add one below." % provider.get("label", provider_id) + return + var api_key := _resolved_api_key(provider_id) + if api_key.is_empty(): + _tab_status.text = "No key set - add one below or set %s." % env_name + return + var running: Thread = _threads.get("_test") + if running != null and running.is_started() and running.is_alive(): + return + var previous_status := _tab_status.text + _tab_status.text = "Testing..." + if _tab_test_button != null and is_instance_valid(_tab_test_button): + _tab_test_button.disabled = true + var key_source := "stored key" + if not OS.get_environment(env_name).is_empty(): + key_source = "via %s" % env_name + var thread := Thread.new() + _threads["_test"] = thread + var start_err := thread.start(_ping_worker.bind(provider, api_key, _tab_status, key_source)) + if start_err != OK: + ## A failed thread start must not leave the button disabled and the + ## status stuck on "Testing..." forever. + _threads.erase("_test") + _tab_status.text = previous_status + if _tab_test_button != null and is_instance_valid(_tab_test_button): + _tab_test_button.disabled = false + _log("vision routing: could not start ping thread: %s" % error_string(start_err)) + + +func _on_enable_toggled(enabled: bool) -> void: + var es := _settings() + if es != null: + es.set_setting(SETTING_ENABLED, enabled) + _sync_ui_states() + + +func _sync_ui_states() -> void: + var enabled := is_routing_enabled() + if _tab_enable != null and is_instance_valid(_tab_enable) and _tab_enable.button_pressed != enabled: + _tab_enable.set_pressed_no_signal(enabled) + + +# --- logging -------------------------------------------------------------------- + +func _log(message: String) -> void: + if log_buffer != null and is_instance_valid(log_buffer) and log_buffer.has_method("log"): + log_buffer.log(message, false) diff --git a/addons/godot_ai/vision_routing.gd.uid b/addons/godot_ai/vision_routing.gd.uid new file mode 100644 index 0000000..c4c5bc2 --- /dev/null +++ b/addons/godot_ai/vision_routing.gd.uid @@ -0,0 +1 @@ +uid://dp444q4ocpx45 diff --git a/addons/godotx_toast/assets/fonts/LICENSE.txt b/addons/godotx_toast/assets/fonts/LICENSE.txt new file mode 100644 index 0000000..e96f4bc --- /dev/null +++ b/addons/godotx_toast/assets/fonts/LICENSE.txt @@ -0,0 +1,93 @@ +Copyright 2011 The Roboto Project Authors (https://github.com/googlefonts/roboto-classic) Roboto-Italic[wdth,wght].ttf: Copyright 2011 The Roboto Project Authors (https://github.com/googlefonts/roboto-classic) + +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/addons/godotx_toast/assets/fonts/Roboto-Regular.ttf b/addons/godotx_toast/assets/fonts/Roboto-Regular.ttf new file mode 100644 index 0000000..e26016b Binary files /dev/null and b/addons/godotx_toast/assets/fonts/Roboto-Regular.ttf differ diff --git a/addons/godotx_toast/assets/fonts/Roboto-Regular.ttf.import b/addons/godotx_toast/assets/fonts/Roboto-Regular.ttf.import new file mode 100644 index 0000000..a63a836 --- /dev/null +++ b/addons/godotx_toast/assets/fonts/Roboto-Regular.ttf.import @@ -0,0 +1,36 @@ +[remap] + +importer="font_data_dynamic" +type="FontFile" +uid="uid://bij3dcdvuwr64" +path="res://.godot/imported/Roboto-Regular.ttf-f1b5c17e626cd5fe0a2497606e0a64df.fontdata" + +[deps] + +source_file="res://addons/godotx_toast/assets/fonts/Roboto-Regular.ttf" +dest_files=["res://.godot/imported/Roboto-Regular.ttf-f1b5c17e626cd5fe0a2497606e0a64df.fontdata"] + +[params] + +Rendering=null +antialiasing=1 +generate_mipmaps=false +disable_embedded_bitmaps=true +multichannel_signed_distance_field=false +msdf_pixel_range=8 +msdf_size=48 +allow_system_fallback=true +force_autohinter=false +modulate_color_glyphs=false +hinting=3 +subpixel_positioning=4 +keep_rounding_remainders=true +oversampling=0.0 +Fallbacks=null +fallbacks=[] +Compress=null +compress=true +preload=[] +language_support={} +script_support={} +opentype_features={} diff --git a/addons/godotx_toast/plugin.cfg b/addons/godotx_toast/plugin.cfg new file mode 100644 index 0000000..1881198 --- /dev/null +++ b/addons/godotx_toast/plugin.cfg @@ -0,0 +1,6 @@ +[plugin] +name="GodotX Toast" +description="Professional toast notification system with style-driven architecture" +author="Paulo Coutinho" +version="2.0.0" +script="plugin.gd" diff --git a/addons/godotx_toast/plugin.gd b/addons/godotx_toast/plugin.gd new file mode 100644 index 0000000..4df0e64 --- /dev/null +++ b/addons/godotx_toast/plugin.gd @@ -0,0 +1,11 @@ +@tool +extends EditorPlugin + +const AUTOLOAD_NAME = "GodotxToast" +const AUTOLOAD_PATH = "res://addons/godotx_toast/runtime/godotx_toast.gd" + +func _enter_tree() -> void: + add_autoload_singleton(AUTOLOAD_NAME, AUTOLOAD_PATH) + +func _exit_tree() -> void: + remove_autoload_singleton(AUTOLOAD_NAME) diff --git a/addons/godotx_toast/plugin.gd.uid b/addons/godotx_toast/plugin.gd.uid new file mode 100644 index 0000000..e6e1c5e --- /dev/null +++ b/addons/godotx_toast/plugin.gd.uid @@ -0,0 +1 @@ +uid://chqrgi1ovp4fl diff --git a/addons/godotx_toast/runtime/godotx_toast.gd b/addons/godotx_toast/runtime/godotx_toast.gd new file mode 100644 index 0000000..696905f --- /dev/null +++ b/addons/godotx_toast/runtime/godotx_toast.gd @@ -0,0 +1,213 @@ +extends Node + +signal toast_shown(id: String) +signal toast_dismissed(id: String, reason: int) +signal toast_clicked(id: String) +signal loading_progress_updated(id: String, progress: float) +signal loading_completed(id: String, success: bool) + +var proportion: float = 30.0: + set(value): + proportion = clamp(value, 1.0, 100.0) + if _manager: + _manager.set_proportion(proportion) + +var default_origin: GodotxToastEnums.ToastOrigin = GodotxToastEnums.ToastOrigin.BOTTOM: + set(value): + default_origin = value + if _manager: + _manager.default_origin = value + +var default_animation: GodotxToastEnums.ToastAnimation = GodotxToastEnums.ToastAnimation.SLIDE: + set(value): + default_animation = value + if _manager: + _manager.default_animation = value + +var default_time: int = GodotxToastEnums.ToastTime.MEDIUM: + set(value): + default_time = value + if _manager: + _manager.default_time = value + +var _manager: GodotxToastManager = null +var _initialized: bool = false + +func _ready(): + _initialize.call_deferred() + +func _initialize(): + if _initialized: + return + + _manager = GodotxToastManager.new() + _manager.name = "GodotxToastManager" + add_child(_manager) + + _manager.proportion = proportion + _manager.default_origin = default_origin + _manager.default_animation = default_animation + _manager.default_time = default_time + + _manager.toast_shown.connect(func(id): toast_shown.emit(id)) + _manager.toast_dismissed.connect(func(id, reason): toast_dismissed.emit(id, reason)) + _manager.toast_clicked.connect(func(id): toast_clicked.emit(id)) + _manager.loading_progress_updated.connect(func(id, progress): loading_progress_updated.emit(id, progress)) + _manager.loading_completed.connect(func(id, success): loading_completed.emit(id, success)) + + _initialized = true + +func show( + message: String, + style: Variant = null, + time: Variant = null, + origin: int = -1, + animation: int = -1, + options: Dictionary = {} +) -> String: + + if not _initialized: + _initialize() + + if message.is_empty(): + push_error("GodotX Toast: Message cannot be empty") + return "" + + var resolved_style: GodotxToastStyle + if style == null: + resolved_style = GodotxToastStyles.get_style(GodotxToastStyles.INFO) + elif style is String: + resolved_style = GodotxToastStyles.get_style(style) + elif style is GodotxToastStyle: + resolved_style = style + else: + push_error("GodotX Toast: Invalid style type") + return "" + + if resolved_style == null: + push_error("GodotX Toast: Could not resolve style") + return "" + + var resolved_time: float + if time is int: + resolved_time = float(time) + elif time is float: + resolved_time = time + elif time == null: + resolved_time = float(default_time) + else: + resolved_time = float(default_time) + + var resolved_origin = origin if origin >= 0 else resolved_style.default_origin + var resolved_animation = animation if animation >= 0 else resolved_style.default_animation + + return _manager.show_toast( + message, + resolved_style, + resolved_time, + resolved_origin, + resolved_animation, + options + ) + +func show_loading( + message: String, + style: Variant = null, + origin: int = -1, + animation: int = -1, + options: Dictionary = {} +) -> String: + + if not _initialized: + _initialize() + + if message.is_empty(): + push_error("GodotX Toast: Loading message cannot be empty") + return "" + + var resolved_style: GodotxToastStyle + if style == null: + resolved_style = GodotxToastStyles.get_style(GodotxToastStyles.LOADING) + elif style is String: + resolved_style = GodotxToastStyles.get_style(style) + elif style is GodotxToastStyle: + resolved_style = style + else: + push_error("GodotX Toast: Invalid style type for loading") + return "" + + if resolved_style == null: + push_error("GodotX Toast: Could not resolve loading style") + return "" + + var resolved_origin = origin if origin >= 0 else resolved_style.default_origin + var resolved_animation = animation if animation >= 0 else resolved_style.default_animation + + return _manager.show_loading( + message, + resolved_style, + resolved_origin, + resolved_animation, + options + ) + +func update_loading(toast_id: String, progress: float, new_message: String = "") -> bool: + if not _initialized or _manager == null: + return false + return _manager.update_loading(toast_id, progress, new_message) + +func complete_loading(toast_id: String, success: bool = true, final_message: String = "") -> bool: + if not _initialized or _manager == null: + return false + return _manager.complete_loading(toast_id, success, final_message) + +func loading(message: String, style: Variant = null) -> String: + return show_loading(message, style) + +func dismiss(toast_id: String) -> bool: + if not _initialized or _manager == null: + return false + return _manager.dismiss_toast(toast_id) + +func clear_all(): + if not _initialized or _manager == null: + return + _manager.clear_all() + +func clear_by_origin(origin: GodotxToastEnums.ToastOrigin): + if not _initialized or _manager == null: + return + _manager.dismiss_by_origin(origin) + +func quick_show(message: String, style_id: String = "info", time_seconds: float = 4.0) -> String: + return show(message, style_id, time_seconds) + +func success(message: String, time: Variant = null) -> String: + return show(message, GodotxToastStyles.SUCCESS, time if time != null else default_time) + +func error(message: String, time: Variant = null) -> String: + return show(message, GodotxToastStyles.ERROR, time if time != null else default_time) + +func warning(message: String, time: Variant = null) -> String: + return show(message, GodotxToastStyles.WARNING, time if time != null else default_time) + +func info(message: String, time: Variant = null) -> String: + return show(message, GodotxToastStyles.INFO, time if time != null else default_time) + +func configure( + p_proportion: float = -1, + p_default_origin: int = -1, + p_default_animation: int = -1, + p_default_time: int = -1 +): + if p_proportion > 0: + proportion = p_proportion + if p_default_origin >= 0: + default_origin = p_default_origin + if p_default_animation >= 0: + default_animation = p_default_animation + if p_default_time > 0: + default_time = p_default_time + + if _manager: + _manager.update_config(proportion, default_origin, default_animation, default_time) diff --git a/addons/godotx_toast/runtime/godotx_toast.gd.uid b/addons/godotx_toast/runtime/godotx_toast.gd.uid new file mode 100644 index 0000000..318fe8d --- /dev/null +++ b/addons/godotx_toast/runtime/godotx_toast.gd.uid @@ -0,0 +1 @@ +uid://bgvixrj72u7rv diff --git a/addons/godotx_toast/runtime/toast_container.gd b/addons/godotx_toast/runtime/toast_container.gd new file mode 100644 index 0000000..2f4dc4b --- /dev/null +++ b/addons/godotx_toast/runtime/toast_container.gd @@ -0,0 +1,241 @@ +class_name GodotxToastContainer +extends Control + +var origin: GodotxToastEnums.ToastOrigin +var _toasts: Array[GodotxToastView] = [] +var _queued_toasts: Array[Dictionary] = [] +var _spacing: int = 8 + +func _init(p_origin: GodotxToastEnums.ToastOrigin): + origin = p_origin + mouse_filter = MOUSE_FILTER_IGNORE + z_index = 200 + anchors_preset = Control.PRESET_FULL_RECT + +func add_toast(toast_view: GodotxToastView, strategy: int, max_visible: int) -> bool: + if _toasts.size() >= max_visible: + match strategy: + GodotxToastEnums.StackStrategy.DROP_NEW: + toast_view.queue_free() + return false + GodotxToastEnums.StackStrategy.DROP_OLDEST: + if _toasts.size() > 0: + _toasts[0].dismiss(GodotxToastEnums.ToastDismissReason.API) + _toasts.append(toast_view) + GodotxToastEnums.StackStrategy.REPLACE_OLDEST: + if _toasts.size() > 0: + _toasts[0].dismiss(GodotxToastEnums.ToastDismissReason.API) + _toasts.append(toast_view) + GodotxToastEnums.StackStrategy.QUEUE: + _queued_toasts.append({"view": toast_view, "strategy": strategy, "max": max_visible}) + return true + else: + _toasts.append(toast_view) + + _add_toast_node(toast_view) + return true + +func _add_toast_node(toast_view: GodotxToastView): + toast_view.position = Vector2(-9999.0, -9999.0) + add_child(toast_view) + toast_view.dismissed.connect(_on_toast_dismissed) + if toast_view.has_signal("swiped"): + toast_view.swiped.connect(_on_toast_swiped) + # Use Godot's sorting mechanism - wait for layout + call_deferred("_position_toast_after_layout", toast_view) + +func _position_toast_after_layout(toast_view: GodotxToastView): + if not is_instance_valid(toast_view): + return + # Position all visible toasts + _position_all_toasts() + toast_view.animate_in(_get_toast_position(toast_view)) + +func _get_toast_position(toast_view: GodotxToastView) -> Vector2: + var visible_toasts = _get_visible_toasts() + var idx = visible_toasts.find(toast_view) + if idx < 0: + return Vector2.ZERO + var positions = _calculate_positions() + if idx < positions.size(): + return positions[idx] + return Vector2.ZERO + +func _position_all_toasts(): + var positions = _calculate_positions() + var visible_toasts = _get_visible_toasts() + for i in range(visible_toasts.size()): + if i < positions.size(): + visible_toasts[i].position = positions[i] + +func _on_toast_dismissed(toast_id: String, _reason: int): + for i in range(_toasts.size()): + if _toasts[i].toast_id == toast_id: + _toasts.remove_at(i) + break + call_deferred("_reposition_toasts") + _process_queue() + +func _on_toast_swiped(toast_id: String, _direction: Vector2): + dismiss_toast(toast_id, GodotxToastEnums.ToastDismissReason.SWIPE) + +func _process_queue(): + if _queued_toasts.is_empty(): + return + var next = _queued_toasts.pop_front() + add_toast(next.view, next.strategy, next.max) + +func _reposition_toasts(): + var visible_toasts = _get_visible_toasts() + if visible_toasts.is_empty(): + return + var positions = _calculate_positions() + for i in range(visible_toasts.size()): + if i < positions.size(): + var tw = create_tween() + tw.set_ease(Tween.EASE_OUT) + tw.set_trans(Tween.TRANS_QUAD) + tw.tween_property(visible_toasts[i], "position", positions[i], 0.2) + +func _calculate_positions() -> Array: + # Get only visible (non-dismissing) toasts + var visible_toasts: Array[GodotxToastView] = [] + for toast in _toasts: + if not toast._is_dismissing: + visible_toasts.append(toast) + + if visible_toasts.is_empty(): + return [] + + var viewport_size = get_viewport().get_visible_rect().size + var safe_area = _get_safe_area_margins() + var direction = _get_stack_direction() + var positions = [] + + var anchor_y = _get_anchor_y(viewport_size, safe_area, visible_toasts) + + var current_y = anchor_y + for toast in visible_toasts: + # Calculate X position individually for each toast based on its width + var toast_w = toast.size.x + var pos_x = _calculate_x_for_toast(viewport_size, safe_area, toast_w) + var pos = Vector2(pos_x, current_y) + positions.append(pos) + var toast_h = toast.size.y + current_y += direction * (toast_h + _spacing) + + return positions + +func _calculate_x_for_toast(viewport_size: Vector2, safe_area: Dictionary, toast_width: float) -> float: + match origin: + GodotxToastEnums.ToastOrigin.CENTER, GodotxToastEnums.ToastOrigin.TOP, GodotxToastEnums.ToastOrigin.BOTTOM: + return (viewport_size.x - toast_width) / 2.0 + GodotxToastEnums.ToastOrigin.LEFT, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.BOTTOM_LEFT: + return safe_area.left + 16.0 + GodotxToastEnums.ToastOrigin.RIGHT, GodotxToastEnums.ToastOrigin.TOP_RIGHT, GodotxToastEnums.ToastOrigin.BOTTOM_RIGHT: + return viewport_size.x - safe_area.right - 16.0 - toast_width + return 0.0 + +func _get_visible_toasts() -> Array[GodotxToastView]: + var visible: Array[GodotxToastView] = [] + for toast in _toasts: + if not toast._is_dismissing: + visible.append(toast) + return visible + +func _get_anchor_x(viewport_size: Vector2, safe_area: Dictionary, visible_toasts: Array[GodotxToastView] = []) -> float: + if visible_toasts.is_empty(): + visible_toasts = _get_visible_toasts() + if visible_toasts.is_empty(): + return 0.0 + var toast_width = visible_toasts[0].size.x + + match origin: + GodotxToastEnums.ToastOrigin.CENTER, GodotxToastEnums.ToastOrigin.TOP, GodotxToastEnums.ToastOrigin.BOTTOM: + return (viewport_size.x - toast_width) / 2.0 + GodotxToastEnums.ToastOrigin.LEFT, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.BOTTOM_LEFT: + return safe_area.left + 16.0 + GodotxToastEnums.ToastOrigin.RIGHT, GodotxToastEnums.ToastOrigin.TOP_RIGHT, GodotxToastEnums.ToastOrigin.BOTTOM_RIGHT: + return viewport_size.x - safe_area.right - 16.0 - toast_width + return 0.0 + +func _get_anchor_y(viewport_size: Vector2, safe_area: Dictionary, visible_toasts: Array[GodotxToastView] = []) -> float: + if visible_toasts.is_empty(): + visible_toasts = _get_visible_toasts() + + var total_height = _calculate_total_height() + + match origin: + GodotxToastEnums.ToastOrigin.TOP, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.TOP_RIGHT: + return safe_area.top + 16.0 + GodotxToastEnums.ToastOrigin.BOTTOM, GodotxToastEnums.ToastOrigin.BOTTOM_LEFT, GodotxToastEnums.ToastOrigin.BOTTOM_RIGHT: + if visible_toasts.is_empty(): + return viewport_size.y - safe_area.bottom - 16.0 + var first_height = visible_toasts[0].size.y + return viewport_size.y - safe_area.bottom - 16.0 - first_height + GodotxToastEnums.ToastOrigin.CENTER: + return (viewport_size.y - total_height) / 2.0 + GodotxToastEnums.ToastOrigin.LEFT, GodotxToastEnums.ToastOrigin.RIGHT: + return (viewport_size.y - total_height) / 2.0 + return 16.0 + +func _calculate_total_height() -> float: + var total = 0.0 + var visible_count = 0 + for toast in _toasts: + if not toast._is_dismissing: + total += toast.size.y + visible_count += 1 + if visible_count > 0: + total += (visible_count - 1) * _spacing + return total + +func _get_stack_direction() -> float: + match origin: + GodotxToastEnums.ToastOrigin.TOP, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.TOP_RIGHT: + return 1.0 + GodotxToastEnums.ToastOrigin.BOTTOM, GodotxToastEnums.ToastOrigin.BOTTOM_LEFT, GodotxToastEnums.ToastOrigin.BOTTOM_RIGHT: + return -1.0 + _: + return 1.0 + +func _get_safe_area_margins() -> Dictionary: + if _toasts.is_empty(): + return {"top": 0, "bottom": 0, "left": 0, "right": 0} + var ui_scale = get_global_transform().get_scale().x + return _toasts[0].style.get_effective_safe_area_margins(ui_scale) + +func get_toast_count() -> int: + return _toasts.size() + +func get_toast_by_id(id: String) -> GodotxToastView: + for toast in _toasts: + if toast.toast_id == id: + return toast + return null + +func dismiss_all(reason: int = GodotxToastEnums.ToastDismissReason.API): + var toasts_copy = _toasts.duplicate() + _toasts.clear() + for toast in toasts_copy: + if is_instance_valid(toast): + toast.dismiss(reason) + for queued in _queued_toasts: + if is_instance_valid(queued.view): + queued.view.queue_free() + _queued_toasts.clear() + +func dismiss_toast(id: String, reason: int = GodotxToastEnums.ToastDismissReason.API) -> bool: + for toast in _toasts: + if toast.toast_id == id: + toast.dismiss(reason) + return true + return false + +func update_max_widths(max_width: float): + for toast in _toasts: + toast.set_max_width(max_width) + call_deferred("_reposition_toasts") + +func handle_viewport_resized(): + call_deferred("_reposition_toasts") diff --git a/addons/godotx_toast/runtime/toast_container.gd.uid b/addons/godotx_toast/runtime/toast_container.gd.uid new file mode 100644 index 0000000..1151ea8 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_container.gd.uid @@ -0,0 +1 @@ +uid://5tufy0jhkvhf diff --git a/addons/godotx_toast/runtime/toast_deck_container.gd b/addons/godotx_toast/runtime/toast_deck_container.gd new file mode 100644 index 0000000..50de794 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_deck_container.gd @@ -0,0 +1,292 @@ +## GodotxToastDeckContainer — Sonner-style stacked deck. +## +## Architecture: +## _visible_cards[0] = active front card (full interaction, normal scale) +## _visible_cards[1..MAX_PREVIEWS] = preview cards (no interaction, scaled/offset) +## _deck_queue = cards waiting to enter the scene +## +## When the front card is dismissed, preview[1] animates to the active position, +## preview[2] moves to preview[1] slot, and a new card from the queue fills the +## last preview slot — everything stays visible and transitions smoothly. +class_name GodotxToastDeckContainer +extends GodotxToastContainer + +const MAX_PREVIEWS: int = 2 + +## Cards currently in the scene (indices 0 = front active, 1+ = previews). +var _visible_cards: Array[GodotxToastView] = [] +## Cards waiting — not yet added to the scene. +var _deck_queue: Array[GodotxToastView] = [] + +## Deduplication flag: ensures _do_layout() runs at most once per frame. +var _layout_pending: bool = false + +func _init(p_origin: GodotxToastEnums.ToastOrigin): + super(p_origin) + +# --------------------------------------------------------------------------- +# add_toast — override for DECK strategy +# --------------------------------------------------------------------------- + +func add_toast(toast_view: GodotxToastView, strategy: int, _max_visible: int) -> bool: + if strategy != GodotxToastEnums.StackStrategy.DECK: + return super.add_toast(toast_view, strategy, _max_visible) + + if _visible_cards.size() < 1 + MAX_PREVIEWS: + _push_to_visible(toast_view) + else: + _deck_queue.push_back(toast_view) + + return true + +# --------------------------------------------------------------------------- +# Adding cards to the visible stack +# --------------------------------------------------------------------------- + +func _push_to_visible(toast_view: GodotxToastView): + var slot = _visible_cards.size() + _visible_cards.append(toast_view) + + toast_view.position = Vector2(-9999.0, -9999.0) # off-screen until positioned + toast_view.z_index = 20 - slot + + if slot == 0: + # Active card — normal behavior, full interaction. + toast_view.dismissed.connect(_on_active_dismissed) + else: + # Preview card — disable timer and input before _ready() fires. + _enter_preview(toast_view) + + add_child(toast_view) + _schedule_layout() + +func _enter_preview(toast_view: GodotxToastView): + ## Called BEFORE add_child so _ready() sees display_time=-1 and skips the timer. + toast_view.set_meta("_deck_original_display_time", toast_view.display_time) + toast_view.display_time = -1 # prevents _setup_timer() from running in _ready() + toast_view.mouse_filter = Control.MOUSE_FILTER_IGNORE + +func _exit_preview(toast_view: GodotxToastView): + ## Promotes a preview card to the active front slot. + var orig_time: float = toast_view.get_meta("_deck_original_display_time", -1.0) + toast_view.display_time = orig_time + toast_view.mouse_filter = Control.MOUSE_FILTER_STOP + # Reset visual transform (was scaled/offset as a preview). + toast_view.scale = Vector2.ONE + toast_view.pivot_offset = Vector2.ZERO + # Start the auto-dismiss timer now that the card is in front. + if orig_time > 0: + toast_view._setup_timer() + +# --------------------------------------------------------------------------- +# Layout — position all visible cards in their correct slots +# --------------------------------------------------------------------------- + +func _schedule_layout(): + if _layout_pending: + return + _layout_pending = true + call_deferred("_do_layout") + +func _do_layout(): + _layout_pending = false + if _visible_cards.is_empty(): + return + + var front = _visible_cards[0] + if not is_instance_valid(front): + return + + var active_pos = _compute_active_position(front) + var card_w = front.size.x + + for i in range(_visible_cards.size()): + var card = _visible_cards[i] + if not is_instance_valid(card): + continue + card.z_index = 20 - i + if i == 0: + if card.position.x < -100: + card.animate_in(active_pos) + else: + var card_h = card.size.y + var sf = _scale_for_slot(i, card.style) + var pivot = _pivot_for_slot(card_w, card_h) + var pos = _pos_for_slot(active_pos, card_h, i, sf, card.style) + card.pivot_offset = pivot + card.scale = Vector2(sf, sf) + card.position = pos + +# --------------------------------------------------------------------------- +# Transition after the front card is dismissed +# --------------------------------------------------------------------------- + +func _on_active_dismissed(_toast_id: String, _reason: int): + if _visible_cards.is_empty(): + return + _visible_cards.remove_at(0) # front card frees itself via queue_free() + + # Fill empty preview slots from the queue. + while _visible_cards.size() < 1 + MAX_PREVIEWS and not _deck_queue.is_empty(): + var queued = _deck_queue.pop_front() + queued.position = Vector2(-9999.0, -9999.0) + # Enter preview BEFORE add_child to suppress the timer in _ready(). + _enter_preview(queued) + _visible_cards.append(queued) + queued.z_index = 20 - (_visible_cards.size() - 1) + add_child(queued) + + if _visible_cards.is_empty(): + return + + # Promote the new front card: restore interaction + timer. + var new_front = _visible_cards[0] + if is_instance_valid(new_front): + _exit_preview(new_front) + new_front.z_index = 20 + new_front.dismissed.connect(_on_active_dismissed) + + # Animate all visible cards to their updated slot positions. + call_deferred("_animate_transition") + +func _animate_transition(): + if _visible_cards.is_empty(): + return + + var front = _visible_cards[0] + if not is_instance_valid(front): + return + + var active_pos = _compute_active_position(front) + var card_w = front.size.x + + var dur = 0.28 + + for i in range(_visible_cards.size()): + var card = _visible_cards[i] + if not is_instance_valid(card): + continue + card.z_index = 20 - i + + if i == 0: + var tw = card.create_tween() + tw.set_ease(Tween.EASE_OUT) + tw.set_trans(Tween.TRANS_CUBIC) + tw.set_parallel(true) + tw.tween_property(card, "position", active_pos, dur) + tw.tween_property(card, "scale", Vector2.ONE, dur) + tw.tween_property(card, "pivot_offset", Vector2.ZERO, dur) + else: + var card_h = card.size.y + var sf = _scale_for_slot(i, card.style) + var target_pos = _pos_for_slot(active_pos, card_h, i, sf, card.style) + var target_pivot = _pivot_for_slot(card_w, card_h) + if card.position.x < -100: + # brand-new card from queue: place directly, no tween needed + card.pivot_offset = target_pivot + card.scale = Vector2(sf, sf) + card.position = target_pos + else: + var tw = card.create_tween() + tw.set_ease(Tween.EASE_OUT) + tw.set_trans(Tween.TRANS_CUBIC) + tw.set_parallel(true) + tw.tween_property(card, "position", target_pos, dur) + tw.tween_property(card, "scale", Vector2(sf, sf), dur) + tw.tween_property(card, "pivot_offset", target_pivot, dur) + +# --------------------------------------------------------------------------- +# Position / scale / pivot helpers +# --------------------------------------------------------------------------- + +func _scale_for_slot(slot: int, style: GodotxToastStyle) -> float: + return clamp(1.0 - slot * style.deck_stack_scale_step, 0.5, 1.0) + +## Returns the pivot that keeps the near edge of each preview aligned with +## the near edge of the active card as scale shrinks toward the background. +## BOTTOM/CENTER/LEFT/RIGHT → pivot at bottom-center (w/2, h): shrinks upward. +## TOP → pivot at top-center (w/2, 0): shrinks downward. +func _pivot_for_slot(w: float, h: float) -> Vector2: + match origin: + GodotxToastEnums.ToastOrigin.TOP, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.TOP_RIGHT: + return Vector2(w / 2.0, 0.0) + _: + return Vector2(w / 2.0, h) + +## Previews fan away from the active card toward the background: +## BOTTOM: previews move up → pos.y decreases by offset_step per slot. +## TOP: previews move down → pos.y increases by offset_step per slot. +func _pos_for_slot(active_pos: Vector2, _h: float, slot: int, + _scale: float, style: GodotxToastStyle) -> Vector2: + var offset = style.get_effective_deck_stack_offset_step(1.0) * slot + var pos = active_pos + match origin: + GodotxToastEnums.ToastOrigin.TOP, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.TOP_RIGHT: + pos.y = active_pos.y + offset + _: + pos.y = active_pos.y - offset + return pos + +# --------------------------------------------------------------------------- +# Active-card position (from deck origin settings) +# --------------------------------------------------------------------------- + +func _compute_active_position(toast_view: GodotxToastView) -> Vector2: + var vp = get_viewport().get_visible_rect().size + var ui = toast_view._ui_scale + var sa = toast_view.style.get_effective_safe_area_margins(ui) + var w = toast_view.size.x if toast_view.size.x > 1 else toast_view.custom_minimum_size.x + var h = toast_view.size.y if toast_view.size.y > 1 else toast_view.custom_minimum_size.y + var pad = 16.0 + + match origin: + GodotxToastEnums.ToastOrigin.BOTTOM: + return Vector2((vp.x - w) / 2.0, vp.y - sa.bottom - pad - h) + GodotxToastEnums.ToastOrigin.BOTTOM_LEFT: + return Vector2(sa.left + pad, vp.y - sa.bottom - pad - h) + GodotxToastEnums.ToastOrigin.BOTTOM_RIGHT: + return Vector2(vp.x - sa.right - pad - w, vp.y - sa.bottom - pad - h) + GodotxToastEnums.ToastOrigin.TOP: + return Vector2((vp.x - w) / 2.0, sa.top + pad) + GodotxToastEnums.ToastOrigin.TOP_LEFT: + return Vector2(sa.left + pad, sa.top + pad) + GodotxToastEnums.ToastOrigin.TOP_RIGHT: + return Vector2(vp.x - sa.right - pad - w, sa.top + pad) + GodotxToastEnums.ToastOrigin.LEFT: + return Vector2(sa.left + pad, (vp.y - h) / 2.0) + GodotxToastEnums.ToastOrigin.RIGHT: + return Vector2(vp.x - sa.right - pad - w, (vp.y - h) / 2.0) + _: # CENTER + return Vector2((vp.x - w) / 2.0, (vp.y - h) / 2.0) + +# --------------------------------------------------------------------------- +# Overrides +# --------------------------------------------------------------------------- + +func dismiss_all(reason: int = GodotxToastEnums.ToastDismissReason.API): + for card in _visible_cards: + if is_instance_valid(card): + card.queue_free() + _visible_cards.clear() + for card in _deck_queue: + if is_instance_valid(card): + card.queue_free() + _deck_queue.clear() + +func dismiss_toast(id: String, reason: int = GodotxToastEnums.ToastDismissReason.API) -> bool: + for i in range(_visible_cards.size()): + if is_instance_valid(_visible_cards[i]) and _visible_cards[i].toast_id == id: + _visible_cards[i].dismiss(reason) + return true + for i in range(_deck_queue.size()): + if is_instance_valid(_deck_queue[i]) and _deck_queue[i].toast_id == id: + _deck_queue[i].queue_free() + _deck_queue.remove_at(i) + return true + return false + +func get_queued_count() -> int: + return _deck_queue.size() + +func handle_viewport_resized(): + _schedule_layout() diff --git a/addons/godotx_toast/runtime/toast_deck_container.gd.uid b/addons/godotx_toast/runtime/toast_deck_container.gd.uid new file mode 100644 index 0000000..9413eb4 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_deck_container.gd.uid @@ -0,0 +1 @@ +uid://4q18p16vys5f diff --git a/addons/godotx_toast/runtime/toast_enums.gd b/addons/godotx_toast/runtime/toast_enums.gd new file mode 100644 index 0000000..a9d80dd --- /dev/null +++ b/addons/godotx_toast/runtime/toast_enums.gd @@ -0,0 +1,62 @@ +class_name GodotxToastEnums + +enum ToastOrigin { + CENTER, + LEFT, + RIGHT, + TOP, + BOTTOM, + TOP_LEFT, + TOP_RIGHT, + BOTTOM_LEFT, + BOTTOM_RIGHT +} + +enum ToastAnimation { + SLIDE, + FADE, + NONE +} + +enum ToastTime { + SHORT = 2, + MEDIUM = 4, + LONG = 8 +} + +enum ToastDismissReason { + TIMEOUT, + CLICK, + CLOSE_BUTTON, + API, + SWIPE +} + +enum StackStrategy { + DROP_NEW, + DROP_OLDEST, + REPLACE_OLDEST, + QUEUE, + DECK +} + +enum BackgroundType { + NONE, + COLOR, + TEXTURE, + SCENE +} + +enum SpinnerType { + NONE, + DEFAULT, + TEXTURE, + SCENE +} + +enum SwipeDirection { + NONE, + HORIZONTAL, + VERTICAL, + BOTH +} diff --git a/addons/godotx_toast/runtime/toast_enums.gd.uid b/addons/godotx_toast/runtime/toast_enums.gd.uid new file mode 100644 index 0000000..53f39b9 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_enums.gd.uid @@ -0,0 +1 @@ +uid://b480t4f1e3li0 diff --git a/addons/godotx_toast/runtime/toast_loading_view.gd b/addons/godotx_toast/runtime/toast_loading_view.gd new file mode 100644 index 0000000..76882e9 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_loading_view.gd @@ -0,0 +1,203 @@ +class_name GodotxToastLoadingView +extends GodotxToastView + +signal progress_updated(toast_id: String, progress: float) + +var progress: float = 0.0: + set(value): + progress = clamp(value, 0.0, 100.0) + _on_progress_changed() + +var _spinner: Control = null +var _progress_bar: ProgressBar = null + +func _init(): + super._init() + display_time = -1 + +func _ready(): + # super._ready() builds the layout (icon_container, text_label, etc.) + super._ready() + # Now that layout exists, build spinner and progress bar on top. + _setup_spinner() + _setup_progress_bar() + # Remove the timer that super creates (loading toasts don't auto-dismiss). + _remove_auto_timer() + +func _remove_auto_timer(): + if _timer: + _timer.stop() + _timer.queue_free() + _timer = null + +func _setup_spinner(): + if not style: + return + + match style.spinner_type: + GodotxToastEnums.SpinnerType.NONE: + return + GodotxToastEnums.SpinnerType.DEFAULT: + _spinner = _create_default_spinner() + GodotxToastEnums.SpinnerType.TEXTURE: + if style.spinner_texture: + _spinner = _create_texture_spinner() + else: + push_error("GodotxToastLoadingView: spinner_type is TEXTURE but spinner_texture is null") + return + GodotxToastEnums.SpinnerType.SCENE: + if style.spinner_scene: + _spinner = _create_scene_spinner() + else: + push_error("GodotxToastLoadingView: spinner_type is SCENE but spinner_scene is null") + return + + if _spinner and _icon_container: + _icon_container.custom_minimum_size = style.get_effective_spinner_size(_ui_scale) + # Clear any existing icon content. + for child in _icon_container.get_children(): + child.queue_free() + _icon_container.add_child(_spinner) + elif _spinner == null: + push_error("GodotxToastLoadingView: failed to create spinner") + +func _create_default_spinner() -> Control: + var container = CenterContainer.new() + container.mouse_filter = Control.MOUSE_FILTER_IGNORE + container.custom_minimum_size = style.get_effective_spinner_size(_ui_scale) + + var texture_rect = TextureRect.new() + texture_rect.name = "SpinnerTexture" + texture_rect.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED + var spinner_size = style.get_effective_spinner_size(_ui_scale) + texture_rect.custom_minimum_size = spinner_size + texture_rect.pivot_offset = spinner_size / 2.0 + texture_rect.modulate = style.spinner_tint + + if style.spinner_texture: + texture_rect.texture = style.spinner_texture + else: + texture_rect.texture = _create_default_spinner_texture(spinner_size) + + container.add_child(texture_rect) + + # Use a simple rotation tween loop instead of AnimationPlayer to avoid + # AnimationLibrary setup issues in Godot 4.3+. + var rotate_tween = create_tween() + rotate_tween.set_loops() + rotate_tween.tween_method( + func(angle: float): texture_rect.rotation = angle, + 0.0, TAU, + 1.0 / maxf(0.1, style.spinner_speed) + ) + + return container + +func _create_default_spinner_texture(size: Vector2) -> ImageTexture: + var px = int(maxf(32, size.x)) + var image = Image.create(px, px, false, Image.FORMAT_RGBA8) + image.fill(Color.TRANSPARENT) + + var center = Vector2(px / 2.0, px / 2.0) + var radius = px * 0.38 + var thickness = maxf(2.0, px * 0.09) + + for x in range(px): + for y in range(px): + var pos = Vector2(x, y) + var dist = pos.distance_to(center) + if dist >= radius - thickness and dist <= radius + thickness: + var angle = (pos - center).angle() + # Fading arc: transparent at -PI, opaque at PI/2 + var normalized = fposmod(angle + PI, TAU) / TAU + var alpha = 0.1 + 0.9 * pow(normalized, 1.5) + image.set_pixel(x, y, Color(1.0, 1.0, 1.0, alpha)) + + return ImageTexture.create_from_image(image) + +func _create_texture_spinner() -> Control: + var container = CenterContainer.new() + container.mouse_filter = Control.MOUSE_FILTER_IGNORE + container.custom_minimum_size = style.get_effective_spinner_size(_ui_scale) + + var texture_rect = TextureRect.new() + texture_rect.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED + texture_rect.texture = style.spinner_texture + var spinner_size = style.get_effective_spinner_size(_ui_scale) + texture_rect.custom_minimum_size = spinner_size + texture_rect.pivot_offset = spinner_size / 2.0 + texture_rect.modulate = style.spinner_tint + container.add_child(texture_rect) + + var rotate_tween = create_tween() + rotate_tween.set_loops() + rotate_tween.tween_method( + func(angle: float): texture_rect.rotation = angle, + 0.0, TAU, + 1.0 / maxf(0.1, style.spinner_speed) + ) + + return container + +func _create_scene_spinner() -> Control: + var instance = style.spinner_scene.instantiate() + if not instance is Control: + push_error("GodotxToastLoadingView: spinner_scene root must be a Control") + instance.queue_free() + return null + instance.custom_minimum_size = style.get_effective_spinner_size(_ui_scale) + return instance + +func _setup_progress_bar(): + if not style or not style.show_progress_bar: + return + + _progress_bar = ProgressBar.new() + _progress_bar.min_value = 0.0 + _progress_bar.max_value = 100.0 + _progress_bar.value = progress + _progress_bar.custom_minimum_size.y = style.progress_bar_height + _progress_bar.size_flags_horizontal = Control.SIZE_EXPAND_FILL + _progress_bar.mouse_filter = Control.MOUSE_FILTER_IGNORE + + if style.progress_bar_style: + _progress_bar.add_theme_stylebox_override("fill", style.progress_bar_style) + + # Inject below the HBox content inside a VBox wrapper. + # We need to restructure: wrap _content_container in a VBox and add progress bar below. + var parent = _content_container.get_parent() + if parent: + var vbox = VBoxContainer.new() + vbox.size_flags_horizontal = Control.SIZE_EXPAND_FILL + vbox.size_flags_vertical = Control.SIZE_EXPAND_FILL + vbox.mouse_filter = Control.MOUSE_FILTER_IGNORE + vbox.add_theme_constant_override("separation", 4) + + parent.remove_child(_content_container) + vbox.add_child(_content_container) + vbox.add_child(_progress_bar) + parent.add_child(vbox) + +func _on_progress_changed(): + if _progress_bar: + _progress_bar.value = progress + if not toast_id.is_empty(): + progress_updated.emit(toast_id, progress) + +func update_progress(value: float, new_message: String = ""): + progress = value + if not new_message.is_empty(): + message = new_message + if _text_label: + _text_label.text = message + +func complete(success: bool = true, final_message: String = ""): + if not final_message.is_empty(): + message = final_message + if _text_label: + _text_label.text = message + + if _spinner: + _spinner.visible = false + + dismiss(GodotxToastEnums.ToastDismissReason.API) diff --git a/addons/godotx_toast/runtime/toast_loading_view.gd.uid b/addons/godotx_toast/runtime/toast_loading_view.gd.uid new file mode 100644 index 0000000..e00cff9 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_loading_view.gd.uid @@ -0,0 +1 @@ +uid://dn34sxo3itall diff --git a/addons/godotx_toast/runtime/toast_manager.gd b/addons/godotx_toast/runtime/toast_manager.gd new file mode 100644 index 0000000..926877a --- /dev/null +++ b/addons/godotx_toast/runtime/toast_manager.gd @@ -0,0 +1,249 @@ +class_name GodotxToastManager +extends CanvasLayer + +signal toast_shown(id: String) +signal toast_dismissed(id: String, reason: int) +signal toast_clicked(id: String) +signal loading_progress_updated(id: String, progress: float) +signal loading_completed(id: String, success: bool) + +var proportion: float = 30.0 +var default_origin: GodotxToastEnums.ToastOrigin = GodotxToastEnums.ToastOrigin.BOTTOM +var default_animation: GodotxToastEnums.ToastAnimation = GodotxToastEnums.ToastAnimation.SLIDE +var default_time: int = GodotxToastEnums.ToastTime.MEDIUM + +var _containers: Dictionary = {} +var _deck_containers: Dictionary = {} +var _loading_toasts: Dictionary = {} +var _toast_counter: int = 0 +var _ui_scale: float = 1.0 +var _cached_width: float = 0.0 + +func _ready(): + layer = 128 + follow_viewport_enabled = false + _setup_containers() + _update_ui_scale() + get_tree().root.size_changed.connect(_on_viewport_resized) + +func _setup_containers(): + for origin in GodotxToastEnums.ToastOrigin.values(): + var container = GodotxToastContainer.new(origin) + container.name = "Container_%d" % origin + add_child(container) + _containers[origin] = container + + var deck_container = GodotxToastDeckContainer.new(origin) + deck_container.name = "DeckContainer_%d" % origin + add_child(deck_container) + _deck_containers[origin] = deck_container + +func show_toast( + message: String, + style: GodotxToastStyle, + time: float, + origin: GodotxToastEnums.ToastOrigin, + animation: GodotxToastEnums.ToastAnimation, + options: Dictionary = {} +) -> String: + + if message.is_empty(): + push_error("GodotxToastManager: Cannot show toast with empty message") + return "" + + if style == null: + push_error("GodotxToastManager: Cannot show toast with null style") + return "" + + _toast_counter += 1 + var toast_id = "toast_%d_%d" % [_toast_counter, Time.get_ticks_msec()] + + var toast_view = GodotxToastView.new() + toast_view.toast_id = toast_id + toast_view.style = style + toast_view.message = message + toast_view.display_time = time + toast_view.origin = origin + toast_view.animation = animation + + toast_view.clicked.connect(_on_toast_clicked) + toast_view.dismissed.connect(_on_toast_dismissed) + toast_view.swiped.connect(_on_toast_swiped) + + var max_width = _calculate_toast_max_width() + toast_view.set_max_width(max_width) + + var use_deck = style.stack_strategy == GodotxToastEnums.StackStrategy.DECK + var container = _deck_containers[origin] if use_deck else _containers[origin] + + var success = container.add_toast(toast_view, style.stack_strategy, style.max_visible) + + if not success: + return "" + + toast_shown.emit(toast_id) + return toast_id + +func show_loading( + message: String, + style: GodotxToastStyle, + origin: GodotxToastEnums.ToastOrigin, + animation: GodotxToastEnums.ToastAnimation, + options: Dictionary = {} +) -> String: + + if message.is_empty(): + push_error("GodotxToastManager: Cannot show loading toast with empty message") + return "" + + if style == null: + push_error("GodotxToastManager: Cannot show loading toast with null style") + return "" + + _toast_counter += 1 + var toast_id = "loading_%d_%d" % [_toast_counter, Time.get_ticks_msec()] + + var loading_view = GodotxToastLoadingView.new() + loading_view.toast_id = toast_id + loading_view.style = style + loading_view.message = message + loading_view.display_time = -1 + loading_view.origin = origin + loading_view.animation = animation + + loading_view.clicked.connect(_on_toast_clicked) + loading_view.dismissed.connect(_on_loading_dismissed) + loading_view.progress_updated.connect(_on_loading_progress_updated) + loading_view.swiped.connect(_on_toast_swiped) + + var max_width = _calculate_toast_max_width() + loading_view.set_max_width(max_width) + + var use_deck = style.stack_strategy == GodotxToastEnums.StackStrategy.DECK + var container = _deck_containers[origin] if use_deck else _containers[origin] + + var success = container.add_toast(loading_view, style.stack_strategy, style.max_visible) + + if not success: + return "" + + _loading_toasts[toast_id] = loading_view + toast_shown.emit(toast_id) + return toast_id + +func update_loading(toast_id: String, progress: float, new_message: String = "") -> bool: + if not _loading_toasts.has(toast_id): + return false + + var loading_view = _loading_toasts[toast_id] + loading_view.update_progress(progress, new_message) + return true + +func complete_loading(toast_id: String, success: bool = true, final_message: String = "") -> bool: + if not _loading_toasts.has(toast_id): + return false + + var loading_view = _loading_toasts[toast_id] + loading_view.complete(success, final_message) + + if success: + loading_completed.emit(toast_id, true) + else: + loading_completed.emit(toast_id, false) + + _loading_toasts.erase(toast_id) + return true + +func dismiss_toast(toast_id: String) -> bool: + for container in _containers.values(): + if container.dismiss_toast(toast_id, GodotxToastEnums.ToastDismissReason.API): + return true + + for container in _deck_containers.values(): + if container.dismiss_toast(toast_id, GodotxToastEnums.ToastDismissReason.API): + return true + + if _loading_toasts.has(toast_id): + var loading_view = _loading_toasts[toast_id] + loading_view.dismiss(GodotxToastEnums.ToastDismissReason.API) + _loading_toasts.erase(toast_id) + return true + + return false + +func clear_all(): + for container in _containers.values(): + container.dismiss_all(GodotxToastEnums.ToastDismissReason.API) + + for container in _deck_containers.values(): + container.dismiss_all(GodotxToastEnums.ToastDismissReason.API) + + for toast_id in _loading_toasts.keys(): + _loading_toasts[toast_id].dismiss(GodotxToastEnums.ToastDismissReason.API) + _loading_toasts.clear() + +func dismiss_by_origin(origin: GodotxToastEnums.ToastOrigin): + if _containers.has(origin): + _containers[origin].dismiss_all(GodotxToastEnums.ToastDismissReason.API) + + if _deck_containers.has(origin): + _deck_containers[origin].dismiss_all(GodotxToastEnums.ToastDismissReason.API) + +func _calculate_toast_max_width() -> float: + var viewport_size = get_viewport().get_visible_rect().size + var safe_margin = 48.0 * _ui_scale + return viewport_size.x - (safe_margin * 2) + +func _on_viewport_resized(): + _update_ui_scale() + var new_max_width = _calculate_toast_max_width() + if abs(new_max_width - _cached_width) > 1.0: + _cached_width = new_max_width + for container in _containers.values(): + container.update_max_widths(new_max_width) + container.handle_viewport_resized() + + for container in _deck_containers.values(): + container.update_max_widths(new_max_width) + container.handle_viewport_resized() + +func _update_ui_scale(): + var viewport = get_viewport() + if viewport: + _ui_scale = viewport.content_scale_factor + +func _on_toast_clicked(toast_id: String): + toast_clicked.emit(toast_id) + +func _on_toast_dismissed(toast_id: String, reason: int): + toast_dismissed.emit(toast_id, reason) + +func _on_toast_swiped(_toast_id: String, _direction: Vector2): + # Swipe dismiss is handled by the container; do nothing here to avoid double-dismiss. + pass + +func _on_loading_dismissed(toast_id: String, reason: int): + toast_dismissed.emit(toast_id, reason) + _loading_toasts.erase(toast_id) + +func _on_loading_progress_updated(toast_id: String, progress: float): + loading_progress_updated.emit(toast_id, progress) + +func set_proportion(value: float): + proportion = clamp(value, 1.0, 100.0) + _on_viewport_resized() + +func update_config( + p_proportion: float = -1, + p_origin: int = -1, + p_animation: int = -1, + p_time: int = -1 +): + if p_proportion > 0: + proportion = clamp(p_proportion, 1.0, 100.0) + if p_origin >= 0: + default_origin = p_origin + if p_animation >= 0: + default_animation = p_animation + if p_time > 0: + default_time = p_time diff --git a/addons/godotx_toast/runtime/toast_manager.gd.uid b/addons/godotx_toast/runtime/toast_manager.gd.uid new file mode 100644 index 0000000..55231ff --- /dev/null +++ b/addons/godotx_toast/runtime/toast_manager.gd.uid @@ -0,0 +1 @@ +uid://xkvjd0k6u842 diff --git a/addons/godotx_toast/runtime/toast_style.gd b/addons/godotx_toast/runtime/toast_style.gd new file mode 100644 index 0000000..bb583c4 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_style.gd @@ -0,0 +1,145 @@ +@tool +class_name GodotxToastStyle +extends Resource + +@export_group("Background") +@export var background_type: GodotxToastEnums.BackgroundType = GodotxToastEnums.BackgroundType.COLOR +@export var background_color: Color = Color(0.2, 0.2, 0.2, 0.95) +@export var background_texture: Texture2D +@export var background_scene: PackedScene + +@export_group("Icon") +@export var icon_enabled: bool = false +@export var icon_content: Texture2D +@export var icon_scene: PackedScene +@export var icon_size: Vector2 = Vector2(32, 32) +@export var icon_tint: Color = Color.WHITE +@export var icon_margin: int = 8 + +@export_group("Close Button") +@export var close_button_enabled: bool = false +@export var close_button_content: Texture2D +@export var close_button_scene: PackedScene +@export var close_button_size: Vector2 = Vector2(20, 20) +@export var close_button_tint: Color = Color.WHITE +@export var close_button_margin: int = 8 + +@export_group("Spinner (Loading)") +@export var spinner_type: GodotxToastEnums.SpinnerType = GodotxToastEnums.SpinnerType.NONE +@export var spinner_texture: Texture2D +@export var spinner_scene: PackedScene +@export var spinner_size: Vector2 = Vector2(24, 24) +@export var spinner_tint: Color = Color.WHITE +@export var spinner_speed: float = 1.0 + +@export_group("Progress Bar (Loading)") +@export var show_progress_bar: bool = false +@export var progress_bar_height: int = 4 +@export var progress_bar_style: StyleBox + +@export_group("Text") +@export var font: Font +@export var font_size: int = 22 +@export var font_color: Color = Color.WHITE +@export var outline_size: int = 0 +@export var outline_color: Color = Color.BLACK +@export var text_alignment: HorizontalAlignment = HORIZONTAL_ALIGNMENT_CENTER + +@export_group("Layout") +@export var padding: Vector4i = Vector4i(16, 16, 16, 16) +@export var gap: int = 8 +@export var minimum_width: int = 320 + +@export var corner_radius: int = 8 +@export var use_pill_shape: bool = true +@export var border_enabled: bool = false +@export var border_width: int = 1 +@export var border_color: Color = Color.WHITE + +@export_group("Shadow") +@export var shadow_enabled: bool = true +@export var shadow_color: Color = Color(0, 0, 0, 0.3) +@export var shadow_offset: Vector2 = Vector2(0, 4) +@export var shadow_size: int = 4 + +@export_group("Behavior") +@export var tap_to_dismiss: bool = true +@export var block_input: bool = false +@export var pause_on_hover: bool = false +@export var allow_stack: bool = true +@export var max_visible: int = 3 +@export var stack_strategy: GodotxToastEnums.StackStrategy = GodotxToastEnums.StackStrategy.REPLACE_OLDEST +@export var safe_area_margin_top: int = 20 +@export var safe_area_margin_bottom: int = 20 +@export var safe_area_margin_left: int = 20 +@export var safe_area_margin_right: int = 20 + +@export_group("Swipe") +@export var swipe_enabled: bool = false +@export var swipe_direction: GodotxToastEnums.SwipeDirection = GodotxToastEnums.SwipeDirection.HORIZONTAL +@export var swipe_threshold: float = 50.0 +@export var swipe_velocity_threshold: float = 200.0 + +@export_group("Deck Stack") +@export var deck_stack_scale_step: float = 0.08 +@export var deck_stack_offset_step: float = 8.0 +@export var deck_stack_alpha_step: float = 0.2 + +@export_group("Animation") +@export var default_animation: GodotxToastEnums.ToastAnimation = GodotxToastEnums.ToastAnimation.SLIDE +@export var animation_duration: float = 0.3 +@export var animation_easing: Tween.EaseType = Tween.EASE_OUT +@export var animation_trans: Tween.TransitionType = Tween.TRANS_QUAD + +@export_group("Spawn") +@export var default_origin: GodotxToastEnums.ToastOrigin = GodotxToastEnums.ToastOrigin.BOTTOM + +func get_effective_padding(ui_scale: float = 1.0) -> Vector4i: + return Vector4i( + int(padding.x * ui_scale), + int(padding.y * ui_scale), + int(padding.z * ui_scale), + int(padding.w * ui_scale) + ) + +func get_effective_font_size(ui_scale: float = 1.0) -> int: + return int(font_size * ui_scale) + +func get_effective_icon_size(ui_scale: float = 1.0) -> Vector2: + return icon_size * ui_scale + +func get_effective_close_button_size(ui_scale: float = 1.0) -> Vector2: + return close_button_size * ui_scale + +func get_effective_spinner_size(ui_scale: float = 1.0) -> Vector2: + return spinner_size * ui_scale + +func get_effective_gap(ui_scale: float = 1.0) -> int: + return int(gap * ui_scale) + +func get_effective_minimum_width(ui_scale: float = 1.0) -> int: + return int(minimum_width * ui_scale) + + +func get_effective_corner_radius(ui_scale: float = 1.0) -> int: + return int(corner_radius * ui_scale) + +func get_effective_shadow_offset(ui_scale: float = 1.0) -> Vector2: + return shadow_offset * ui_scale + +func get_effective_shadow_size(ui_scale: float = 1.0) -> int: + return int(shadow_size * ui_scale) + +func get_effective_safe_area_margins(ui_scale: float = 1.0) -> Dictionary: + return { + "top": int(safe_area_margin_top * ui_scale), + "bottom": int(safe_area_margin_bottom * ui_scale), + "left": int(safe_area_margin_left * ui_scale), + "right": int(safe_area_margin_right * ui_scale) + } + +func get_effective_deck_stack_offset_step(ui_scale: float = 1.0) -> float: + return deck_stack_offset_step * ui_scale + +func get_effective_swipe_threshold(ui_scale: float = 1.0) -> float: + return swipe_threshold * ui_scale diff --git a/addons/godotx_toast/runtime/toast_style.gd.uid b/addons/godotx_toast/runtime/toast_style.gd.uid new file mode 100644 index 0000000..4cd1042 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_style.gd.uid @@ -0,0 +1 @@ +uid://bev1qb40mg6p2 diff --git a/addons/godotx_toast/runtime/toast_styles.gd b/addons/godotx_toast/runtime/toast_styles.gd new file mode 100644 index 0000000..2ebffa2 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_styles.gd @@ -0,0 +1,139 @@ +class_name GodotxToastStyles + +const SUCCESS = "success" +const WARNING = "warning" +const INFO = "info" +const ERROR = "error" +const LIGHT = "light" +const DARK = "dark" +const LOADING = "loading" + +static var _styles: Dictionary = {} +static var _default_font_path: String = "res://addons/godotx_toast/assets/fonts/Roboto-Regular.ttf" +static var _font_cache: Dictionary = {} + +static func _static_init(): + _register_builtin_styles() + +static func register(id: String, style: GodotxToastStyle) -> void: + if id.is_empty(): + push_error("GodotxToastStyles: Cannot register style with empty id") + return + if style == null: + push_error("GodotxToastStyles: Cannot register null style for id: %s" % id) + return + _styles[id.to_lower()] = style + +static func unregister(id: String) -> void: + _styles.erase(id.to_lower()) + +static func get_style(id: Variant) -> GodotxToastStyle: + if id is GodotxToastStyle: + return id + if id is String: + var key = id.to_lower() + if _styles.has(key): + return _styles[key] + push_error("GodotxToastStyles: Style not found: %s" % id) + return null + push_error("GodotxToastStyles: Invalid style type: %s" % typeof(id)) + return null + +static func has_style(id: String) -> bool: + return _styles.has(id.to_lower()) + +static func get_default_font() -> Font: + if not _font_cache.has("default"): + var font = load(_default_font_path) if ResourceLoader.exists(_default_font_path) else null + if font == null: + font = ThemeDB.get_fallback_font() + _font_cache["default"] = font + return _font_cache["default"] + +static func clear_font_cache() -> void: + _font_cache.clear() + +static func _register_builtin_styles() -> void: + var font = get_default_font() + + var success = GodotxToastStyle.new() + success.background_color = Color(0.13, 0.55, 0.13, 0.95) + success.font = font + success.font_color = Color.WHITE + success.border_color = Color(0.2, 0.7, 0.2, 1.0) + success.shadow_color = Color(0, 0, 0, 0.25) + success.default_origin = GodotxToastEnums.ToastOrigin.BOTTOM + register(SUCCESS, success) + + var warning = GodotxToastStyle.new() + warning.background_color = Color(0.96, 0.59, 0.12, 0.95) + warning.font = font + warning.font_color = Color.BLACK + warning.border_color = Color(1.0, 0.76, 0.03, 1.0) + warning.shadow_color = Color(0, 0, 0, 0.25) + warning.default_origin = GodotxToastEnums.ToastOrigin.BOTTOM + register(WARNING, warning) + + var info = GodotxToastStyle.new() + info.background_color = Color(0.13, 0.47, 0.76, 0.95) + info.font = font + info.font_color = Color.WHITE + info.border_color = Color(0.25, 0.6, 0.9, 1.0) + info.shadow_color = Color(0, 0, 0, 0.25) + info.default_origin = GodotxToastEnums.ToastOrigin.BOTTOM + register(INFO, info) + + var error = GodotxToastStyle.new() + error.background_color = Color(0.83, 0.18, 0.18, 0.95) + error.font = font + error.font_color = Color.WHITE + error.border_color = Color(0.95, 0.3, 0.3, 1.0) + error.shadow_color = Color(0, 0, 0, 0.3) + error.default_origin = GodotxToastEnums.ToastOrigin.BOTTOM + register(ERROR, error) + + var light = GodotxToastStyle.new() + light.background_color = Color(0.95, 0.95, 0.95, 0.98) + light.font = font + light.font_color = Color(0.13, 0.13, 0.13, 1.0) + light.border_enabled = true + light.border_color = Color(0.8, 0.8, 0.8, 1.0) + light.shadow_color = Color(0, 0, 0, 0.15) + light.default_origin = GodotxToastEnums.ToastOrigin.BOTTOM + register(LIGHT, light) + + var dark = GodotxToastStyle.new() + dark.background_color = Color(0.2, 0.2, 0.2, 0.98) + dark.font = font + dark.font_color = Color(0.95, 0.95, 0.95, 1.0) + dark.border_enabled = true + dark.border_color = Color(0.4, 0.4, 0.4, 1.0) + dark.shadow_color = Color(0, 0, 0, 0.4) + dark.default_origin = GodotxToastEnums.ToastOrigin.BOTTOM + register(DARK, dark) + + var loading = GodotxToastStyle.new() + loading.background_color = Color(0.25, 0.25, 0.25, 0.98) + loading.font = font + loading.font_color = Color.WHITE + loading.border_enabled = true + loading.border_color = Color(0.5, 0.5, 0.5, 0.5) + loading.shadow_color = Color(0, 0, 0, 0.4) + loading.shadow_enabled = true + loading.default_origin = GodotxToastEnums.ToastOrigin.BOTTOM + # Spinner configuration + loading.spinner_type = GodotxToastEnums.SpinnerType.DEFAULT + loading.spinner_tint = Color(0.4, 0.7, 1.0) + loading.spinner_speed = 1.5 + loading.spinner_size = Vector2(28, 28) + # Make icon slot visible so spinner renders + loading.icon_enabled = true + loading.icon_size = Vector2(28, 28) + # Prevent user from dismissing loading toasts + loading.tap_to_dismiss = false + loading.swipe_enabled = false + loading.close_button_enabled = false + loading.max_visible = 1 + loading.stack_strategy = GodotxToastEnums.StackStrategy.REPLACE_OLDEST + loading.default_animation = GodotxToastEnums.ToastAnimation.FADE + register(LOADING, loading) diff --git a/addons/godotx_toast/runtime/toast_styles.gd.uid b/addons/godotx_toast/runtime/toast_styles.gd.uid new file mode 100644 index 0000000..741edf4 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_styles.gd.uid @@ -0,0 +1 @@ +uid://cm5b0s4ihoqcv diff --git a/addons/godotx_toast/runtime/toast_view.gd b/addons/godotx_toast/runtime/toast_view.gd new file mode 100644 index 0000000..4e03392 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_view.gd @@ -0,0 +1,522 @@ +## GodotxToastView — single toast notification node. +## +## Architecture: extends PanelContainer. +## • Background (COLOR): StyleBoxFlat applied to the "panel" theme slot. +## StyleBoxFlat.content_margin_* provides the padding — no extra containers needed. +## • Background (TEXTURE/SCENE): StyleBoxEmpty on "panel" slot + a TextureRect/ +## scene child positioned with z_index < 0 so it renders behind the content. +## • Content: HBoxContainer [icon | label | close] fills the PanelContainer naturally. +## +## PanelContainer sizes itself to max(custom_minimum_size, content + content_margin), +## which gives correct, compact toasts without any manual height calculation. +class_name GodotxToastView +extends PanelContainer + +signal clicked(toast_id: String) +signal close_requested(toast_id: String) +signal dismissed(toast_id: String, reason: int) +signal swiped(toast_id: String, direction: Vector2) + +var toast_id: String +var style: GodotxToastStyle +var message: String +var display_time: float +var origin: GodotxToastEnums.ToastOrigin +var animation: GodotxToastEnums.ToastAnimation + +var _ui_scale: float = 1.0 +var _timer: Timer +var _is_hovering: bool = false +var _is_dismissing: bool = false +var _tween: Tween +var _content_container: HBoxContainer +var _icon_container: Control +var _text_label: Label +var _close_container: Control + +var _is_dragging: bool = false +var _drag_start_pos: Vector2 +var _drag_current_pos: Vector2 +var _drag_start_mouse: Vector2 + +func _init(): + mouse_filter = MOUSE_FILTER_STOP + z_index = 100 + anchors_preset = Control.PRESET_TOP_LEFT + size_flags_horizontal = Control.SIZE_SHRINK_BEGIN + size_flags_vertical = Control.SIZE_SHRINK_CENTER + +func _ready(): + _ui_scale = _get_ui_scale() + _setup_background() + _setup_layout() + _apply_style() + _setup_timer() + _setup_input() + +func _get_ui_scale() -> float: + var s = get_global_transform().get_scale().x + return s if s > 0.01 else 1.0 + +# --------------------------------------------------------------------------- +# Background +# --------------------------------------------------------------------------- + +func _setup_background(): + var p = style.get_effective_padding(_ui_scale) + + match style.background_type: + GodotxToastEnums.BackgroundType.NONE: + var empty = StyleBoxEmpty.new() + # Content margin keeps padding even with no visible background + empty.content_margin_left = p.x + empty.content_margin_top = p.y + empty.content_margin_right = p.z + empty.content_margin_bottom = p.w + add_theme_stylebox_override("panel", empty) + + GodotxToastEnums.BackgroundType.COLOR: + var sb = StyleBoxFlat.new() + sb.bg_color = style.background_color + var cr: int + if style.use_pill_shape: + # Pill shape: corner radius = half of estimated height + var font_size = style.get_effective_font_size(_ui_scale) + var padding = style.get_effective_padding(_ui_scale) + var estimated_height = font_size + padding.y + padding.w + 4 # Extra for better pill shape + cr = int(estimated_height / 2.0) + else: + cr = style.get_effective_corner_radius(_ui_scale) + sb.corner_radius_top_left = cr + sb.corner_radius_top_right = cr + sb.corner_radius_bottom_left = cr + sb.corner_radius_bottom_right = cr + if style.border_enabled: + sb.border_width_left = style.border_width + sb.border_width_top = style.border_width + sb.border_width_right = style.border_width + sb.border_width_bottom = style.border_width + sb.border_color = style.border_color + if style.shadow_enabled: + sb.shadow_color = style.shadow_color + sb.shadow_size = style.get_effective_shadow_size(_ui_scale) + sb.shadow_offset = style.get_effective_shadow_offset(_ui_scale) + sb.content_margin_left = p.x + sb.content_margin_top = p.y + sb.content_margin_right = p.z + sb.content_margin_bottom = p.w + add_theme_stylebox_override("panel", sb) + + GodotxToastEnums.BackgroundType.TEXTURE: + if style.background_texture: + # Transparent panel + texture child behind content. + var empty = StyleBoxEmpty.new() + empty.content_margin_left = p.x + empty.content_margin_top = p.y + empty.content_margin_right = p.z + empty.content_margin_bottom = p.w + add_theme_stylebox_override("panel", empty) + var tx = TextureRect.new() + tx.texture = style.background_texture + tx.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_COVERED + tx.z_index = -1 + tx.mouse_filter = Control.MOUSE_FILTER_IGNORE + # Anchors fill the PanelContainer, ignoring content_margin. + tx.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT) + add_child(tx) + else: + push_error("GodotxToastView: background_type TEXTURE but background_texture is null") + + GodotxToastEnums.BackgroundType.SCENE: + if style.background_scene: + var empty = StyleBoxEmpty.new() + empty.content_margin_left = p.x + empty.content_margin_top = p.y + empty.content_margin_right = p.z + empty.content_margin_bottom = p.w + add_theme_stylebox_override("panel", empty) + var inst = style.background_scene.instantiate() + if inst is Control: + inst.z_index = -1 + inst.mouse_filter = Control.MOUSE_FILTER_IGNORE + inst.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT) + add_child(inst) + else: + push_error("GodotxToastView: background_scene root must be a Control") + inst.queue_free() + else: + push_error("GodotxToastView: background_type SCENE but background_scene is null") + +# --------------------------------------------------------------------------- +# Layout — [icon | label | close] inside PanelContainer +# --------------------------------------------------------------------------- + +func _setup_layout(): + _content_container = HBoxContainer.new() + _content_container.alignment = BoxContainer.ALIGNMENT_CENTER + _content_container.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN + _content_container.size_flags_vertical = Control.SIZE_SHRINK_CENTER + _content_container.mouse_filter = Control.MOUSE_FILTER_IGNORE + _content_container.add_theme_constant_override("separation", style.get_effective_gap(_ui_scale)) + add_child(_content_container) + + _icon_container = Control.new() + _icon_container.mouse_filter = Control.MOUSE_FILTER_IGNORE + _icon_container.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN + _icon_container.size_flags_vertical = Control.SIZE_SHRINK_CENTER + _content_container.add_child(_icon_container) + + _text_label = Label.new() + _text_label.horizontal_alignment = style.text_alignment + _text_label.vertical_alignment = VerticalAlignment.VERTICAL_ALIGNMENT_CENTER + _text_label.autowrap_mode = TextServer.AUTOWRAP_OFF + + _text_label.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN + _text_label.size_flags_vertical = Control.SIZE_SHRINK_CENTER + _text_label.mouse_filter = Control.MOUSE_FILTER_IGNORE + _content_container.add_child(_text_label) + + _close_container = Control.new() + _close_container.mouse_filter = Control.MOUSE_FILTER_IGNORE + _close_container.size_flags_vertical = Control.SIZE_SHRINK_CENTER + _content_container.add_child(_close_container) + +# --------------------------------------------------------------------------- +# Style application +# --------------------------------------------------------------------------- + +func _apply_style(): + var font_to_use: Font = style.font if style.font else GodotxToastStyles.get_default_font() + if font_to_use: + _text_label.add_theme_font_override("font", font_to_use) + _text_label.add_theme_font_size_override("font_size", style.get_effective_font_size(_ui_scale)) + _text_label.add_theme_color_override("font_color", style.font_color) + if style.outline_size > 0: + _text_label.add_theme_constant_override("outline_size", style.outline_size) + _text_label.add_theme_color_override("font_outline_color", style.outline_color) + _text_label.text = message + + _setup_icon() + _setup_close_button() + + # Apply padding as custom_minimum_size to ensure consistent height across all background types + var pad = style.get_effective_padding(_ui_scale) + var font_size = style.get_effective_font_size(_ui_scale) + # Height: font size + vertical padding (top + bottom) + var min_height = font_size + pad.y + pad.w + custom_minimum_size.y = min_height + +func _setup_icon(): + for ch in _icon_container.get_children(): + ch.queue_free() + if not style.icon_enabled: + _icon_container.custom_minimum_size = Vector2.ZERO + return + var sz = style.get_effective_icon_size(_ui_scale) + _icon_container.custom_minimum_size = sz + _icon_container.size = sz + if style.icon_scene: + var inst = style.icon_scene.instantiate() + if inst is Control: + inst.custom_minimum_size = sz + inst.size = sz + _icon_container.add_child(inst) + else: + push_error("GodotxToastView: icon_scene root must be a Control") + inst.queue_free() + elif style.icon_content: + var tx = TextureRect.new() + tx.texture = style.icon_content + tx.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED + tx.expand_mode = TextureRect.EXPAND_IGNORE_SIZE + tx.texture_filter = CanvasItem.TEXTURE_FILTER_LINEAR + tx.modulate = style.icon_tint + # Force exact size and center the icon + tx.custom_minimum_size = sz + tx.size = sz + tx.position = Vector2.ZERO + tx.mouse_filter = Control.MOUSE_FILTER_IGNORE + _icon_container.add_child(tx) + +func _setup_close_button(): + for ch in _close_container.get_children(): + ch.queue_free() + if not style.close_button_enabled: + _close_container.custom_minimum_size = Vector2.ZERO + return + var sz = style.get_effective_close_button_size(_ui_scale) + _close_container.custom_minimum_size = sz + _close_container.mouse_filter = Control.MOUSE_FILTER_STOP + if style.close_button_scene: + var inst = style.close_button_scene.instantiate() + if inst is Control: + inst.custom_minimum_size = sz + inst.size = sz + _close_container.add_child(inst) + else: + push_error("GodotxToastView: close_button_scene root must be a Control") + inst.queue_free() + elif style.close_button_content: + var tx = TextureRect.new() + tx.texture = style.close_button_content + tx.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED + tx.modulate = style.close_button_tint + tx.custom_minimum_size = sz + tx.size = sz + tx.mouse_filter = Control.MOUSE_FILTER_IGNORE + _close_container.add_child(tx) + _close_container.gui_input.connect(_on_close_input) + +# --------------------------------------------------------------------------- +# Timer +# --------------------------------------------------------------------------- + +func _setup_timer(): + if display_time <= 0: + return + _timer = Timer.new() + _timer.one_shot = true + _timer.wait_time = display_time + _timer.timeout.connect(_on_timeout) + add_child(_timer) + _timer.start() + +# --------------------------------------------------------------------------- +# Input — all handled via gui_input (MOUSE_FILTER_STOP ensures only the +# topmost node receives events; critical for the deck's active-only behavior). +# --------------------------------------------------------------------------- + +func _setup_input(): + gui_input.connect(_on_gui_input) + if style.pause_on_hover: + mouse_entered.connect(_on_mouse_entered) + mouse_exited.connect(_on_mouse_exited) + +func _on_gui_input(event: InputEvent): + if _is_dismissing: + return + + var threshold = style.get_effective_swipe_threshold(_ui_scale) + + if event is InputEventMouseButton and event.button_index == MOUSE_BUTTON_LEFT: + if event.pressed: + _is_dragging = true + _drag_start_pos = position + _drag_start_mouse = event.global_position + _drag_current_pos = event.global_position + else: + if _is_dragging: + _is_dragging = false + var did_swipe = _evaluate_swipe(threshold) + if not did_swipe and style.tap_to_dismiss: + clicked.emit(toast_id) + dismiss(GodotxToastEnums.ToastDismissReason.CLICK) + + elif event is InputEventMouseMotion and _is_dragging: + _drag_current_pos = event.global_position + if style.swipe_enabled: + _update_drag_position() + + elif event is InputEventScreenTouch: + if event.pressed: + _is_dragging = true + _drag_start_pos = position + _drag_start_mouse = event.position + _drag_current_pos = event.position + else: + if _is_dragging: + _is_dragging = false + var did_swipe = _evaluate_swipe(threshold) + if not did_swipe and style.tap_to_dismiss: + clicked.emit(toast_id) + dismiss(GodotxToastEnums.ToastDismissReason.CLICK) + + elif event is InputEventScreenDrag and _is_dragging: + _drag_current_pos = event.position + if style.swipe_enabled: + _update_drag_position() + +func _on_close_input(event: InputEvent): + if _is_dismissing: + return + if event is InputEventMouseButton and event.pressed and event.button_index == MOUSE_BUTTON_LEFT: + close_requested.emit(toast_id) + dismiss(GodotxToastEnums.ToastDismissReason.CLOSE_BUTTON) + elif event is InputEventScreenTouch and event.pressed: + close_requested.emit(toast_id) + dismiss(GodotxToastEnums.ToastDismissReason.CLOSE_BUTTON) + +func _update_drag_position(): + var delta = _drag_current_pos - _drag_start_mouse + match style.swipe_direction: + GodotxToastEnums.SwipeDirection.HORIZONTAL: + position.x = _drag_start_pos.x + delta.x + GodotxToastEnums.SwipeDirection.VERTICAL: + position.y = _drag_start_pos.y + delta.y + GodotxToastEnums.SwipeDirection.BOTH: + position = _drag_start_pos + delta + +func _evaluate_swipe(threshold: float) -> bool: + if not style.swipe_enabled: + return false + var delta = _drag_current_pos - _drag_start_mouse + var direction = Vector2.ZERO + match style.swipe_direction: + GodotxToastEnums.SwipeDirection.HORIZONTAL: + if abs(delta.x) > threshold: + direction = Vector2(sign(delta.x), 0) + GodotxToastEnums.SwipeDirection.VERTICAL: + if abs(delta.y) > threshold: + direction = Vector2(0, sign(delta.y)) + GodotxToastEnums.SwipeDirection.BOTH: + if delta.length() > threshold: + direction = delta.normalized() + if direction != Vector2.ZERO: + _swipe_out(direction) + return true + if delta.length() > 2.0: + _snap_back() + return false + +func _swipe_out(direction: Vector2): + if _tween and _tween.is_valid(): + _tween.kill() + _tween = create_tween() + _tween.set_ease(style.animation_easing) + _tween.set_trans(style.animation_trans) + var vp = get_viewport().get_visible_rect().size + var target = position + if direction.x != 0: + target.x = (vp.x + size.x) * sign(direction.x) + if direction.y != 0: + target.y = (vp.y + size.y) * sign(direction.y) + _tween.tween_property(self, "position", target, 0.2) + _tween.tween_callback(func(): + swiped.emit(toast_id, direction) + _complete_dismiss(GodotxToastEnums.ToastDismissReason.SWIPE) + ) + +func _snap_back(): + if _tween and _tween.is_valid(): + _tween.kill() + _tween = create_tween() + _tween.set_ease(Tween.EASE_OUT) + _tween.set_trans(Tween.TRANS_SPRING) + _tween.tween_property(self, "position", _drag_start_pos, 0.3) + +func _on_mouse_entered(): + _is_hovering = true + if _timer: + _timer.paused = true + +func _on_mouse_exited(): + _is_hovering = false + if _timer: + _timer.paused = false + +func _on_timeout(): + if not _is_dismissing: + dismiss(GodotxToastEnums.ToastDismissReason.TIMEOUT) + +# --------------------------------------------------------------------------- +# Dismiss +# --------------------------------------------------------------------------- + +func dismiss(reason: int = GodotxToastEnums.ToastDismissReason.API): + if _is_dismissing: + return + _is_dismissing = true + if _timer: + _timer.stop() + _animate_out(reason) + +func _animate_out(reason: int): + if _tween and _tween.is_valid(): + _tween.kill() + if animation == GodotxToastEnums.ToastAnimation.NONE: + _complete_dismiss(reason) + return + _tween = create_tween() + _tween.set_ease(style.animation_easing) + _tween.set_trans(style.animation_trans) + match animation: + GodotxToastEnums.ToastAnimation.SLIDE: + _tween.tween_property(self, "position", _get_slide_out_pos(), style.animation_duration) + GodotxToastEnums.ToastAnimation.FADE: + _tween.tween_property(self, "modulate:a", 0.0, style.animation_duration) + _tween.tween_callback(_complete_dismiss.bind(reason)) + +func _complete_dismiss(reason: int): + dismissed.emit(toast_id, reason) + queue_free() + +# --------------------------------------------------------------------------- +# Animate in +# --------------------------------------------------------------------------- + +func animate_in(target_position: Vector2): + if _tween and _tween.is_valid(): + _tween.kill() + if animation == GodotxToastEnums.ToastAnimation.NONE: + position = target_position + return + match animation: + GodotxToastEnums.ToastAnimation.SLIDE: + position = _slide_in_start(target_position) + modulate.a = 1.0 + _tween = create_tween() + _tween.set_ease(style.animation_easing) + _tween.set_trans(style.animation_trans) + _tween.tween_property(self, "position", target_position, style.animation_duration) + GodotxToastEnums.ToastAnimation.FADE: + position = target_position + modulate.a = 0.0 + _tween = create_tween() + _tween.set_ease(style.animation_easing) + _tween.set_trans(style.animation_trans) + _tween.tween_property(self, "modulate:a", 1.0, style.animation_duration) + +func _slide_in_start(target: Vector2) -> Vector2: + var vp = get_viewport().get_visible_rect().size + var s = target + match origin: + GodotxToastEnums.ToastOrigin.LEFT, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.BOTTOM_LEFT: + s.x = -size.x - 50 + GodotxToastEnums.ToastOrigin.RIGHT, GodotxToastEnums.ToastOrigin.TOP_RIGHT, GodotxToastEnums.ToastOrigin.BOTTOM_RIGHT: + s.x = vp.x + 50 + GodotxToastEnums.ToastOrigin.TOP: + s.y = -size.y - 50 + _: # BOTTOM, CENTER + s.y = vp.y + 50 + return s + +func _get_slide_out_pos() -> Vector2: + var vp = get_viewport().get_visible_rect().size + var t = position + match origin: + GodotxToastEnums.ToastOrigin.LEFT, GodotxToastEnums.ToastOrigin.TOP_LEFT, GodotxToastEnums.ToastOrigin.BOTTOM_LEFT: + t.x = -size.x - 50 + GodotxToastEnums.ToastOrigin.RIGHT, GodotxToastEnums.ToastOrigin.TOP_RIGHT, GodotxToastEnums.ToastOrigin.BOTTOM_RIGHT: + t.x = vp.x + 50 + GodotxToastEnums.ToastOrigin.TOP: + t.y = -size.y - 50 + _: # BOTTOM, CENTER + t.y = vp.y + 50 + return t + +# --------------------------------------------------------------------------- +# Public API +# --------------------------------------------------------------------------- + +var _max_width: float = 0.0 + +func set_max_width(max_w: float): + _max_width = max_w + # Apply max width constraint if needed + if _max_width > 0 and size.x > _max_width: + custom_minimum_size.x = _max_width + +func update_style(new_style: GodotxToastStyle, new_ui_scale: float = 1.0): + style = new_style + _ui_scale = new_ui_scale + _apply_style() diff --git a/addons/godotx_toast/runtime/toast_view.gd.uid b/addons/godotx_toast/runtime/toast_view.gd.uid new file mode 100644 index 0000000..b3022e4 --- /dev/null +++ b/addons/godotx_toast/runtime/toast_view.gd.uid @@ -0,0 +1 @@ +uid://dkmlrbnjevdrj diff --git a/addons/log/LICENSE b/addons/log/LICENSE new file mode 100644 index 0000000..d4d4ceb --- /dev/null +++ b/addons/log/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Russell Matney + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/addons/log/color_theme_dark.tres b/addons/log/color_theme_dark.tres new file mode 100644 index 0000000..b9ec6ea --- /dev/null +++ b/addons/log/color_theme_dark.tres @@ -0,0 +1,33 @@ +[gd_resource type="Resource" script_class="LogColorTheme" load_steps=2 format=3 uid="uid://c2tfr7nw4y7ll"] + +[ext_resource type="Script" uid="uid://br8socgd1vvih" path="res://addons/log/log_color_theme.gd" id="1_6x53w"] + +[resource] +script = ExtResource("1_6x53w") +color_src_prefix = Color(0.498039, 1, 0.831373, 1) +color_addons_prefix = Color(0.803922, 0.521569, 0.247059, 1) +color_test_prefix = Color(0.678431, 1, 0.184314, 1) +color_comma = Color(1, 0.411765, 0.705882, 1) +color_ampersand = Color(1, 0.498039, 0.313726, 1) +color_pipe = Color(1, 0.498039, 0.313726, 1) +color_carrot = Color(1, 0.498039, 0.313726, 1) +colors_rainbow_delims = Array[Color]([Color(0.862745, 0.0784314, 0.235294, 1), Color(0.392157, 0.584314, 0.929412, 1), Color(1, 0.498039, 0.313726, 1), Color(1, 0.752941, 0.796078, 1), Color(0.803922, 0.521569, 0.247059, 1)]) +color_nil = Color(1, 0.498039, 0.313726, 1) +color_bool = Color(1, 0.752941, 0.796078, 1) +color_int = Color(0.392157, 0.584314, 0.929412, 1) +color_float = Color(0.392157, 0.584314, 0.929412, 1) +color_vectors = Color(0.392157, 0.584314, 0.929412, 1) +color_rects = Color(0.392157, 0.584314, 0.929412, 1) +color_class_name = Color(0.372549, 0.619608, 0.627451, 1) +color_string = Color(0.662745, 0.662745, 0.662745, 1) +color_string_name = Color(1, 0.752941, 0.796078, 1) +color_node_path = Color(1, 0.752941, 0.796078, 1) +color_type_color = Color(1, 0.752941, 0.796078, 1) +color_rid = Color(1, 0.752941, 0.796078, 1) +color_object = Color(1, 0.752941, 0.796078, 1) +color_callable = Color(1, 0.752941, 0.796078, 1) +color_signal = Color(1, 0.752941, 0.796078, 1) +color_array = Color(1, 0.752941, 0.796078, 1) +color_dictionary = Color(1, 0.752941, 0.796078, 1) +color_packed_array = Color(1, 0.752941, 0.796078, 1) +color_type_max = Color(1, 0.752941, 0.796078, 1) diff --git a/addons/log/color_theme_light.tres b/addons/log/color_theme_light.tres new file mode 100644 index 0000000..c4c0f1f --- /dev/null +++ b/addons/log/color_theme_light.tres @@ -0,0 +1,33 @@ +[gd_resource type="Resource" script_class="LogColorTheme" load_steps=2 format=3 uid="uid://biby87a3dypvn"] + +[ext_resource type="Script" uid="uid://br8socgd1vvih" path="res://addons/log/log_color_theme.gd" id="1_kcklq"] + +[resource] +script = ExtResource("1_kcklq") +color_src_prefix = Color(0, 0.545098, 0.545098, 1) +color_addons_prefix = Color(0.545098, 0, 0, 1) +color_test_prefix = Color(0, 0.392157, 0, 1) +color_comma = Color(0.862745, 0.0784314, 0.235294, 1) +color_ampersand = Color(1, 0.498039, 0.313726, 1) +color_pipe = Color(1, 0.498039, 0.313726, 1) +color_carrot = Color(1, 0.498039, 0.313726, 1) +colors_rainbow_delims = Array[Color]([Color(0.862745, 0.0784314, 0.235294, 1), Color(0, 0, 0.545098, 1), Color(0.294118, 0, 0.509804, 1), Color(0.501961, 0.501961, 0, 1), Color(0.545098, 0.270588, 0.0745098, 1)]) +color_nil = Color(1, 0.498039, 0.313726, 1) +color_bool = Color(0.545098, 0, 0, 1) +color_int = Color(0.6, 0.196078, 0.8, 1) +color_float = Color(0.6, 0.196078, 0.8, 1) +color_vectors = Color(0.392157, 0.584314, 0.929412, 1) +color_rects = Color(0.392157, 0.584314, 0.929412, 1) +color_class_name = Color(0.372549, 0.619608, 0.627451, 1) +color_string = Color(0.545098, 0, 0, 1) +color_string_name = Color(0.545098, 0, 0, 1) +color_node_path = Color(0.545098, 0, 0, 1) +color_type_color = Color(0.545098, 0, 0, 1) +color_rid = Color(0.545098, 0, 0, 1) +color_object = Color(0.545098, 0, 0, 1) +color_callable = Color(0.545098, 0, 0, 1) +color_signal = Color(0.545098, 0, 0, 1) +color_array = Color(0.545098, 0, 0, 1) +color_dictionary = Color(0.545098, 0, 0, 1) +color_packed_array = Color(0.545098, 0, 0, 1) +color_type_max = Color(0.545098, 0, 0, 1) diff --git a/addons/log/log.gd b/addons/log/log.gd new file mode 100644 index 0000000..82d1c5a --- /dev/null +++ b/addons/log/log.gd @@ -0,0 +1,780 @@ +## Log.gd - colorized pretty printing functions +## +## [code]Log.pr(...)[/code] and [code]Log.prn(...)[/code] are drop-in replacements for [code]print(...)[/code]. +## +## [br][br] +## You can also [code]Log.warn(...)[/code] or [code]Log.error(...)[/code] to both print and push_warn/push_error. +## +## [br][br] +## Custom object output is supported by implementing [code]to_pretty()[/code] on the object. +## +## [br][br] +## For objects you don't own (built-ins or addons you don't want to edit), +## there is a [code]register_type_overwrite(key, handler)[/code] helper. +## +## [br][br] +## You can find up-to-date docs and examples in the Log.gd repo and docs site: +## [br] +## - https://github.com/russmatney/log.gd +## [br] +## - https://russmatney.github.io/log.gd +## + +@tool +extends Object +class_name Log + +# helpers #################################### + +static func assoc(opts: Dictionary, key: String, val: Variant) -> Dictionary: + var _opts: Dictionary = opts.duplicate(true) + _opts[key] = val + return _opts + +# settings helpers #################################### + +static func initialize_setting(key: String, default_value: Variant, type: int, hint: int = PROPERTY_HINT_NONE, hint_string: String = "") -> void: + if not ProjectSettings.has_setting(key): + ProjectSettings.set(key, default_value) + ProjectSettings.set_initial_value(key, default_value) + ProjectSettings.add_property_info({name=key, type=type, hint=hint, hint_string=hint_string}) + +# settings keys and default #################################### + +const KEY_PREFIX: String = "log_gd/config" +static var is_config_setup: bool = false + +# TODO drop this key +const KEY_COLOR_THEME_DICT: String = "log_color_theme_dict" +const KEY_COLOR_THEME: String = "log_color_theme" +const KEY_COLOR_THEME_RESOURCE_PATH: String = "%s/color_resource_path" % KEY_PREFIX +const KEY_DISABLE_COLORS: String = "%s/disable_colors" % KEY_PREFIX +const KEY_FORCE_TERMSAFE_COLORS: String = "%s/force_termsafe_colors" % KEY_PREFIX +const KEY_MAX_ARRAY_SIZE: String = "%s/max_array_size" % KEY_PREFIX +const KEY_SKIP_KEYS: String = "%s/dictionary_skip_keys" % KEY_PREFIX +const KEY_USE_NEWLINES: String = "%s/use_newlines" % KEY_PREFIX +const KEY_NEWLINE_MAX_DEPTH: String = "%s/newline_max_depth" % KEY_PREFIX +const KEY_LOG_LEVEL: String = "%s/log_level" % KEY_PREFIX +const KEY_WARN_TODO: String = "%s/warn_todo" % KEY_PREFIX +const KEY_SHOW_LOG_LEVEL_SELECTOR: String = "%s/show_log_level_selector" % KEY_PREFIX +const KEY_SHOW_TIMESTAMPS: String = "%s/show_timestamps" % KEY_PREFIX +const KEY_TIMESTAMP_TYPE: String = "%s/timestamp_type" % KEY_PREFIX +const KEY_HUMAN_READABLE_TIMESTAMP_FORMAT: String = "%s/human_readable_timestamp_format" % KEY_PREFIX + +enum Levels { + DEBUG, + INFO, + WARN, + ERROR + } + +enum TimestampTypes { + UNIX, + TICKS_MSEC, + TICKS_USEC, + HUMAN_12HR, + HUMAN_24HR + } + +const CONFIG_DEFAULTS := { + KEY_COLOR_THEME_RESOURCE_PATH: "res://addons/log/color_theme_dark.tres", + KEY_DISABLE_COLORS: false, + KEY_FORCE_TERMSAFE_COLORS: false, + KEY_MAX_ARRAY_SIZE: 20, + KEY_SKIP_KEYS: ["layer_0/tile_data"], + KEY_USE_NEWLINES: false, + KEY_NEWLINE_MAX_DEPTH: -1, + KEY_LOG_LEVEL: Levels.INFO, + KEY_WARN_TODO: true, + KEY_SHOW_LOG_LEVEL_SELECTOR: false, + KEY_SHOW_TIMESTAMPS: false, + KEY_TIMESTAMP_TYPE: TimestampTypes.HUMAN_12HR, + KEY_HUMAN_READABLE_TIMESTAMP_FORMAT: "{hour}:{minute}:{second}", + } + +# settings setup #################################### + +static func setup_settings(opts: Dictionary = {}) -> void: + initialize_setting(KEY_COLOR_THEME_RESOURCE_PATH, CONFIG_DEFAULTS[KEY_COLOR_THEME_RESOURCE_PATH], TYPE_STRING, PROPERTY_HINT_FILE) + initialize_setting(KEY_DISABLE_COLORS, CONFIG_DEFAULTS[KEY_DISABLE_COLORS], TYPE_BOOL) + initialize_setting(KEY_FORCE_TERMSAFE_COLORS, CONFIG_DEFAULTS[KEY_FORCE_TERMSAFE_COLORS], TYPE_BOOL) + initialize_setting(KEY_MAX_ARRAY_SIZE, CONFIG_DEFAULTS[KEY_MAX_ARRAY_SIZE], TYPE_INT) + initialize_setting(KEY_SKIP_KEYS, CONFIG_DEFAULTS[KEY_SKIP_KEYS], TYPE_PACKED_STRING_ARRAY) + initialize_setting(KEY_USE_NEWLINES, CONFIG_DEFAULTS[KEY_USE_NEWLINES], TYPE_BOOL) + initialize_setting(KEY_NEWLINE_MAX_DEPTH, CONFIG_DEFAULTS[KEY_NEWLINE_MAX_DEPTH], TYPE_INT) + initialize_setting(KEY_LOG_LEVEL, CONFIG_DEFAULTS[KEY_LOG_LEVEL], TYPE_INT, PROPERTY_HINT_ENUM, "DEBUG,INFO,WARN,ERROR") + initialize_setting(KEY_WARN_TODO, CONFIG_DEFAULTS[KEY_WARN_TODO], TYPE_BOOL) + initialize_setting(KEY_SHOW_LOG_LEVEL_SELECTOR, CONFIG_DEFAULTS[KEY_SHOW_LOG_LEVEL_SELECTOR], TYPE_BOOL) + initialize_setting(KEY_SHOW_TIMESTAMPS, CONFIG_DEFAULTS[KEY_SHOW_TIMESTAMPS], TYPE_BOOL) + initialize_setting(KEY_TIMESTAMP_TYPE, CONFIG_DEFAULTS[KEY_TIMESTAMP_TYPE], TYPE_INT, PROPERTY_HINT_ENUM, "UNIX,TICKS_MSEC,TICKS_USEC,HUMAN_12HR,HUMAN_24HR") + initialize_setting(KEY_HUMAN_READABLE_TIMESTAMP_FORMAT, CONFIG_DEFAULTS[KEY_HUMAN_READABLE_TIMESTAMP_FORMAT], TYPE_STRING) + +# config setup #################################### + +static var config: Dictionary = {} +static func rebuild_config(opts: Dictionary = {}) -> void: + for key: String in CONFIG_DEFAULTS.keys(): + # Keep config set in code before to_printable() is called for the first time + var val: Variant = Log.config.get(key, ProjectSettings.get_setting(key, CONFIG_DEFAULTS[key])) + + Log.config[key] = val + + # hardcoding a resource-load b/c it seems like custom-resources can't be loaded by the project settings + # https://github.com/godotengine/godot/issues/96219 + if val != null and key == KEY_COLOR_THEME_RESOURCE_PATH: + Log.config[KEY_COLOR_THEME] = load(val) + Log.config[KEY_COLOR_THEME_DICT] = Log.config[KEY_COLOR_THEME].to_color_dict() + + var force_termsafe = get_force_termsafe_colors() + if (force_termsafe): + print("NOTE: Forcing TERM_SAFE colors from config") + set_colors_termsafe() + + Log.is_config_setup = true + +# config getters ################################################################### + +static func get_max_array_size() -> int: + return Log.config.get(KEY_MAX_ARRAY_SIZE, CONFIG_DEFAULTS[KEY_MAX_ARRAY_SIZE]) + +static func get_dictionary_skip_keys() -> Array: + return Log.config.get(KEY_SKIP_KEYS, CONFIG_DEFAULTS[KEY_SKIP_KEYS]) + +static func get_disable_colors() -> bool: + return Log.config.get(KEY_DISABLE_COLORS, CONFIG_DEFAULTS[KEY_DISABLE_COLORS]) + +static func get_force_termsafe_colors() -> bool: + return Log.config.get(KEY_FORCE_TERMSAFE_COLORS, CONFIG_DEFAULTS[KEY_FORCE_TERMSAFE_COLORS]) + +# TODO consider termsafe LogColorThemes +static var warned_about_termsafe_fallback := false +static func get_config_color_theme_dict() -> Dictionary: + var color_theme = Log.config.get(KEY_COLOR_THEME) + var color_dict = Log.config.get(KEY_COLOR_THEME_DICT) + if color_dict != null: + return color_dict + if not warned_about_termsafe_fallback: + print("Falling back to TERM_SAFE colors") + warned_about_termsafe_fallback = true + return LogColorTheme.COLORS_TERM_SAFE + +static func get_config_color_theme() -> LogColorTheme: + var color_theme = Log.config.get(KEY_COLOR_THEME) + # TODO better warnings, fallbacks + return color_theme + +static func get_use_newlines() -> bool: + return Log.config.get(KEY_USE_NEWLINES, CONFIG_DEFAULTS[KEY_USE_NEWLINES]) + +static func get_newline_max_depth() -> int: + return Log.config.get(KEY_NEWLINE_MAX_DEPTH, CONFIG_DEFAULTS[KEY_NEWLINE_MAX_DEPTH]) + +static func get_log_level() -> int: + if not Log.is_config_setup: + rebuild_config() + return Log.config.get(KEY_LOG_LEVEL, CONFIG_DEFAULTS[KEY_LOG_LEVEL]) + +static func get_warn_todo() -> int: + return Log.config.get(KEY_WARN_TODO, CONFIG_DEFAULTS[KEY_WARN_TODO]) + +static func get_show_timestamps() -> bool: + return Log.config.get(KEY_SHOW_TIMESTAMPS, CONFIG_DEFAULTS[KEY_SHOW_TIMESTAMPS]) + +static func get_timestamp_type() -> TimestampTypes: + return Log.config.get(KEY_TIMESTAMP_TYPE, CONFIG_DEFAULTS[KEY_TIMESTAMP_TYPE]) + +static func get_timestamp_format() -> String: + return Log.config.get(KEY_HUMAN_READABLE_TIMESTAMP_FORMAT, CONFIG_DEFAULTS[KEY_HUMAN_READABLE_TIMESTAMP_FORMAT]) + + +## config setters ################################################################### + +## Disable color-wrapping output. +## +## [br][br] +## Useful to declutter the output if the environment does not support colors. +## Note that some environments support only a subset of colors - you may prefer +## [code]set_colors_termsafe()[/code]. +static func disable_colors() -> void: + Log.config[KEY_DISABLE_COLORS] = true + +## Re-enable color-wrapping output. +static func enable_colors() -> void: + Log.config[KEY_DISABLE_COLORS] = false + +## Disable newlines in pretty-print output. +## +## [br][br] +## Useful if you want your log output on a single line, typically for use with +## log aggregation tools. +static func disable_newlines() -> void: + Log.config[KEY_USE_NEWLINES] = false + +## Re-enable newlines in pretty-print output. +static func enable_newlines() -> void: + Log.config[KEY_USE_NEWLINES] = true + +## Disable warning on Log.todo(). +static func disable_warn_todo() -> void: + Log.config[KEY_WARN_TODO] = false + +## Re-enable warning on Log.todo(). +static func enable_warn_todo() -> void: + Log.config[KEY_WARN_TODO] = true + +## Set the maximum depth of an object that will get its own newline. +## +## [br][br] +## Useful if you have deeply nested objects where you're primarly interested +## in easily parsing the information near the root of the object. +static func set_newline_max_depth(new_depth: int) -> void: + Log.config[KEY_NEWLINE_MAX_DEPTH] = new_depth + +## Resets the maximum object depth for newlines to the default. +static func reset_newline_max_depth() -> void: + Log.config[KEY_USE_NEWLINES] = CONFIG_DEFAULTS[KEY_NEWLINE_MAX_DEPTH] + +## Set the minimum level of logs that get printed +static func set_log_level(new_log_level: int) -> void: + Log.config[KEY_LOG_LEVEL] = new_log_level + +## Show timestamps in log lines +static func show_timestamps() -> void: + Log.config[KEY_SHOW_TIMESTAMPS] = true + +## Don't timestamps in log lines +static func hide_timestamps() -> void: + Log.config[KEY_SHOW_TIMESTAMPS] = false + +## Use the given timestamp type +static func use_timestamp_type(timestamp_type: Log.TimestampTypes) -> void: + Log.config[KEY_TIMESTAMP_TYPE] = timestamp_type + +## Use the given timestamp format +static func use_timestamp_format(timestamp_format: String) -> void: + Log.config[KEY_HUMAN_READABLE_TIMESTAMP_FORMAT] = timestamp_format + +## set color theme #################################### + +## Use the terminal safe color scheme, which should support colors in most tty-like environments. +static func set_colors_termsafe() -> void: + Log.config[KEY_COLOR_THEME_DICT] = LogColorTheme.COLORS_TERM_SAFE + +## Use prettier colors - i.e. whatever LogColorTheme is configured. +static func set_colors_pretty() -> void: + var theme_path: Variant = Log.config.get(KEY_COLOR_THEME_RESOURCE_PATH) + # TODO proper string, file, resource load check here + if theme_path != null: + Log.config[KEY_COLOR_THEME] = load(theme_path) + Log.config[KEY_COLOR_THEME_DICT] = Log.config[KEY_COLOR_THEME].to_color_dict() + else: + print("WARNING no color theme resource path to load!") + +## applying colors #################################### + +static func should_use_color(opts: Dictionary = {}) -> bool: + if OS.has_feature("ios") or OS.has_feature("web"): + # ios and web (and likely others) don't handle colors well + return false + if Log.get_disable_colors(): + return false + # supports per-print color skipping + if opts.get("disable_colors", false): + return false + return true + +static func color_wrap(s: Variant, opts: Dictionary = {}) -> String: + # TODO refactor to use the color theme directly + var colors: Dictionary = get_config_color_theme_dict() + var color_theme: LogColorTheme = get_config_color_theme() + + if not should_use_color(opts): + return str(s) + + var color: Variant = opts.get("color", "") + if color == null or (color is String and color == ""): + var s_type: Variant = opts.get("typeof", typeof(s)) + if s_type is String: + # type overwrites + color = colors.get(s_type) + elif s_type is int and s_type == TYPE_STRING: + # specific strings/punctuation + var s_trimmed: String = str(s).strip_edges() + if s_trimmed in colors: + color = colors.get(s_trimmed) + else: + # fallback string color + color = colors.get(s_type) + else: + # all other types + color = colors.get(s_type) + + if color is String and color == "" or color == null: + print("Log.gd could not determine color for object: %s type: (%s)" % [str(s), typeof(s)]) + + if color is Array: + # support rainbow delimiters + if opts.get("typeof", "") in ["dict_key"]: + # subtract 1 for dict_keys + # we the keys are 'down' a nesting level, but we want the curly + dict keys to match + color = color[(opts.get("newline_depth", 0) - 1) % len(color)] + else: + color = color[opts.get("newline_depth", 0) % len(color)] + + if color is Color: + # get the colors back to something bb_code can handle + color = color.to_html(false) + + if color_theme and color_theme.has_bg(): + var bg_color: String = color_theme.get_bg_color(opts.get("newline_depth", 0)).to_html(false) + return "[bgcolor=%s][color=%s]%s[/color][/bgcolor]" % [bg_color, color, s] + return "[color=%s]%s[/color]" % [color, s] + +## overwrites ########################################################################### + +static var type_overwrites: Dictionary = {} + +## Register a single type overwrite. +## +## [br][br] +## The key should be either obj.get_class() or typeof(var). (Note that using typeof(var) may overwrite more broadly than expected). +## +## [br][br] +## The handler is called with the object and an options dict. +## [code]func(obj): return {name=obj.name}[/code] +static func register_type_overwrite(key: String, handler: Callable) -> void: + # TODO warning on key exists? support multiple handlers for same type? + # validate the key/handler somehow? + type_overwrites[key] = handler + +## Register a dictionary of type overwrite. +## +## [br][br] +## Expects a Dictionary like [code]{obj.get_class(): func(obj): return {key=obj.get_key()}}[/code]. +## +## [br][br] +## It depends on [code]obj.get_class()[/code] then [code]typeof(obj)[/code] for the key. +## The handler is called with the object as the only argument. (e.g. [code]func(obj): return {name=obj.name}[/code]). +static func register_type_overwrites(overwrites: Dictionary) -> void: + type_overwrites.merge(overwrites, true) + +static func clear_type_overwrites() -> void: + type_overwrites = {} + +## to_pretty ########################################################################### + +## Returns the passed object as a bb-colorized string. +## +## [br][br] +## The core of Log.gd's functionality. +## +## [br][br] +## Can be useful to feed directly into a RichTextLabel. +## +static func to_pretty(msg: Variant, opts: Dictionary = {}) -> String: + var newlines: bool = opts.get("newlines", Log.get_use_newlines()) + var newline_depth: int = opts.get("newline_depth", 0) + var newline_max_depth: int = opts.get("newline_max_depth", Log.get_newline_max_depth()) + var indent_level: int = opts.get("indent_level", 0) + + if not newlines: + newline_max_depth = 0 + elif newline_max_depth == 0: + newlines = false + + # If newline_max_depth is negative, don't limit the depth + if newline_max_depth > 0 and newline_depth >= newline_max_depth: + newlines = false + + if not "newline_depth" in opts: + opts["newline_depth"] = newline_depth + + if not "indent_level" in opts: + opts["indent_level"] = indent_level + + if not is_instance_valid(msg) and typeof(msg) == TYPE_OBJECT: + return str("invalid instance: ", msg) + + if msg == null: + return Log.color_wrap(msg, opts) + + if msg is Object and (msg as Object).get_class() in type_overwrites: + var fn: Callable = type_overwrites.get((msg as Object).get_class()) + return Log.to_pretty(fn.call(msg), opts) + elif typeof(msg) in type_overwrites: + var fn: Callable = type_overwrites.get(typeof(msg)) + return Log.to_pretty(fn.call(msg), opts) + + # objects + if msg is Object and (msg as Object).has_method("to_pretty"): + # using a cast and `call.("blah")` here it's "type safe" + return Log.to_pretty((msg as Object).call("to_pretty"), opts) + if msg is Object and (msg as Object).has_method("data"): + return Log.to_pretty((msg as Object).call("data"), opts) + # DEPRECATED + if msg is Object and (msg as Object).has_method("to_printable"): + return Log.to_pretty((msg as Object).call("to_printable"), opts) + + # arrays + if msg is Array or msg is PackedStringArray: + var msg_array: Array = msg + if len(msg) > Log.get_max_array_size(): + pr("[DEBUG]: truncating large array. total:", len(msg)) + msg_array = msg_array.slice(0, Log.get_max_array_size() - 1) + if newlines: + msg_array.append("...") + + # shouldn't we be incrementing index_level here? + var tmp: String = Log.color_wrap("[ ", opts) + opts["newline_depth"] += 1 + var last: int = len(msg) - 1 + for i: int in range(len(msg)): + if newlines and last > 1: + tmp += Log.color_wrap("\n\t", opts) + tmp += Log.to_pretty(msg[i], + # duplicate here to prevent indenting-per-msg + # e.g. when printing an array of dictionaries + opts.duplicate(true)) + if i != last: + tmp += Log.color_wrap(", ", opts) + opts["newline_depth"] -= 1 + tmp += Log.color_wrap(" ]", opts) + return tmp + + # dictionary + elif msg is Dictionary: + var tmp: String = Log.color_wrap("{ ", opts) + opts["newline_depth"] += 1 + var ct: int = len(msg) + var last: Variant + if len(msg) > 0: + last = (msg as Dictionary).keys()[-1] + var indent_updated = false + for k: Variant in (msg as Dictionary).keys(): + var val: Variant + if k in Log.get_dictionary_skip_keys(): + val = "..." + else: + if not indent_updated: + indent_updated = true + opts["indent_level"] += 1 + val = Log.to_pretty(msg[k], opts) + if newlines and ct > 1: + tmp += Log.color_wrap("\n\t", opts) \ + + Log.color_wrap(range(indent_level)\ + .map(func(_i: int) -> String: return "\t")\ + .reduce(func(a: String, b: Variant) -> String: return str(a, b), ""), opts) + var key: String = Log.color_wrap('"%s"' % k, Log.assoc(opts, "typeof", "dict_key")) + tmp += "%s%s%s" % [key, Log.color_wrap(": ", opts), val] + if last and str(k) != str(last): + tmp += Log.color_wrap(", ", opts) + opts["newline_depth"] -= 1 + tmp += Log.color_wrap(" }", opts) + opts["indent_level"] -= 1 # ugh! updating the dict in-place + return tmp + + # strings + elif msg is String: + if msg == "": + return '""' + if "[color=" in msg and "[/color]" in msg: + # passes through strings that might already be colorized? + # can't remember this use-case + # perhaps should use a regex and unit tests for something more robust + return msg + return Log.color_wrap(msg, opts) + elif msg is StringName: + return str(Log.color_wrap("&", opts), '"%s"' % msg) + elif msg is NodePath: + return str(Log.color_wrap("^", opts), '"%s"' % msg) + + elif msg is Color: + # probably too opinionated, but seeing 4 floats for color is noisey + return Log.color_wrap(msg.to_html(false), Log.assoc(opts, "typeof", TYPE_COLOR)) + + # vectors + elif msg is Vector2 or msg is Vector2i: + return '%s%s%s%s%s' % [ + Log.color_wrap("(", opts), + Log.color_wrap(msg.x, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(",", opts), + Log.color_wrap(msg.y, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(")", opts), + ] + + elif msg is Vector3 or msg is Vector3i: + return '%s%s%s%s%s%s%s' % [ + Log.color_wrap("(", opts), + Log.color_wrap(msg.x, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(",", opts), + Log.color_wrap(msg.y, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(",", opts), + Log.color_wrap(msg.z, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(")", opts), + ] + elif msg is Vector4 or msg is Vector4i: + return '%s%s%s%s%s%s%s%s%s' % [ + Log.color_wrap("(", opts), + Log.color_wrap(msg.x, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(",", opts), + Log.color_wrap(msg.y, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(",", opts), + Log.color_wrap(msg.z, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(",", opts), + Log.color_wrap(msg.w, Log.assoc(opts, "typeof", "vector_value")), + Log.color_wrap(")", opts), + ] + + # packed scene + elif msg is PackedScene: + var msg_ps: PackedScene = msg + if msg_ps.resource_path != "": + return str(Log.color_wrap("PackedScene:", opts), '%s' % msg_ps.resource_path.get_file()) + elif msg_ps.get_script() != null and msg_ps.get_script().resource_path != "": + var path: String = msg_ps.get_script().resource_path + return Log.color_wrap(path.get_file(), Log.assoc(opts, "typeof", "class_name")) + else: + return Log.color_wrap(msg_ps, opts) + + # resource + elif msg is Resource: + var msg_res: Resource = msg + if msg_res.get_script() != null and msg_res.get_script().resource_path != "": + var path: String = msg_res.get_script().resource_path + return Log.color_wrap(path.get_file(), Log.assoc(opts, "typeof", "class_name")) + elif msg_res.resource_path != "": + var path: String = msg_res.resource_path + return str(Log.color_wrap("Resource:", opts), '%s' % path.get_file()) + else: + return Log.color_wrap(msg_res, opts) + + # refcounted + elif msg is RefCounted: + var msg_ref: RefCounted = msg + if msg_ref.get_script() != null and msg_ref.get_script().resource_path != "": + var path: String = msg_ref.get_script().resource_path + return Log.color_wrap(path.get_file(), Log.assoc(opts, "typeof", "class_name")) + else: + return Log.color_wrap(msg_ref.get_class(), Log.assoc(opts, "typeof", "class_name")) + + # fallback to primitive-type lookup + else: + return Log.color_wrap(msg, opts) + +## to_printable ########################################################################### + +static func log_prefix(stack: Array) -> String: + if len(stack) > 1: + var call_site: Dictionary = stack[1] + var call_site_source: String = call_site.get("source", "") + var basename: String = call_site_source.get_file().get_basename() + var line_num: String = str(call_site.get("line", 0)) + if call_site_source.match("*/test/*"): + return "{" + basename + ":" + line_num + "}: " + elif call_site_source.match("*/addons/*"): + return "<" + basename + ":" + line_num + ">: " + else: + return "[" + basename + ":" + line_num + "]: " + return "" + +static func to_printable(msgs: Array, opts: Dictionary = {}) -> String: + if not Log.is_config_setup: + rebuild_config() + + if not msgs is Array: + msgs = [msgs] + var stack: Array = opts.get("stack", []) + var pretty: bool = opts.get("pretty", true) + var m: String = "" + if get_show_timestamps(): + m = "[%s]" % Log.timestamp() + if len(stack) > 0: + var prefix: String = Log.log_prefix(stack) + var prefix_type: String + if prefix != null and prefix[0] == "[": + prefix_type = "SRC" + elif prefix != null and prefix[0] == "{": + prefix_type = "TEST" + elif prefix != null and prefix[0] == "<": + prefix_type = "ADDONS" + if pretty: + m += Log.color_wrap(prefix, Log.assoc(opts, "typeof", prefix_type)) + else: + m += prefix + for msg: Variant in msgs: + # add a space between msgs + if pretty: + m += "%s " % Log.to_pretty(msg, opts) + else: + m += "%s " % str(msg) + return m.trim_suffix(" ") + +static func timestamp() -> String: + match Log.get_timestamp_type(): + Log.TimestampTypes.UNIX: + return "%d" % Time.get_unix_time_from_system() + Log.TimestampTypes.TICKS_MSEC: + return "%d" % Time.get_ticks_msec() + Log.TimestampTypes.TICKS_USEC: + return "%d" % Time.get_ticks_usec() + Log.TimestampTypes.HUMAN_12HR: + var time: Dictionary = Time.get_datetime_dict_from_system() + var hour: int = time.hour % 12 + if hour == 0: + hour = 12 + var meridiem: String = "AM" if time.hour < 12 else "PM" + return Log.get_timestamp_format().format({ + "year": time.year, + "month": "%02d" % time.month, + "day": "%02d" % time.day, + "hour": hour, + "minute": "%02d" % time.minute, + "second": "%02d" % time.second, + "meridiem": meridiem, + "dst": time.dst + }) + Log.TimestampTypes.HUMAN_24HR: + var time: Dictionary = Time.get_datetime_dict_from_system() + return Log.get_timestamp_format().format({ + "year": time.year, + "month": "%02d" % time.month, + "day": "%02d" % time.day, + "hour": "%02d" % time.hour, + "minute": "%02d" % time.minute, + "second": "%02d" % time.second, + "dst": time.dst + }) + return "%d" % Time.get_unix_time_from_system() + +## public print fns ########################################################################### + +static func is_not_default(v: Variant) -> bool: + return not v is String or (v is String and v != "ZZZDEF") + +## Pretty-print the passed arguments in a single line. +static func pr(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var m: String = Log.to_printable(msgs, {stack=get_stack()}) + print_rich(m) + +## Pretty-print the passed arguments, expanding dictionaries and arrays with a newline and indentation. +static func prn(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var m: String = Log.to_printable(msgs, {stack=get_stack(), newlines=true, newline_max_depth=1}) + print_rich(m) + +## Pretty-print the passed arguments, expanding dictionaries and arrays with two newlines and indentation. +static func prnn(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var m: String = Log.to_printable(msgs, {stack=get_stack(), newlines=true, newline_max_depth=2}) + print_rich(m) + +## Pretty-print the passed arguments, expanding dictionaries and arrays with three newlines and indentation. +static func prnnn(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var m: String = Log.to_printable(msgs, {stack=get_stack(), newlines=true, newline_max_depth=3}) + print_rich(m) + +## Pretty-print the passed arguments in a single line. +static func log(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var m: String = Log.to_printable(msgs, {stack=get_stack()}) + print_rich(m) + +## Pretty-print the passed arguments in a single line. +static func debug(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + if get_log_level() > Log.Levels.DEBUG: + return + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + msgs.push_front("[DEBUG]") + var m: String = Log.to_printable(msgs, {stack=get_stack()}) + print_rich(m) + +## Pretty-print the passed arguments in a single line. +static func info(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + if get_log_level() > Log.Levels.INFO: + return + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + msgs.push_front("[INFO]") + var m: String = Log.to_printable(msgs, {stack=get_stack()}) + print_rich(m) + +## Like [code]Log.pr()[/code], but also calls push_warning() with the pretty string. +static func warn(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + if get_log_level() > Log.Levels.WARN: + return + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var rich_msgs: Array = msgs.duplicate() + rich_msgs.push_front("[color=yellow][WARN][/color]") + print_rich(Log.to_printable(rich_msgs, {stack=get_stack()})) + # skip the 'color' features in warnings to keep them readable in the debugger + var m: String = Log.to_printable(msgs, {stack=get_stack(), disable_colors=true}) + push_warning(m) + +## Like [code]Log.pr()[/code], but prepends a "[TODO]" and calls push_warning() with the pretty string. +static func todo(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + if get_warn_todo() and get_log_level() > Log.Levels.WARN: + return + elif not get_warn_todo() and get_log_level() > Log.Levels.INFO: + return + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + msgs.push_front("[TODO]") + var rich_msgs: Array = msgs.duplicate() + if get_warn_todo(): + rich_msgs.push_front("[color=yellow][WARN][/color]") + print_rich(Log.to_printable(rich_msgs, {stack=get_stack()})) + if get_warn_todo(): + var m: String = Log.to_printable(msgs, {stack=get_stack(), disable_colors=true}) + push_warning(m) + +## Like [code]Log.pr()[/code], but also calls push_error() with the pretty string. +static func err(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var rich_msgs: Array = msgs.duplicate() + rich_msgs.push_front("[color=red][ERR][/color]") + print_rich(Log.to_printable(rich_msgs, {stack=get_stack()})) + # skip the 'color' features in errors to keep them readable in the debugger + var m: String = Log.to_printable(msgs, {stack=get_stack(), disable_colors=true}) + push_error(m) + +## Like [code]Log.pr()[/code], but also calls push_error() with the pretty string. +static func error(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var rich_msgs: Array = msgs.duplicate() + rich_msgs.push_front("[color=red][ERR][/color]") + print_rich(Log.to_printable(rich_msgs, {stack=get_stack()})) + # skip the 'color' features in errors to keep them readable in the debugger + var m: String = Log.to_printable(msgs, {stack=get_stack(), disable_colors=true}) + push_error(m) + +static func blank() -> void: + print() + + +## Helper that will both print() and print_rich() the enriched string +static func _internal_debug(msg: Variant, msg2: Variant = "ZZZDEF", msg3: Variant = "ZZZDEF", msg4: Variant = "ZZZDEF", msg5: Variant = "ZZZDEF", msg6: Variant = "ZZZDEF", msg7: Variant = "ZZZDEF") -> void: + var msgs: Array = [msg, msg2, msg3, msg4, msg5, msg6, msg7] + msgs = msgs.filter(Log.is_not_default) + var m: String = Log.to_printable(msgs, {stack=get_stack()}) + print("_internal_debug: ", m) + print_rich(m) + + +## DEPRECATED +static func merge_theme_overwrites(_opts = {}) -> void: + pass + +## DEPRECATED +static func clear_theme_overwrites() -> void: + pass diff --git a/addons/log/log.gd.uid b/addons/log/log.gd.uid new file mode 100644 index 0000000..127bb42 --- /dev/null +++ b/addons/log/log.gd.uid @@ -0,0 +1 @@ +uid://bjhtrex267w1y diff --git a/addons/log/log_color_theme.gd b/addons/log/log_color_theme.gd new file mode 100644 index 0000000..c38c966 --- /dev/null +++ b/addons/log/log_color_theme.gd @@ -0,0 +1,225 @@ +## LogColorTheme - Bring Your Own Color Theme to Log.gd! +## [br][br] +## Create a new resource of this type, and assign this via the Project Settings. +## [br][br] +## Be sure to enable Log.gd via Project > Plugins to see this type in the editor! +## +@tool +extends Resource +class_name LogColorTheme + +## cycles ######################################## + +@export var bg_colors: Array[Color] = [] + +@export var colors_rainbow_delims: Array[Color] = ["crimson", "cornflower_blue", "coral", "pink", "peru"] + +## delimiters ######################################## + +@export var color_comma: Color = "crimson" +@export var color_ampersand: Color = "coral" +@export var color_pipe: Color = "coral" +@export var color_carrot: Color = "coral" + +# @export var colors_dict_keys: Array[Color] = ["coral", "cadet_blue", "pink", "peru"] + +## prefixes ######################################## + +@export var color_src_prefix: Color = "aquamarine" +@export var color_addons_prefix: Color = "peru" +@export var color_test_prefix: Color = "green_yellow" + +## types ############################################ + +@export var color_nil: Color = "coral" +@export var color_bool: Color = "pink" +@export var color_int: Color = "cornflower_blue" +@export var color_float: Color = "cornflower_blue" + +@export var color_vectors: Color = "cornflower_blue" +@export var color_rects: Color = "cornflower_blue" + +@export var color_class_name: Color = "cadet_blue" +@export var color_string: Color = "dark_gray" +@export var color_string_name: Color = "pink" +@export var color_node_path: Color = "pink" + +@export var color_type_color: Color = "pink" +@export var color_rid: Color = "pink" +@export var color_object: Color = "pink" +@export var color_callable: Color = "pink" +@export var color_signal: Color = "pink" + +@export var color_array: Color = "pink" +@export var color_dictionary: Color = "pink" +@export var color_packed_array: Color = "pink" +@export var color_type_max: Color = "pink" + +## to_color_dict ############################################ + +func to_color_dict() -> Dictionary: + var color_dict = {} + + color_dict["SRC"] = color_src_prefix + color_dict["ADDONS"] = color_addons_prefix + color_dict["TEST"] = color_test_prefix + + color_dict["|"] = color_pipe + color_dict["&"] = color_ampersand + color_dict["^"] = color_carrot + + # consider rainbow for commas too + # color_dict[","] = colors_rainbow_delims + color_dict[","] = color_comma + + color_dict["("] = colors_rainbow_delims + color_dict[")"] = colors_rainbow_delims + color_dict["["] = colors_rainbow_delims + color_dict["]"] = colors_rainbow_delims + color_dict["{"] = colors_rainbow_delims + color_dict["}"] = colors_rainbow_delims + color_dict["<"] = colors_rainbow_delims + color_dict[">"] = colors_rainbow_delims + + color_dict["dict_key"] = colors_rainbow_delims + color_dict["vector_value"] = color_float + color_dict["class_name"] = color_class_name + + color_dict[TYPE_NIL] = color_nil + color_dict[TYPE_BOOL] = color_bool + color_dict[TYPE_INT] = color_int + color_dict[TYPE_FLOAT] = color_float + + color_dict[TYPE_VECTOR2] = color_vectors + color_dict[TYPE_VECTOR2I] = color_vectors + color_dict[TYPE_RECT2] = color_rects + color_dict[TYPE_RECT2I] = color_rects + color_dict[TYPE_VECTOR3] = color_vectors + color_dict[TYPE_VECTOR3I] = color_vectors + color_dict[TYPE_TRANSFORM2D] = color_rects + color_dict[TYPE_VECTOR4] = color_vectors + color_dict[TYPE_VECTOR4I] = color_vectors + color_dict[TYPE_PLANE] = color_rects + color_dict[TYPE_QUATERNION] = color_rects + color_dict[TYPE_AABB] = color_rects + color_dict[TYPE_BASIS] = color_rects + color_dict[TYPE_TRANSFORM3D] = color_rects + color_dict[TYPE_PROJECTION] = color_rects + + color_dict[TYPE_STRING] = color_string + color_dict[TYPE_STRING_NAME] = color_string_name + color_dict[TYPE_NODE_PATH] = color_node_path + + color_dict[TYPE_COLOR] = color_type_color + color_dict[TYPE_RID] = color_rid + color_dict[TYPE_OBJECT] = color_object + color_dict[TYPE_CALLABLE] = color_callable + color_dict[TYPE_SIGNAL] = color_signal + + # Do these ever get through if we're walking these ourselves? + color_dict[TYPE_DICTIONARY] = color_dictionary + color_dict[TYPE_ARRAY] = color_array + + # Maybe want a hint/label before array openers? + color_dict[TYPE_PACKED_BYTE_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_INT32_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_INT64_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_FLOAT32_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_FLOAT64_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_STRING_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_VECTOR2_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_VECTOR3_ARRAY] = color_packed_array + color_dict[TYPE_PACKED_COLOR_ARRAY] = color_packed_array + + color_dict[TYPE_MAX] = color_type_max + + + return color_dict + +## bg color + +func has_bg() -> bool: + if bg_colors == null: + return false + return len(bg_colors) > 0 + +func get_bg_color(i: int = 0) -> Color: + return bg_colors[i % len(bg_colors)] + +### static term safe helpers + +# terminal safe colors: +# - black +# - red +# - green +# - yellow +# - blue +# - magenta +# - pink +# - purple +# - cyan +# - white +# - orange +# - gray + +static var TERMSAFE_RAINBOW: Array = ["red", "blue", "green", "pink", "orange"] + +static var COLORS_TERM_SAFE: Dictionary = { + "SRC": "cyan", + "ADDONS": "red", + "TEST": "green", + ",": "red", + "(": TERMSAFE_RAINBOW, + ")": TERMSAFE_RAINBOW, + "[": TERMSAFE_RAINBOW, + "]": TERMSAFE_RAINBOW, + "{": TERMSAFE_RAINBOW, + "}": TERMSAFE_RAINBOW, + "<": TERMSAFE_RAINBOW, + ">": TERMSAFE_RAINBOW, + "|": TERMSAFE_RAINBOW, + "&": "orange", + "^": "orange", + "dict_key": TERMSAFE_RAINBOW, + "vector_value": "green", + "class_name": "magenta", + TYPE_NIL: "pink", + TYPE_BOOL: "pink", + TYPE_INT: "green", + TYPE_FLOAT: "green", + TYPE_STRING: "pink", + TYPE_VECTOR2: "green", + TYPE_VECTOR2I: "green", + TYPE_RECT2: "green", + TYPE_RECT2I: "green", + TYPE_VECTOR3: "green", + TYPE_VECTOR3I: "green", + TYPE_TRANSFORM2D: "pink", + TYPE_VECTOR4: "green", + TYPE_VECTOR4I: "green", + TYPE_PLANE: "pink", + TYPE_QUATERNION: "pink", + TYPE_AABB: "pink", + TYPE_BASIS: "pink", + TYPE_TRANSFORM3D: "pink", + TYPE_PROJECTION: "pink", + TYPE_COLOR: "pink", + TYPE_STRING_NAME: "pink", + TYPE_NODE_PATH: "pink", + TYPE_RID: "pink", + TYPE_OBJECT: "pink", + TYPE_CALLABLE: "pink", + TYPE_SIGNAL: "pink", + TYPE_DICTIONARY: "pink", + TYPE_ARRAY: "pink", + TYPE_PACKED_BYTE_ARRAY: "pink", + TYPE_PACKED_INT32_ARRAY: "pink", + TYPE_PACKED_INT64_ARRAY: "pink", + TYPE_PACKED_FLOAT32_ARRAY: "pink", + TYPE_PACKED_FLOAT64_ARRAY: "pink", + TYPE_PACKED_STRING_ARRAY: "pink", + TYPE_PACKED_VECTOR2_ARRAY: "pink", + TYPE_PACKED_VECTOR3_ARRAY: "pink", + TYPE_PACKED_COLOR_ARRAY: "pink", + TYPE_MAX: "pink", + } diff --git a/addons/log/log_color_theme.gd.uid b/addons/log/log_color_theme.gd.uid new file mode 100644 index 0000000..184fe91 --- /dev/null +++ b/addons/log/log_color_theme.gd.uid @@ -0,0 +1 @@ +uid://br8socgd1vvih diff --git a/addons/log/plugin.cfg b/addons/log/plugin.cfg new file mode 100644 index 0000000..be27a74 --- /dev/null +++ b/addons/log/plugin.cfg @@ -0,0 +1,14 @@ +[plugin] + +name="Log.gd" +description="A pretty-printing debug logger. + +Log.pr(\"some str\", some_object) + +- Colorizes printed data based on datatype +- Recurses through nested data structures (Arrays and Dictionaries) +- Prefixes logs with the callsite's source file and line_number +" +author="Russell Matney" +version="v0.2.2" +script="plugin.gd" diff --git a/addons/log/plugin.gd b/addons/log/plugin.gd new file mode 100644 index 0000000..f0c5a09 --- /dev/null +++ b/addons/log/plugin.gd @@ -0,0 +1,43 @@ +@tool +extends EditorPlugin + + +var override_log_level_option_button: OptionButton = OptionButton.new() + +var icon_debug: Texture2D = EditorInterface.get_editor_theme().get_icon("Debug", "EditorIcons") +var icon_info: Texture2D = EditorInterface.get_editor_theme().get_icon("NodeInfo", "EditorIcons") +var icon_warn: Texture2D = EditorInterface.get_editor_theme().get_icon("NodeWarning", "EditorIcons") +var icon_err: Texture2D = EditorInterface.get_editor_theme().get_icon("StatusError", "EditorIcons") + + +func _enter_tree() -> void: + override_log_level_option_button.visible = ProjectSettings.get_setting("log_gd/config/show_log_level_selector", false) + override_log_level_option_button.add_icon_item(icon_debug, "DEBUG") + override_log_level_option_button.add_icon_item(icon_info, "INFO") + override_log_level_option_button.add_icon_item(icon_warn, "WARN") + override_log_level_option_button.add_icon_item(icon_err, "ERROR") + override_log_level_option_button.select(Log.get_log_level()) + override_log_level_option_button.item_selected.connect(override_log_level) + add_control_to_container(CONTAINER_TOOLBAR, override_log_level_option_button) + override_log_level_option_button.get_parent().move_child(override_log_level_option_button, override_log_level_option_button.get_index() - 2) + + Log.setup_settings() + Log.rebuild_config() + # TODO only run if some log-specific setting has changed + ProjectSettings.settings_changed.connect(on_settings_changed) + + +func _exit_tree() -> void: + remove_control_from_container(CONTAINER_TOOLBAR, override_log_level_option_button) + + +func on_settings_changed() -> void: + override_log_level_option_button.select(ProjectSettings.get_setting("log_gd/config/log_level")) + override_log_level_option_button.visible = ProjectSettings.get_setting("log_gd/config/show_log_level_selector") + Log.rebuild_config() + + +func override_log_level(value: Log.Levels) -> void: + Log.set_log_level(value) + ProjectSettings.set_setting("log_gd/config/log_level", value) + ProjectSettings.save() diff --git a/addons/log/plugin.gd.uid b/addons/log/plugin.gd.uid new file mode 100644 index 0000000..02aa551 --- /dev/null +++ b/addons/log/plugin.gd.uid @@ -0,0 +1 @@ +uid://dc3akmw7hy6ok diff --git a/addons/native_video/INSTALLATION.ru.md b/addons/native_video/INSTALLATION.ru.md new file mode 100644 index 0000000..b276be2 --- /dev/null +++ b/addons/native_video/INSTALLATION.ru.md @@ -0,0 +1,27 @@ +# Установка Native Video + +Пакет предназначен для Godot 4.6+ на Windows x86_64 и GNU/Linux x86_64. + +1. Распакуйте архив в корень проекта Godot. В результате файл расширения + должен находиться по пути `res://addons/native_video/native_video.gdextension`. +2. Полностью перезапустите редактор Godot. +3. Используйте `NativeVideoStream` через обычный `VideoStreamPlayer`. + +В Windows дополнительных мультимедийных пакетов не требуется: используется +Media Foundation. Сборка проверена в Godot 4.7.1 Mono с рендерером Vulkan. + +В Linux используются динамические системные библиотеки GStreamer 1.x. Для +Debian/Ubuntu установите runtime-компоненты: + +```bash +sudo apt install libgstreamer1.0-0 libgstreamer-plugins-base1.0-0 \ + gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ + gstreamer1.0-plugins-bad gstreamer1.0-libav gstreamer1.0-vaapi +``` + +Linux-сборка рассчитана на glibc 2.36+ и Vulkan (Forward+ или Mobile). +Аппаратный декодер обязателен по умолчанию. Если он недоступен, расширение +выводит понятную ошибку. Явно разрешить программный fallback для диагностики +можно переменной окружения `GODOT_NATIVE_VIDEO_ALLOW_SOFTWARE=1`. + +Подробности о кодеках, драйверах и диагностике находятся в `README.md`. diff --git a/addons/native_video/LICENSE b/addons/native_video/LICENSE new file mode 100644 index 0000000..29c739e --- /dev/null +++ b/addons/native_video/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Clay Tercek + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/addons/native_video/README.md b/addons/native_video/README.md new file mode 100644 index 0000000..fac27f3 --- /dev/null +++ b/addons/native_video/README.md @@ -0,0 +1,417 @@ +# Native Video for Godot + +Hardware-accelerated MP4/MOV video playback (H.264/HEVC) for Godot 4 on +macOS, Windows, and Linux, using the platform media stack as a **hardware +decoder only** — never in player mode — and presenting decoded frames to the +GPU through either zero-copy import or an explicit, counted CPU-copy path. +Drop-in compatible with Godot's `VideoStreamPlayer`. + +## Architecture + +The extension is built around a Godot-independent **core** that drives the +OS media framework in Decoder mode: `AVAssetReader` on macOS, a synchronous +`IMFSourceReader` on Windows. Either way, decode itself runs on a bounded +shared worker pool, not one thread per video; on Windows, COM is confined to +a single dedicated MTA (multi-threaded apartment) executor thread the +backend owns for the life of the open media, since Godot's own main thread +runs in an STA that Media Foundation object creation can't use directly. +The core owns the master clock, the frame queue, sync, and decode-ahead, so +nothing implicit in the OS framework owns timing. + +On macOS, frames reach the GPU with no CPU copy: the hardware-decoded NV12 +surface is imported via `RenderingDevice.texture_create_from_extension` as a +`Texture2DRD` and converted NV12→RGB in a single Metal compute pass into an +engine-owned texture returned from `VideoStreamPlayback._get_texture()`. +Godot never samples the decoder surface directly. On Windows the same +zero-copy shape is available when Godot runs its D3D12 rendering driver — +see [Windows present path](#windows-present-path) below for the one case +where it falls back to a CPU copy instead. + +Highlights: + +- **Decoder mode, engine-owned clock** — audio-master sync with a monotonic + fallback for silent clips; drop-late / hold-early present policy recovers + from decode hiccups without permanent drift. +- **Explicit present pipelines** — zero-copy on macOS and Windows D3D12; + counted, bounded CPU-copy on Windows Vulkan and the initial Linux Vulkan + backend. +- **Hardware decode via the OS** — AVFoundation on macOS, Media Foundation + on Windows, GStreamer with VA-API/NVDEC on Linux; low CPU and battery, no + bundled codec libraries. +- **Adaptive scrubbing** — keyframe-only while dragging fast, exact frame on + settle. +- **Shared decode-worker pool** — many videos in one scene without a thread + per video; per-stream frame order preserved. + +## Requirements + +- **macOS** (Apple Silicon or Intel; the extension links AVFoundation, + CoreMedia, CoreVideo, and Metal directly), **Windows** (the extension links + Media Foundation and D3D11/D3D12 directly), or **x86_64 GNU/Linux** with + GStreamer 1.22+ and the appropriate hardware decoder plugin. +- **Godot 4.6+**, **Forward+ or Mobile renderer** (the RenderingDevice + renderers). The Compatibility/OpenGL renderer is not supported on any + platform — there is no OpenGL texture presentation path. +- **Zig 0.16.0** to build from source (see [mise.toml](mise.toml)). Other + Zig versions are not supported: the extension is built against + [gdzig](https://github.com/gdzig/gdzig), a pre-1.0 binding generator + pinned to a specific commit and Zig version. + +## Releases + +Each GitHub Release attaches a `native_video-.zip` containing an +`addons/native_video/` folder — a self-contained Godot addon: drop it into +a project's `addons/` directory and Godot picks up `native_video.gdextension` +automatically. It bundles: + +| Platform | Arch | Files | +| --- | --- | --- | +| macOS | universal (arm64 + x86_64, via `lipo`) | `libnative_video.macos.debug.dylib`, `libnative_video.macos.release.dylib` | +| Windows | x86_64 | `native_video.windows.debug.x86_64.dll`, `native_video.windows.release.x86_64.dll` | +| Windows | x86 (32-bit) | `native_video.windows.debug.x86_32.dll`, `native_video.windows.release.x86_32.dll` | +| Windows | arm64 | `native_video.windows.debug.arm64.dll`, `native_video.windows.release.arm64.dll` | +| Linux | x86_64 | `libnative_video.linux.debug.x86_64.so`, `libnative_video.linux.release.x86_64.so` | + +Both a debug and a release binary ship for every platform/arch, matching +Godot's `template_debug`/`template_release` export split — the `.gdextension` +routes each automatically based on how the exported project was built. +Debug binaries are built with `-Doptimize=ReleaseSafe` (safety checks kept +in, unstripped); release binaries with `-Doptimize=ReleaseFast` (stripped). + +**iOS** builds and links (produces a valid iOS Mach-O `dylib`), but is not +shipped in releases: Godot's iOS export conventionally expects a static +library / `.xcframework` rather than a plain dylib, and only link-time (not +on-device runtime) has been verified. Follow-up work; not currently +tracked for a specific release. + +## Windows present path + +Windows can run Godot's Vulkan or D3D12 `RenderingDevice` driver, and this +build links two import paths that hand decoded frames to Godot. The choice +is made once, automatically, at startup, from the active RD driver name and +the running Godot version — never a build-time variant, never a +try-and-fail probe: + +| Renderer driver | Import path | Zero-copy | Notes | +| --- | --- | --- | --- | +| `d3d12` | D3D12 shared-handle import | Yes | Shared NT handles + a shared D3D11/D3D12 fence hand the decoder's D3D11 texture to Godot's D3D12 device; a plane-split compute pass splits NV12/P010 into luma/chroma views. The selection code requires Godot 4.5+ for this path (`texture_create_from_extension` isn't implemented for the D3D12 driver before that); this extension's Godot 4.6+ floor already clears that bar. | +| `vulkan` (stock) or anything else | CPU-copy fallback | No | A zero-copy Vulkan path (DXGI shared handles into `VK_KHR_external_memory_win32`) is not built here — it was hard-disabled upstream even before this Zig port, because Godot's `texture_create_from_extension` mis-binds NV12 plane aspects on the Vulkan driver. Adds one GPU→CPU readback per frame before the texture reaches Godot. | + +External absolute drive paths are opened in place. On Windows, `C:\...` and +`C:/...` inputs are normalized to a UTF-16 `file:///C:/...` URI without +percent-encoding Unicode or spaces; no copy, link, or ASCII alias is created. + +If the D3D12 path is selected but fails to come up — no D3D12 device to +bind, or the shared handles can't be opened across adapters — the extension +degrades to the CPU-copy path automatically, once, and stays there for the +rest of that playback session; it never retries the zero-copy path per +frame. Call `get_cpu_copy_count()` on a playback instance to see how many +frames took the CPU-copy path this session (always 0 on macOS, since Metal +import is always zero-copy there). + +**Recommendation:** run Godot with the D3D12 rendering driver for zero-copy +present. Stock Vulkan still gets full hardware decode, just with a per-frame +GPU→CPU readback added before present. + +## Linux backend (GStreamer) + +Linux uses GStreamer as a demux/decoder graph with bounded, unsynchronised +`appsink` outputs. GStreamer never renders video or audio and is not the master +clock: the existing Zig core continues to own scheduling, decode-ahead, A/V +sync, seeking and frame selection. Video and audio use independent graphs so a +mid-stream audio-track change can seek audio without disturbing video. + +The initial production path targets x86_64 Linux, Godot's Vulkan +RenderingDevice (Forward+ or Mobile), H.264/HEVC in MP4/MOV/M4V, and NV12/P010 +decoder output. Decoded system-memory planes are copied into two reused staging +buffers and uploaded to Godot textures. This is an explicit, bounded CPU-copy +presenter; every presented frame increments `get_cpu_copy_count()`. DMA-BUF +import is not yet enabled because Godot's public RenderingDevice extension API +does not expose enough Vulkan image-import synchronization to make modifier and +fence handling portable. + +Distributed x86_64 Linux binaries use Zig's architecture baseline (SSE2) and +do not require AVX, AVX2, or AVX-512. Release CI disassembles both `.so` files +and rejects non-baseline vector instructions, preventing a build-host CPU from +silently becoming a deployment requirement. + +Development packages (Debian 13 package names): + +```bash +sudo apt install pkg-config build-essential libgstreamer1.0-dev \ + libgstreamer-plugins-base1.0-dev +``` + +Runtime packages for the ordinary open-source desktop stack: + +```bash +sudo apt install gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ + gstreamer1.0-plugins-bad gstreamer1.0-libav gstreamer1.0-tools \ + gstreamer1.0-vaapi +``` + +- Intel and AMD: a working VA-API driver plus the GStreamer `va`/VA-API + decoder plugin is required. Verify it with `gst-inspect-1.0 vah264dec` or + `gst-inspect-1.0 vah265dec`. +- NVIDIA: install the distribution's GStreamer NVDEC/nvcodec plugin matching + the proprietary driver. Availability and package names vary by distribution. +- Debian 13 is the verified build baseline. Ubuntu 24.04 and newer are + supported when they provide GStreamer 1.22+ and the same plugin/API set. +- Wayland and X11 do not enter the decoder graph; each still needs separate + Vulkan/driver validation. Compatibility/OpenGL remains unsupported. + +The selected decoder, negotiated pixel format, presenter, and fallback reason +are reported in Godot diagnostics. Software decoding is never selected +silently: if GStreamer chooses `avdec_h264`/`avdec_h265`, opening fails. For +diagnostics or unsupported machines it can be explicitly enabled with +`GODOT_NATIVE_VIDEO_ALLOW_SOFTWARE=1`; the fallback is then logged as a warning +and is not advertised as hardware acceleration. + +Before deployment, collect a path-free capability report on the target Linux +machine. The strict form exits with code 2 when no supported hardware decoder +factory is visible: + +```bash +bash tools/linux_diagnostics.sh +bash tools/linux_diagnostics.sh --require-hardware +``` + +Run it independently under Wayland and X11 when both sessions are supported by +the product. A complete hardware qualification records the session type, +GPU/driver, selected GStreamer factory, Godot renderer, H.264/HEVC result, +audio result, seek result, lifecycle stress result, and CPU-copy count. + +The extension dynamically links GStreamer under its LGPL license; GStreamer, +codec plugins and GPU drivers are not redistributed by this repository. A +distributor must separately audit the licenses of the exact runtime plugins it +ships (notably distro-provided FFmpeg/libav plugin builds). + +## Runtime source switching + +External MP4/MOV/M4V sources follow the normal `VideoStreamPlayer` lifecycle on +Godot 4.7.x. `stop()` synchronously cancels and joins any in-flight decode +slice, pauses the native video/audio pipeline, drains queued audio and video, +resets the source to position 0, and detaches the displayed frame. Calling it +more than once is safe. A later `play()` resumes the same source from 0. + +Setting `stream = null`, assigning a different stream, freeing the player with +`queue_free()`, and replacing a scene while playback is active are supported. +Reassigning a stream resource returned from Godot's resource cache is also +safe, including when its 64-bit ObjectID has the high bit set. +Destruction first retires presented frame handles, then cancels the decoder, +waits for its worker, detaches native callbacks/readers, and releases each +backend handle exactly once. No plugin-side audio worker or audio-bus reference +survives disposal. The process-wide bounded scheduler threads remain idle for +reuse; they do not retain a disposed stream or decoder. + +The lifecycle regression harness accepts two external paths and performs 50 +stop/unbind/rebind/replay cycles, including a second simultaneous decoder, +active-player deletion and real `SceneTree.change_scene_to_packed()` replacement: + +```bash +godot --path project --script res://lifecycle_stress.gd -- /path/a.mp4 /path/b.mp4 +zig build lifecycle-smoke -- /path/a.mp4 /path/b.mp4 --cycles=50 +``` + +On Windows, quote paths containing spaces. Headless runs validate decoder, +audio, worker and ownership teardown but cannot validate texture presentation; +use Forward+ or Mobile for the full presentation path. The only intentional +long-lived native objects are the bounded shared scheduler threads described +above. + +## Known limitations + +- **Headless mode (`--headless`)**: presentation is disabled because there + is no RenderingDevice. Decode, audio mixing, the master clock, and + playback state machines keep running normally, and end-of-stream is + reached. No texture output is available. +- **Compatibility/OpenGL renderer**: not supported on any platform — no + CPU present path. +- **Linux DMA-BUF zero-copy**: not available in the initial Linux backend; + Vulkan presentation uses the counted CPU-copy upload described above. +- **Vulkan zero-copy on Windows**: not available. A DXGI-shared-handle path + into Vulkan was hard-disabled upstream (a Godot `texture_create_from_extension` + bug mis-binds NV12 plane aspects on the Vulkan driver) and isn't built into + this extension, so Vulkan on Windows always takes the CPU-copy fallback + described above. +- **HEVC on Windows** depends on a decoder MFT being registered on the + machine (typically the "HEVC Video Extensions" package) — not present on + every Windows installation. +- **Single precision only (prebuilt binaries)**: the released libraries are + built for the standard single-precision Godot. They will not load into a + double-precision (`precision=double`) Godot build — the two disagree on the + in-memory layout of core types. Double-precision users build from source + with `-Dprecision=double` (see [Building from source](#building-from-source)). + +## Diagnostics + +Every log line the extension emits — from the main thread or a decode +worker, on either backend — is mirrored to Godot's own reporting surface as +well as stderr: errors and warnings show up in the editor's Output panel +(`push_error` / `push_warning`), not just a console window, and info/debug +lines print there too. A failed `load()` (bad path, backend open failure, +unsupported content) is reported the same way with the underlying error name, +instead of failing silently. Normal diagnostics do not expose the full media +path. + +`get_cpu_copy_count()` on a live `VideoStreamPlayback` reports how many +frames in this session have gone through a CPU-copy presenter — the Windows +Vulkan fallback or the current Linux Vulkan path. + +## Scope + +- **Codecs:** H.264, HEVC (Main and Main10). +- **Containers:** MP4, MOV — the loader registers `.mp4`, `.mov`, and + `.m4v`. +- **Pixel formats:** NV12 (8-bit) and 10-bit biplanar — x420 on macOS, + P010 on Windows — negotiated to match the source's bit depth. The + conversion shader normalises 10-bit payloads in 16-bit GPU words on both + platforms. +- **Colorimetry:** BT.709, BT.601, and BT.2020 YCbCr matrices; BT.709 / + BT.601 / BT.2020 / DCI-P3 primaries; BT.709, PQ (ST 2084 / HDR10), and HLG + transfer functions; video and full range. Unspecified fields default to + BT.709, video range. +- **HDR:** PQ/HLG clips tone-map to watchable SDR by default, or output + scene-linear HDR (RGBA16F, 1.0 = 203-nit Reference White per BT.2408) when + the stream's `output_mode` is set to HDR. +- **Audio:** AAC, decoded to interleaved float32 PCM. Mono, stereo, and 5.1 + sources are channel-mixed to the clip's canonical output format. +- **Multi-track audio:** supported — enumerate tracks with + `NativeVideoStream.get_audio_tracks()` and select one via + `VideoStreamPlayer.audio_track`, either before `play()` or mid-playback. + +Beyond this scope, the extension will attempt to play anything the OS media +framework can decode, as long as it arrives in one of the registered +container extensions above. Such content may well work, but only the matrix +above is tested and contractually supported. + +**Out of scope:** VP9/AV1. **Known limitation:** mixed-sample-rate clips — +the first audio track's sample rate wins, and a mid-stream switch to a +track with a differing rate is refused. + +## Building from source + +1. Install Zig 0.16.0 (`mise install` picks it up from + [mise.toml](mise.toml), or install it directly — the system Zig on most + machines will be a newer, incompatible version). + + The pinned `gdzig` bindgen currently expects Godot 4.6's extension API + JSON. A library generated against 4.6 is compatible with and has been + smoke-tested in Godot 4.7.1, but passing a 4.7 executable through + `-Dgodot-path` makes this bindgen revision fail while parsing the newer + JSON. For a 4.7 runtime, omit `-Dgodot-path` (the build downloads Godot + 4.6 for bindgen) or point it at a 4.6.x executable. + + To build bindings with 4.6 but run integration checks with an installed + 4.7 executable, provide both paths separately: + + ```bash + zig build lifecycle-smoke \ + -Dgodot-path=/path/to/Godot-4.6 \ + -Druntime-godot-path=/path/to/Godot-4.7 -- /path/a.mp4 /path/b.mp4 + ``` + +2. Build the extension: + + ```bash + zig build + ``` + + This compiles `libnative_video.dylib` (macOS), `native_video.dll` + (Windows), or `libnative_video.so` (Linux) and installs it to `project/lib/`, where + `project/native_video.gdextension` expects it. `build.zig` is the entire + build entry point. Apple/Windows dependencies are system frameworks; + Linux additionally resolves the documented GStreamer development packages + through `pkg-config`. + + Builds default to a stripped `ReleaseFast` binary (~380 KB on macOS + arm64; Windows binary size hasn't been separately measured). Pass + `-Doptimize=Debug` for a debug build, or `-Doptimize=ReleaseSmall` to + trade some speed for an even smaller library. + + To target a double-precision Godot build, add `-Dprecision=double` + (default is `float`). The precision must match the Godot the extension + loads into; a mismatch is a memory-layout error, not a graceful failure. + +3. Run the core unit tests (no Godot needed): + + ```bash + zig build test + ``` + + Linux can additionally run the standalone decode/seek/reopen harness under + Valgrind. Only definite and indirect leaks fail the step; install + `valgrind` first and explicitly enable software decoding only on machines + without a hardware plugin: + + ```bash + GODOT_NATIVE_VIDEO_ALLOW_SOFTWARE=1 zig build leak-check + ``` + +4. Run the demo project (builds the extension, launches Godot, and opens + the interactive playback UI against `project/synthetic.mp4` or a clip + passed after `--`): + + ```bash + zig build run + ``` + + For a headless pass/fail check instead — loads a clip, plays it, polls + for a presented video texture, does a pixel-content sanity check, and + quits with exit 0 (PASS) / 1 (FAIL) — use the dedicated smoke step: + + ```bash + zig build smoke + ``` + + Two additional integration steps exercise lifecycle teardown and load the + release-style addon directory from a generated clean Godot project: + + ```bash + zig build lifecycle-smoke -- /path/a.mp4 /path/b.mp4 --cycles=50 + zig build package-smoke + ``` + + (equivalent to `zig build run -- --smoke`, but headless). Both steps + download a matching Godot build for bindgen/running if `GODOT_PATH` or + `-Dgodot-path=/path/to/Godot` isn't set. + +## Project layout + +- `src/core/` — engine-independent core (clock, frame queue, scrubber, + present selector, decode scheduler, backend interface, color math). Pure + Zig, no Godot, AVFoundation, or Media Foundation imports; this is what + `zig build test` exercises. +- `src/avf/` — the AVFoundation backend (macOS): `avf_shim.m`/`avf_shim.h` + (a C-ABI Objective-C shim) plus the Zig glue that drives it through the + core `Backend` interface. `decode_smoke.zig` is a standalone CLI harness + that pumps the backend without Godot, for isolating decode-side bugs. +- `src/mf/` — the Media Foundation backend (Windows): a synchronous + `IMFSourceReader` driven through the core `Backend` interface, the + dedicated MTA `ComExecutor` thread, and the hand-written D3D11/D3D12/DXGI + bindings under `src/mf/win/`. `decode_smoke.zig` mirrors the AVFoundation + harness for isolating decode-side bugs without Godot. +- `src/linux/` — the Linux GStreamer backend, isolated C ABI shim, and + standalone decode smoke. +- `src/godot/` — [gdzig](https://github.com/gdzig/gdzig) glue: + `NativeVideoStream` / `NativeVideoStreamPlayback` registration, the + present pipeline that runs the NV12→RGB compute pass, and the surface + importers it selects between — Metal on macOS; on Windows, the pure + `importer_selector` function plus the D3D12 zero-copy and CPU-copy + importers it chooses between; on Linux, the counted system-memory Vulkan + presenter. +- `project/` — the example/verification Godot project and dev harness. + `main.gd`/`main.tscn` are a single entry point with two modes selected by + CLI flag: interactive playback UI (`zig build run`, the default) or + headless pass/fail verification (`zig build smoke`, `--smoke`). +- `addon/` — the shipped `.gdextension` template packaged into release + zips (see [Releases](#releases) below). Not used by `zig build`; the dev + harness in `project/` has its own `native_video.gdextension` pointing at + local build output. + +For the historical record of how this implementation was chosen — +benchmarks and rationale — see [EVALUATION.md](EVALUATION.md). + +## License + +MIT — see [LICENSE](LICENSE). diff --git a/addons/native_video/libnative_video.linux.debug.x86_64.so b/addons/native_video/libnative_video.linux.debug.x86_64.so new file mode 100644 index 0000000..476ea14 Binary files /dev/null and b/addons/native_video/libnative_video.linux.debug.x86_64.so differ diff --git a/addons/native_video/libnative_video.linux.release.x86_64.so b/addons/native_video/libnative_video.linux.release.x86_64.so new file mode 100644 index 0000000..2150f94 Binary files /dev/null and b/addons/native_video/libnative_video.linux.release.x86_64.so differ diff --git a/addons/native_video/native_video.gdextension b/addons/native_video/native_video.gdextension new file mode 100644 index 0000000..603a72a --- /dev/null +++ b/addons/native_video/native_video.gdextension @@ -0,0 +1,28 @@ +[configuration] +entry_symbol = "native_video_init" +compatibility_minimum = "4.6" +reloadable = false + +[libraries] +; macOS — universal binary (arm64 + x86_64 combined via `lipo`). +macos.debug = "libnative_video.macos.debug.dylib" +macos.release = "libnative_video.macos.release.dylib" + +; Windows — Media Foundation backend, cross-compiled with Zig's bundled +; mingw. No "lib" prefix, matching the extension's own build output. +windows.debug.x86_64 = "native_video.windows.debug.x86_64.dll" +windows.release.x86_64 = "native_video.windows.release.x86_64.dll" +windows.debug.x86_32 = "native_video.windows.debug.x86_32.dll" +windows.release.x86_32 = "native_video.windows.release.x86_32.dll" +windows.debug.arm64 = "native_video.windows.debug.arm64.dll" +windows.release.arm64 = "native_video.windows.release.arm64.dll" + +; Linux x86_64 — dynamically linked GStreamer backend. The deployment host +; must provide the documented GStreamer runtime and hardware decoder plugins. +linux.debug.x86_64 = "libnative_video.linux.debug.x86_64.so" +linux.release.x86_64 = "libnative_video.linux.release.x86_64.so" + +; iOS builds and links but is not shipped here: Godot's iOS export +; conventionally expects a static library / .xcframework, not a plain +; .dylib, and only link-time (not on-device runtime) has been verified. +; Follow-up work — see README. diff --git a/addons/native_video/native_video.gdextension.uid b/addons/native_video/native_video.gdextension.uid new file mode 100644 index 0000000..324806f --- /dev/null +++ b/addons/native_video/native_video.gdextension.uid @@ -0,0 +1 @@ +uid://cfo6pvpcvo28l diff --git a/addons/native_video/native_video.windows.debug.x86_64.dll b/addons/native_video/native_video.windows.debug.x86_64.dll new file mode 100644 index 0000000..e678e15 Binary files /dev/null and b/addons/native_video/native_video.windows.debug.x86_64.dll differ diff --git a/addons/native_video/native_video.windows.release.x86_64.dll b/addons/native_video/native_video.windows.release.x86_64.dll new file mode 100644 index 0000000..0ce3fb8 Binary files /dev/null and b/addons/native_video/native_video.windows.release.x86_64.dll differ diff --git a/addons/native_video/~native_video.windows.debug.x86_64.dll b/addons/native_video/~native_video.windows.debug.x86_64.dll new file mode 100644 index 0000000..e678e15 Binary files /dev/null and b/addons/native_video/~native_video.windows.debug.x86_64.dll differ diff --git a/addons/reload_current_scene/plugin.cfg b/addons/reload_current_scene/plugin.cfg new file mode 100644 index 0000000..40d6dc1 --- /dev/null +++ b/addons/reload_current_scene/plugin.cfg @@ -0,0 +1,7 @@ +[plugin] + +name="Reload Current Scene" +description="Helper button to reload the current scene." +author="Russell Matney" +version="v0.1.0" +script="plugin.gd" diff --git a/addons/reload_current_scene/plugin.gd b/addons/reload_current_scene/plugin.gd new file mode 100644 index 0000000..cdfcda9 --- /dev/null +++ b/addons/reload_current_scene/plugin.gd @@ -0,0 +1,25 @@ +@tool +extends EditorPlugin + + +var reload_scene_btn: Button = Button.new() + + +func _enter_tree() -> void: + reload_scene_btn.pressed.connect(reload_scene) + reload_scene_btn.text = "Reload Scene" + reload_scene_btn.icon = EditorInterface.get_editor_theme().get_icon("Reload", "EditorIcons") + add_control_to_container(CONTAINER_TOOLBAR, reload_scene_btn) + reload_scene_btn.get_parent().move_child(reload_scene_btn, reload_scene_btn.get_index() - 2) + + +func _exit_tree() -> void: + remove_control_from_container(CONTAINER_TOOLBAR, reload_scene_btn) + + +func reload_scene() -> void: + Log.info("[ReloadScene] Reload initialized", Time.get_time_string_from_system()) + var edited_scene: Node = EditorInterface.get_edited_scene_root() + Log.info("[ReloadScene] Edited scene", "%s.scene_file_path" % edited_scene, edited_scene.scene_file_path) + EditorInterface.reload_scene_from_path(edited_scene.scene_file_path) + Log.info("[ReloadScene] Scene reloaded", Time.get_time_string_from_system()) diff --git a/addons/reload_current_scene/plugin.gd.uid b/addons/reload_current_scene/plugin.gd.uid new file mode 100644 index 0000000..42a7adb --- /dev/null +++ b/addons/reload_current_scene/plugin.gd.uid @@ -0,0 +1 @@ +uid://df3sf44c3b64a diff --git a/artifacts/dual_hopper_priority_space_pixel.log b/artifacts/dual_hopper_priority_space_pixel.log new file mode 100644 index 0000000..4932dac --- /dev/null +++ b/artifacts/dual_hopper_priority_space_pixel.log @@ -0,0 +1,6 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +ERROR: Non-existing or invalid boot splash at 'res://src/images/logo.svg'. The only supported format is PNG. Loading default splash. + at: setup_boot_logo (main/main.cpp:3954) +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK diff --git a/artifacts/hopper_inventory_fallback.log b/artifacts/hopper_inventory_fallback.log new file mode 100644 index 0000000..4932dac --- /dev/null +++ b/artifacts/hopper_inventory_fallback.log @@ -0,0 +1,6 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +ERROR: Non-existing or invalid boot splash at 'res://src/images/logo.svg'. The only supported format is PNG. Loading default splash. + at: setup_boot_logo (main/main.cpp:3954) +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK diff --git a/artifacts/hopper_inventory_space_pixel.log b/artifacts/hopper_inventory_space_pixel.log new file mode 100644 index 0000000..4932dac --- /dev/null +++ b/artifacts/hopper_inventory_space_pixel.log @@ -0,0 +1,6 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +ERROR: Non-existing or invalid boot splash at 'res://src/images/logo.svg'. The only supported format is PNG. Loading default splash. + at: setup_boot_logo (main/main.cpp:3954) +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK diff --git a/artifacts/linux/debian13/Exchanger.sh b/artifacts/linux/debian13/Exchanger.sh new file mode 100644 index 0000000..ef73622 --- /dev/null +++ b/artifacts/linux/debian13/Exchanger.sh @@ -0,0 +1,4 @@ +#!/bin/sh +printf '\033c\033]0;%s\a' Exchanger +base_path="$(dirname "$(realpath "$0")")" +"$base_path/Exchanger.x86_64" "$@" diff --git a/artifacts/linux/debian13/Exchanger.x86_64 b/artifacts/linux/debian13/Exchanger.x86_64 new file mode 100644 index 0000000..4dfedfb Binary files /dev/null and b/artifacts/linux/debian13/Exchanger.x86_64 differ diff --git a/artifacts/linux/debian13/debug/Exchanger.Debug.sh b/artifacts/linux/debian13/debug/Exchanger.Debug.sh new file mode 100644 index 0000000..d5cb7d7 --- /dev/null +++ b/artifacts/linux/debian13/debug/Exchanger.Debug.sh @@ -0,0 +1,4 @@ +#!/bin/sh +printf '\033c\033]0;%s\a' Exchanger +base_path="$(dirname "$(realpath "$0")")" +"$base_path/Exchanger.Debug.x86_64" "$@" diff --git a/artifacts/linux/debian13/debug/Exchanger.Debug.x86_64 b/artifacts/linux/debian13/debug/Exchanger.Debug.x86_64 new file mode 100644 index 0000000..32c32b8 Binary files /dev/null and b/artifacts/linux/debian13/debug/Exchanger.Debug.x86_64 differ diff --git a/artifacts/linux/debian13/libnative_video.linux.debug.x86_64.so b/artifacts/linux/debian13/libnative_video.linux.debug.x86_64.so new file mode 100644 index 0000000..476ea14 Binary files /dev/null and b/artifacts/linux/debian13/libnative_video.linux.debug.x86_64.so differ diff --git a/artifacts/linux/debian13/libnative_video.linux.release.x86_64.so b/artifacts/linux/debian13/libnative_video.linux.release.x86_64.so new file mode 100644 index 0000000..2150f94 Binary files /dev/null and b/artifacts/linux/debian13/libnative_video.linux.release.x86_64.so differ diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..5602ed2 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:39:46.3855463+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..560b883 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,10 @@ +2026-09-07T11:39:46.3795914+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:39:46.3836723+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:39:46.3842333+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:39:46.4310013+03:00 [INFO] [Theme] Активирована единственная встроенная тема по умолчанию. +2026-09-07T11:39:46.6804906+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:39:46.6828159+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:39:46.6835094+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:39:46.6837246+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:39:46.9025299+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:39:46.9029126+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..cea0c41 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-2/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,13 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Базовые жетоны карточного пресета имеют неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:96) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:58) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Нулевой бонус карточного пресета имеет неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:96) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:60) diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..ddb144d --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:40:14.763465+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..6979876 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,10 @@ +2026-09-07T11:40:14.7580281+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:40:14.7617705+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:40:14.7623207+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:40:14.8042591+03:00 [INFO] [Theme] Активирована единственная встроенная тема по умолчанию. +2026-09-07T11:40:15.0511919+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:40:15.0529798+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:40:15.0537568+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:40:15.0539608+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:40:15.2728076+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:40:15.2733800+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..8ea211d --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-3/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,14 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=НЕДОСТАТОЧНО ЖЕТОНОВ bonus= +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Базовые жетоны карточного пресета имеют неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:98) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:60) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Нулевой бонус карточного пресета имеет неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:98) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:62) diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..6f44dbd --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:40:49.295052+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..8715bef --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,10 @@ +2026-09-07T11:40:49.2897950+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:40:49.2927212+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:40:49.2934465+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:40:49.3352288+03:00 [INFO] [Theme] Активирована единственная встроенная тема по умолчанию. +2026-09-07T11:40:49.5377577+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:40:49.5390681+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:40:49.5395258+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:40:49.5396792+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:40:50.5385434+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:40:50.5388998+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..b3ea5b3 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-4/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,14 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=НЕДОСТАТОЧНО ЖЕТОНОВ bonus= +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Базовые жетоны карточного пресета имеют неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:102) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:64) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Нулевой бонус карточного пресета имеет неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:102) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:66) diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..c223cbb --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:41:22.1806547+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..9911c40 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,15 @@ +2026-09-07T11:41:22.1727431+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:41:22.1785988+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:41:22.1793564+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:41:22.2422487+03:00 [INFO] [Theme] Активирована единственная встроенная тема по умолчанию. +2026-09-07T11:41:22.4774435+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:41:22.4789337+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:41:22.4923305+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:41:22.4926274+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:41:22.7150689+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:41:22.7165007+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:41:23.5738665+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:41:23.5745540+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:41:23.5746740+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:41:23.8573776+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:41:23.8577317+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..eb5c56b --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,5 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=10 ЖЕТОНОВ bonus=БЕЗ БОНУСА +PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..87d0bde --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin-5/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T08:41:23.5754185+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..76274c5 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:38:20.8550389+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..0d70cc3 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,20 @@ +2026-09-07T11:38:20.8463310+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:38:20.8522800+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:38:20.8535504+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:38:20.9188990+03:00 [INFO] [Theme] Активирована единственная встроенная тема по умолчанию. +2026-09-07T11:38:21.2495989+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:38:21.2517361+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:38:21.2526637+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:38:21.2529477+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:38:21.4423392+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:38:21.4428013+03:00 [INFO] [Application] Журнал приложения завершён. +2026-09-07T11:38:48.9008976+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:38:48.9027102+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:38:48.9031711+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:38:48.9422767+03:00 [INFO] [Theme] Активирована единственная встроенная тема по умолчанию. +2026-09-07T11:38:49.1927061+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:38:49.1942057+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:38:49.1945204+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:38:49.1947727+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:38:49.3965352+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:38:49.3969889+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..a52c971 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,24 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Базовые жетоны карточного пресета имеют неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:85) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:51) +SCRIPT ERROR: Assertion failed: Базовые жетоны карточного пресета имеют неверный формат + at: _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:87) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:87) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:51) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Нулевой бонус карточного пресета имеет неверный формат + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:85) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:53) +SCRIPT ERROR: Assertion failed: Нулевой бонус карточного пресета имеет неверный формат + at: _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:87) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:87) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:53) +PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/godot2026-09-07T11.38.48.log b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/godot2026-09-07T11.38.48.log new file mode 100644 index 0000000..51bd09f --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/builtin/Godot/app_userdata/Exchanger/logs/godot2026-09-07T11.38.48.log @@ -0,0 +1,17 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Не разрешены платёжные bindings + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:80) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:38) +SCRIPT ERROR: Assertion failed: Не разрешены платёжные bindings + at: _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:82) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:82) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:38) +SCRIPT ERROR: Cannot call method 'emit_signal' on a null value. + at: _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:44) + GDScript backtrace (most recent call first): + [0] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:44) diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..80cc4e8 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T09:13:39.4125566+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..2749e53 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,15 @@ +2026-09-07T12:13:39.4061166+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T12:13:39.4108209+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T12:13:39.4115698+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T12:13:39.4677727+03:00 [INFO] [Theme] Активирована единственная встроенная тема по умолчанию. +2026-09-07T12:13:39.7807408+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T12:13:39.7820899+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T12:13:39.7826234+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T12:13:39.7829050+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T12:13:40.0250546+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T12:13:40.0262624+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T12:13:40.8587000+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T12:13:40.8594035+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T12:13:40.8595660+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T12:13:41.1834134+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T12:13:41.1838350+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..eb5c56b --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,5 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=10 ЖЕТОНОВ bonus=БЕЗ БОНУСА +PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..a98e56d --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/builtin/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T09:13:40.8606892+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..022872e --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T09:13:41.9797521+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..cbddd00 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,17 @@ +2026-09-07T12:13:41.9730827+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T12:13:41.9775552+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T12:13:41.9781904+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T12:13:42.4541067+03:00 [INFO] [Theme] Активирована внешняя DLC-тема space-pixel (Космическая pixel-тема). +2026-09-07T12:13:42.4544917+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T12:13:42.7925463+03:00 [INFO] [InteractivePet] Питомец темы space-pixel активирован. +2026-09-07T12:13:42.8034290+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T12:13:42.8055503+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T12:13:42.8060203+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T12:13:42.8064325+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T12:13:43.0254448+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T12:13:43.0264209+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T12:13:43.8778280+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T12:13:43.8787549+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T12:13:43.8789203+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T12:13:44.1648519+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T12:13:44.1652488+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..eb5c56b --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,5 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=10 ЖЕТОНОВ bonus=БЕЗ БОНУСА +PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..1599a46 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/final-control/space-pixel/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T09:13:43.8808891+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..289ac27 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:47:59.9641103+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..b625b1b --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,16 @@ +2026-09-07T11:47:59.9596373+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:47:59.9626505+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:47:59.9630271+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:48:00.2027597+03:00 [INFO] [Theme] Активирована внешняя DLC-тема example (Пример темы). +2026-09-07T11:48:00.2031464+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T11:48:00.4433997+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:48:00.4730662+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:48:00.4734536+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:48:00.4737379+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:48:00.6720564+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:48:00.6729111+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:48:01.8763761+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:48:01.8770168+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:48:01.8771303+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:48:02.0747706+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:48:02.0752001+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..eb5c56b --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,5 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=10 ЖЕТОНОВ bonus=БЕЗ БОНУСА +PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..877b19f --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-example-2/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T08:48:01.8779825+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..52d999f --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:44:39.5133551+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..a92ad73 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,14 @@ +2026-09-07T11:44:39.5080768+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:44:39.5115721+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:44:39.5121973+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:44:40.0142632+03:00 [INFO] [Theme] Активирована внешняя DLC-тема example (Пример темы). +2026-09-07T11:44:40.0146768+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T11:44:40.2679711+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:44:40.2701858+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:44:40.2705664+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:44:40.2707882+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:44:40.4714518+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:44:40.4725779+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:44:41.3226294+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:44:41.3233805+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:44:41.3235563+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..1be1a28 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,12 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Не разрешены платёжные bindings + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:113) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:58) +SCRIPT ERROR: Invalid access to property or key 'text' on a base object of type 'null instance'. + at: _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:61) + GDScript backtrace (most recent call first): + [0] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:61) diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..ae9b64e --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-pcks/example/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T08:44:41.3245621+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..4c90ed6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:48:14.7274808+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..fcc279e --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,17 @@ +2026-09-07T11:48:14.7229358+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:48:14.7259825+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:48:14.7263529+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:48:15.0319601+03:00 [INFO] [Theme] Активирована внешняя DLC-тема space-pixel (Космическая pixel-тема). +2026-09-07T11:48:15.0322656+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T11:48:15.2607682+03:00 [INFO] [InteractivePet] Питомец темы space-pixel активирован. +2026-09-07T11:48:15.2937494+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:48:15.2956054+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:48:15.2960753+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:48:15.2962670+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:48:15.4940316+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:48:15.4950793+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:48:16.4447962+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:48:16.4454495+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:48:16.4455517+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:48:16.7076708+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:48:16.7081437+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..1822c48 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,14 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=10 ЖЕТОНОВ bonus=БЕЗ БОНУСА +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Поля жетонов и бонуса карточного пресета перекрываются + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:119) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:68) +ERROR: PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_FAILED: Поля жетонов и бонуса ручной карточной суммы перекрываются + at: push_error (core/variant/variant_utility.cpp:1023) + GDScript backtrace (most recent call first): + [0] _assert (res://tests/runtime/payment_reward_formatting_smoke.gd:119) + [1] _ready (res://tests/runtime/payment_reward_formatting_smoke.gd:72) diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..dcb9e7e --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-2/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T08:48:16.4465154+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..e90e0a0 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:48:48.3979407+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..4d74cc7 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,17 @@ +2026-09-07T11:48:48.3930433+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:48:48.3962076+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:48:48.3967170+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:48:48.7218554+03:00 [INFO] [Theme] Активирована внешняя DLC-тема space-pixel (Космическая pixel-тема). +2026-09-07T11:48:48.7222024+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T11:48:48.9415925+03:00 [INFO] [InteractivePet] Питомец темы space-pixel активирован. +2026-09-07T11:48:48.9564241+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:48:48.9576224+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:48:48.9578747+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:48:48.9580318+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:48:49.1553552+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:48:49.1562799+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:48:50.0888488+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:48:50.0894252+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:48:50.0895263+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:48:50.3047870+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:48:50.3052246+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..eb5c56b --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,5 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=10 ЖЕТОНОВ bonus=БЕЗ БОНУСА +PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..ebd6294 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/fresh-space-pixel-3/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T08:48:50.0904213+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..9a17af6 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..abe40ae --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:53:39.7725231+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..d7f7c82 --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,19 @@ +2026-09-07T11:53:39.7672648+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:53:39.7708095+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:53:39.7712801+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:53:40.1087830+03:00 [INFO] [Theme] Активирована внешняя DLC-тема space-pixel (Космическая pixel-тема). +2026-09-07T11:53:40.1091214+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T11:53:40.2096526+03:00 [INFO] [Theme] Экран CardAmount: восстановлена совместимость биндингов — 1. +2026-09-07T11:53:40.2817772+03:00 [INFO] [Theme] Экран Settings: восстановлена совместимость биндингов — 3. +2026-09-07T11:53:40.3723311+03:00 [INFO] [InteractivePet] Питомец темы space-pixel активирован. +2026-09-07T11:53:40.3822913+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:53:40.3841381+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:53:40.3845267+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:53:40.3847309+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:53:40.5862765+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:53:40.5873229+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:53:41.4450696+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:53:41.4457327+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:53:41.4458728+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:53:41.7282916+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:53:41.7287036+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..eb5c56b --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,5 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +PAYMENT_REWARD_FORMATTING_VALUES preset=100 РУБ. base=10 ЖЕТОНОВ bonus=БЕЗ БОНУСА +PAYMENT_REWARD_FORMATTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..fc20c2a --- /dev/null +++ b/artifacts/runtime-smoke/payment-reward-formatting/legacy-active/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1 @@ +{"Timestamp":"2026-09-07T08:53:41.4468445+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..a70bf2e --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": false, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..264af86 --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:24:38.4094161+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..596911a --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,19 @@ +2026-09-07T11:24:38.4045723+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:24:38.4080438+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:24:38.4084473+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:24:38.6599206+03:00 [INFO] [Theme] Активирована внешняя DLC-тема example (Пример темы). +2026-09-07T11:24:38.6603936+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T11:24:38.9004399+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:24:38.9025469+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:24:38.9028865+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:24:38.9031411+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:24:39.0700802+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:24:39.0710671+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:24:39.9718594+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:24:39.9726068+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:24:39.9727297+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:24:40.7212455+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:24:40.7216587+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:24:40.7217563+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:24:41.0053087+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:24:41.0057407+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..de4c00f --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,4 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +TOKEN_INVENTORY_ACCOUNTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..8f930d4 --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/example/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1,2 @@ +{"Timestamp":"2026-09-07T08:24:39.9735275+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} +{"Timestamp":"2026-09-07T08:24:40.722079+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json new file mode 100644 index 0000000..7ada4ea --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/default_settings.json @@ -0,0 +1,105 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/.embedded/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json new file mode 100644 index 0000000..a70bf2e --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": false, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json.bak b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json.bak new file mode 100644 index 0000000..8bbaa69 --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/appsettings.json.bak @@ -0,0 +1,121 @@ +{ + "ConfigurationVersion": 23, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { + "AmountRubles": 10 + }, + { + "AmountRubles": 50 + }, + { + "AmountRubles": 100 + }, + { + "AmountRubles": 150 + }, + { + "AmountRubles": 200 + }, + { + "AmountRubles": 300 + }, + { + "AmountRubles": 400 + }, + { + "AmountRubles": 500 + } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "\u0420\u0410\u0417\u041C\u0415\u041D \u0416\u0415\u0422\u041E\u041D\u041E\u0412", + "ShortText": "\u041F\u041E\u041B\u0423\u0427\u0418 \u0421\u0412\u041E\u0418 \u0416\u0415\u0422\u041E\u041D\u042B!", + "SupportPhone": "\u0422\u0435\u043B\u0435\u0444\u043E\u043D \u043F\u043E\u0434\u0434\u0435\u0440\u0436\u043A\u0438 \u0443\u0442\u043E\u0447\u043D\u044F\u0435\u0442\u0441\u044F" + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "\u041F\u0420\u041E\u041C\u041E-\u0411\u041B\u041E\u041A" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": false + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/technical_settings.toml b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/technical_settings.toml new file mode 100644 index 0000000..8d2448a --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/config/technical_settings.toml @@ -0,0 +1,62 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/data/token_inventory.json b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/data/token_inventory.json new file mode 100644 index 0000000..06ce9b1 --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/data/token_inventory.json @@ -0,0 +1,7 @@ +{ + "Count": 0, + "Hopper1Count": 0, + "Hopper2Count": 0, + "Revision": 0, + "UpdatedAtUtc": "2026-09-07T08:24:41.6442197+00:00" +} \ No newline at end of file diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/exchanger.log b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/exchanger.log new file mode 100644 index 0000000..478fc85 --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/exchanger.log @@ -0,0 +1,20 @@ +2026-09-07T11:24:41.6387040+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:24:41.6423345+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:24:41.6429364+03:00 [DEBUG] [Application] Старт DEBUG runtime: os=Windows, mock=True, port=COM3, baud=115200. +2026-09-07T11:24:41.9616698+03:00 [INFO] [Theme] Активирована внешняя DLC-тема space-pixel (Космическая pixel-тема). +2026-09-07T11:24:41.9620406+03:00 [INFO] [Theme] Тема загружена из внешнего DLC. +2026-09-07T11:24:42.2006551+03:00 [INFO] [InteractivePet] Питомец темы space-pixel активирован. +2026-09-07T11:24:42.2123688+03:00 [DEBUG] [Application] Первичное подключение: reconnectSeconds=30, handshakeTimeoutMs=2000. +2026-09-07T11:24:42.2141465+03:00 [INFO] [MockHardware] Подключена имитация порта COM3 @ 115200. +2026-09-07T11:24:42.2144299+03:00 [INFO] [MockHardware] Команда: PING +2026-09-07T11:24:42.2145918+03:00 [INFO] [Application] Mock-сценарий Exchanger запущен. +2026-09-07T11:24:42.3906684+03:00 [INFO] [Navigation] Открыт экран Settings. +2026-09-07T11:24:42.3915641+03:00 [INFO] [Service] Настройки открыты напрямую: защита сервисным PIN выключена. +2026-09-07T11:24:43.2304463+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:24:43.2311572+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:24:43.2312654+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:24:44.0300130+03:00 [INFO] [Settings] Настройки приложения сохранены автоматически. +2026-09-07T11:24:44.0305876+03:00 [INFO] [Application] Журнал приложения инициализирован. +2026-09-07T11:24:44.0307185+03:00 [DEBUG] [Application] Расширенная безопасная диагностика DEBUG-сборки включена. +2026-09-07T11:24:44.3306862+03:00 [INFO] [MockHardware] Имитация порта отключена. +2026-09-07T11:24:44.3311290+03:00 [INFO] [Application] Журнал приложения завершён. diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/godot.log b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/godot.log new file mode 100644 index 0000000..de4c00f --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/godot.log @@ -0,0 +1,4 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +TOKEN_INVENTORY_ACCOUNTING_RUNTIME_SMOKE_OK diff --git a/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl new file mode 100644 index 0000000..ea4bef8 --- /dev/null +++ b/artifacts/runtime-smoke/purchase-limit-fresh-pcks/space-pixel/Godot/app_userdata/Exchanger/logs/settings-audit.jsonl @@ -0,0 +1,2 @@ +{"Timestamp":"2026-09-07T08:24:43.2321269+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} +{"Timestamp":"2026-09-07T08:24:44.0311741+00:00","Role":"Debug","Sections":["Сервис"],"RestartRequired":false} diff --git a/artifacts/service_dialog_keyboard_fallback.log b/artifacts/service_dialog_keyboard_fallback.log new file mode 100644 index 0000000..4932dac --- /dev/null +++ b/artifacts/service_dialog_keyboard_fallback.log @@ -0,0 +1,6 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +ERROR: Non-existing or invalid boot splash at 'res://src/images/logo.svg'. The only supported format is PNG. Loading default splash. + at: setup_boot_logo (main/main.cpp:3954) +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK diff --git a/artifacts/service_dialog_keyboard_space_pixel.log b/artifacts/service_dialog_keyboard_space_pixel.log new file mode 100644 index 0000000..4932dac --- /dev/null +++ b/artifacts/service_dialog_keyboard_space_pixel.log @@ -0,0 +1,6 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +ERROR: Non-existing or invalid boot splash at 'res://src/images/logo.svg'. The only supported format is PNG. Loading default splash. + at: setup_boot_logo (main/main.cpp:3954) +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK diff --git a/artifacts/token_declension_space_pixel.log b/artifacts/token_declension_space_pixel.log new file mode 100644 index 0000000..4932dac --- /dev/null +++ b/artifacts/token_declension_space_pixel.log @@ -0,0 +1,6 @@ +Godot Engine v4.7.1.stable.mono.official.a13da4feb - https://godotengine.org + +ERROR: Non-existing or invalid boot splash at 'res://src/images/logo.svg'. The only supported format is PNG. Loading default splash. + at: setup_boot_logo (main/main.cpp:3954) +[godot_ai game_helper] registered mcp capture (debugger active=false, logger=true) +ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK diff --git a/config/default_settings.json b/config/default_settings.json new file mode 100644 index 0000000..235a0a6 --- /dev/null +++ b/config/default_settings.json @@ -0,0 +1,112 @@ +{ + "ConfigurationVersion": 25, + "Window": { + "Fullscreen": true, + "Borderless": true, + "DebugWindowInDebugBuild": true, + "DebugWindowWidth": 720, + "DebugWindowHeight": 1280, + "TargetFps": 60 + }, + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + }, + "Hardware": { + "UseMock": true, + "PortName": "COM3", + "BaudRate": 115200, + "FrameTimeoutMilliseconds": 100, + "MaximumFrameLength": 1024, + "HandshakeTimeoutMilliseconds": 2000, + "CashlessKeepAliveSeconds": 120, + "ReconnectIntervalSeconds": 30, + "ServiceButtonInputIndex": 8, + "ServiceButtonActiveHigh": false, + "StockSensorInputIndex": 1, + "StockLowWhenInputHigh": false, + "Hopper2StockSensorInputIndex": 4, + "Hopper2StockLowWhenInputHigh": false, + "Hopper1DispenseSensorInputIndex": 24, + "Hopper1DispenseSensorActiveHigh": false, + "Hopper2DispenseSensorInputIndex": 25, + "Hopper2DispenseSensorActiveHigh": false, + "InputPollMilliseconds": 100, + "StockPollSeconds": 5, + "ControllerAesMode": "ECB", + "ControllerAesKeyEnvironmentVariable": "EXCHANGER_CONTROLLER_AES_KEY", + "DispenseMode": "Unsupported", + "MockStockLevel": "Enough" + }, + "Timeouts": { + "SessionIdleSeconds": 45, + "CashPaymentSeconds": 45, + "CashlessPaymentSeconds": 120, + "SuccessSeconds": 10 + }, + "Pricing": { + "TokenPriceRubles": 10, + "MaxCardAmountRubles": 5000, + "CustomAmountStepRubles": 10, + "PaymentPresets": [ + { "AmountRubles": 10 }, + { "AmountRubles": 50 }, + { "AmountRubles": 100 }, + { "AmountRubles": 150 }, + { "AmountRubles": 200 }, + { "AmountRubles": 300 }, + { "AmountRubles": 400 }, + { "AmountRubles": 500 } + ], + "BonusRules": [] + }, + "Payments": { + "CashEnabled": true, + "CardEnabled": true + }, + "Branding": { + "ApplicationName": "РАЗМЕН ЖЕТОНОВ", + "ShortText": "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + "SupportPhone": "Телефон поддержки уточняется" + }, + "AnimatedBannerTexts": { + "CashPayment": "АВТОМАТ НЕ ВЫДАЁТ СДАЧУ", + "CardAmount": "ВЫБЕРИТЕ СУММУ ДЛЯ ПЕРЕХОДА К ТЕРМИНАЛУ", + "CardCustomAmount": "ВВЕДИТЕ СУММУ ДЛЯ ОПЛАТЫ", + "CardTerminalCountdownTemplate": "ОСТАЛОСЬ {seconds} СЕК." + }, + "Audio": { + "MasterVolumePercent": 100, + "Muted": false, + "AdvertisementVolumePercent": 100 + }, + "Advertisement": { + "Enabled": true, + "VideoPaths": [], + "PosterPath": "", + "Muted": true, + "FallbackText": "ПРОМО-БЛОК" + }, + "MenuVisibility": { + "ShowStockStatus": true, + "ShowRightCharacter": true, + "ShowPromotionBlock": true, + "ShowInteractivePet": true + }, + "TokenInventory": { + "Enabled": true, + "PurchaseLimitEnabled": true + }, + "Logging": { + "MinimumLevel": "Info", + "MaxFileSizeMb": 5, + "RetentionDays": 14 + }, + "Security": { + "ServicePinEnabled": false, + "ServicePinSaltBase64": "", + "ServicePinHashBase64": "", + "ServicePinIterations": 210000 + } +} diff --git a/config/technical_settings.toml b/config/technical_settings.toml new file mode 100644 index 0000000..ca7423b --- /dev/null +++ b/config/technical_settings.toml @@ -0,0 +1,65 @@ +# Техническая конфигурация Exchanger. +# +# Этот файл предназначен для монтажника или технического специалиста. +# Он не отображается и не редактируется в интерфейсе приложения. +# После изменения полностью перезапустите приложение. +# +# При первом запуске копия файла создаётся по адресу: +# user://config/technical_settings.toml + +version = 1 + +[theme] +# Каталог с PCK-темами: user:// либо абсолютный путь текущей ОС. +# Windows с обратными слешами: directory = 'D:\Exchanger\themes' +# В одинарной TOML-строке обратные слеши не нужно удваивать. +directory = "user://theme_dlc" +# Имя выбранного файла строго без расширения .pck. +file_name = "active_theme" +enabled = true + +[controller] +# true — безопасный программный имитатор; false — реальный основной контроллер. +use_mock = true +# Полное имя фиксирует устройство (например, COM3 или /dev/ttyUSB0). +# COM перебирает доступные COM-порты по номеру от 0, а ttyUSB или /dev/ttyUSB — +# доступные /dev/ttyUSB* по номеру от 0 до успешной авторизации. +port = "COM3" +baud_rate = 115200 +# Пауза между попытками открыть порт после отсутствия платы или обрыва связи. +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +# Контроллер Вендиста должен получать keep-alive реже одного раза в 180 секунд. +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +# Датчик малого остатка первого хоппера: IN1, active-low. +stock_sensor_input = 1 +stock_low_active_high = false +# Физический датчик выдачи первого хоппера: IN24, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER1 OK. +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +# Датчик малого остатка второго хоппера: IN4, active-low. +stock_sensor_input = 4 +stock_low_active_high = false +# Физический датчик выдачи второго хоппера: IN25, active-low. +# Основной учёт обычной выдачи ведётся по ответам HOPPER2 OK. +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +# Сервисная кнопка: IN8, active-low. +button_input = 8 +button_active_high = false + +[polling] +# Частота резервного чтения цифровых входов. +input_poll_ms = 100 +stock_poll_seconds = 5 diff --git a/default_bus_layout.tres b/default_bus_layout.tres new file mode 100644 index 0000000..799e0de --- /dev/null +++ b/default_bus_layout.tres @@ -0,0 +1,15 @@ +[gd_resource type="AudioBusLayout" format=3] + +[resource] +bus/0/name = &"Master" +bus/0/solo = false +bus/0/mute = false +bus/0/bypass_fx = false +bus/0/volume_db = 0.0 +bus/0/send = &"" +bus/1/name = &"Advertisement" +bus/1/solo = false +bus/1/mute = false +bus/1/bypass_fx = false +bus/1/volume_db = 0.0 +bus/1/send = &"Master" diff --git a/docs/REFERENCE_ANALYSIS.md b/docs/REFERENCE_ANALYSIS.md new file mode 100644 index 0000000..7dc4348 --- /dev/null +++ b/docs/REFERENCE_ANALYSIS.md @@ -0,0 +1,168 @@ +# Анализ визуальных референсов Exchanger + +Дата анализа: **2026-08-20**. + +## Статус материалов + +Каталог `references/` содержит локальные концептуальные материалы и добавлен в `.gitignore`. Эти файлы используются для понимания продукта и не предназначены для приложения или production-сборки. Сам `.gitignore` не управляет экспортом Godot, поэтому будущий export preset должен явно исключить `references/`. Перед использованием конкретных логотипов, персонажей, шрифтов и иллюстраций необходимо подтвердить права и получить исходники подходящего качества. + +Проанализированы: + +- семь макетов интерфейса размером 720×1280; +- один рендер корпуса размером 904×1280; +- видео интерфейса H.264 размером 1080×1920, 50 FPS, длительностью 32,16 секунды, без звуковой дорожки. + +## Физический аппарат + +Референс показывает высокий напольный разменник с портретным экраном: + +- корпус с сильно скруглёнными углами и зелёной рамой; +- установка на четырёх колёсах; +- вертикальный экран на передней панели с подсвеченной рамкой; +- справа от экрана сверху вниз расположены купюроприёмник, платёжный терминал/NFC, монетоприёмник и дополнительный сервисный элемент; +- ниже экрана расположен подсвеченный лоток выдачи жетонов с подписью «Жетоны здесь!»; +- на лицевой панели размещено название «Размен»; +- оформление корпуса продолжает космическую тему интерфейса: звёзды, НЛО, зелёный инопланетянин, луч, корова и монеты; +- боковая панель содержит вертикальную надпись «Размен жетонов». + +Из этого следует, что UI должен проектироваться для портретного дисплея и визуально согласовываться с оклейкой корпуса. Расположение физических приёмников справа можно отражать направляющими иллюстрациями на соответствующих экранах оплаты. + +## Визуальный язык интерфейса + +- Целевая ориентация — портретная 9:16. +- Основной референсный viewport — 1080×1920; макеты также представлены в 720×1280. +- Стиль — яркий пиксель-арт с космическим фоном. +- Основные цвета: тёмно-синий фон, салатовый/зелёный акцент, белые панели и тёмно-синий текст. +- Панели имеют белое тело, зелёную строку-заголовок и скруглённые углы. +- Основные кнопки — крупные зелёные плашки с синим текстом. +- В верхней части присутствуют цена жетона, персонажи и короткие реплики. +- В нижней части постоянно видны бренд/логотип и телефон технической поддержки. +- Инопланетянин и НЛО выполняют роль маскота, подсказки и отображения результата. +- Фоновая композиция статична. Движение создают отдельные спрайты НЛО, луча и персонажей, которые не перекрывают функциональные панели. + +Текущая космическая тема проекта является техническим прототипом. На Этапе 2 её следует адаптировать к портретной пиксельной композиции, не копируя неподтверждённые референсные ассеты напрямую. Фоновая картинка должна оставаться статичной; шейдеры, частицы и фоновое видео для неё не нужны. Промо-ролик — отдельный UI-компонент домашнего экрана. + +## Домашний экран + +На домашнем экране одновременно отображаются: + +- цена одного жетона; в референсе — 10 рублей; +- бинарное состояние запаса: «много жетонов» или «мало жетонов», без числового остатка; +- выбор способа оплаты: наличные или безналичные; +- крупное действие «Выдать»; +- промо-блок; +- логотип и телефон технической поддержки; +- тематические персонажи и короткая реплика клиента/маскота. + +Референс не использует отдельный пустой стартовый экран с кнопкой «Начать». Домашний экран сразу показывает состояние автомата и доступные способы оплаты. Существующий `StartScreen` следует преобразовать в `HomeScreen` или заменить им при внедрении навигации. + +## Ветка оплаты наличными + +Экран «Оплата наличными» содержит: + +- кнопку возврата; +- текущий внесённый баланс; +- рассчитанное количество жетонов и возможный бонус; +- иллюстрации купюроприёмника и монетоприёмника; +- инструкции, куда вносить купюры и монеты; +- действие выдачи после достаточного баланса. + +Контроллер должен передавать приложению события о принятой сумме и, вероятно, текущее состояние приёмников. Правила сдачи, минимальной суммы и отмены необходимо согласовать отдельно. + +## Ветка оплаты картой + +Референс показывает несколько последовательных состояний: + +1. Выбор одной из предустановленных сумм: 10, 50, 100, 150, 200, 300, 400 или 500 рублей. +2. Кнопку «Другая сумма». +3. Цифровую клавиатуру для ввода произвольной суммы, отмену, очистку/ноль и подтверждение. +4. Экран ожидания с инструкцией приложить карту к платёжному терминалу. +5. Экран результата оплаты. + +В видео показан отрицательный результат «Оплата не прошла» с грустным маскотом. Успешный результат и подтверждённая выдача в референсах не показаны, поэтому их визуальная композиция должна быть спроектирована отдельно в том же стиле. + +## Бонусы и расчёт жетонов + +На макетах присутствует пример «100 жетонов + 50 жетонов в подарок». Это требует отдельной конфигурируемой модели: + +- цена одного жетона; +- предустановленные суммы; +- правила округления суммы в количество жетонов; +- пороги и размер бонуса; +- максимальная сумма. + +Датчик хоппера не сообщает точный остаток, поэтому приложение не может проверять выбранный пакет против количества жетонов внутри. Состояние `Low` предупреждает о малом уровне, но не блокирует оплату; отсутствие подтверждённого сигнала (`Unknown`) блокирует её до диагностики. + +Числа из референса считаются примерами до подтверждения владельцем продукта. + +## Промо-блок + +Домашний экран содержит отдельную область для промо-ролика. Планируемый компонент должен: + +- воспроизводить локальные ролики по циклу; +- иметь статический fallback-постер; +- не блокировать основной поток и тач-ввод; +- отключать декодирование на скрытых экранах; +- работать без звука по умолчанию, если иное не согласовано; +- получать плейлист и режим воспроизведения из внешней конфигурации; +- корректно переживать отсутствующий или повреждённый файл. + +## Наблюдаемая последовательность видео + +Приблизительная временная последовательность 32-секундного ролика: + +- 0–13 секунд — домашний экран, анимация НЛО/луча и промо-области; +- 14–18 секунд — экран оплаты наличными; +- 19–20 секунд — возврат на домашний экран; +- около 21 секунды — короткий фоновой переход с НЛО; +- около 22 секунд — выбор суммы оплаты картой; +- около 23 секунд — ввод произвольной суммы; +- 24–27 секунд — ожидание прикладывания карты; +- 28–32 секунды — ошибка оплаты с анимированным маскотом. + +Переходы преимущественно быстрые и не должны задерживать пользователя. Фоновая анимация сохраняет визуальную непрерывность между экранами. + +## Требуемые данные конфигурации + +На основании референсов в конфигурацию необходимо добавить: + +- ориентацию и целевой viewport; +- название/бренд автомата; +- телефон техподдержки; +- цену жетона; +- предустановленные суммы оплаты картой; +- минимальную, максимальную и кратную сумму; +- бонусные правила; +- начальное бинарное состояние `Enough/Low` для mock-режима; +- включённые способы оплаты; +- тексты подсказок; +- плейлист промо-роликов и fallback-постер; +- параметры показа логотипа и брендовых элементов. + +## Требуемые события контроллера + +Протокол оборудования должен позволять получить или инициировать: + +- состояние запаса «много/мало»; при отсутствии сигнала приложение использует техническое состояние `Unknown`; +- принятую наличную сумму и обновление баланса; +- состояние купюро- и монетоприёмника; +- начало карточной оплаты на выбранную сумму; +- успешный, отклонённый и отменённый результат оплаты; +- начало выдачи, прогресс и подтверждённое количество выданных жетонов; +- аппаратные ошибки и состояние связи. + +## Подтверждённая аппаратная разводка + +`IN8` — сервисная кнопка, `IN1` и `IN4` — active-low датчики уровня первого и второго хопперов, `IN24` и `IN25` — датчики выдачи первого и второго хопперов. Оба канала работают: первый использует `30X`, второй — `40X`. Выдача и пересчёт подтверждаются строками платы, поэтому физические входы не создают двойной программный учёт. + +## Неподтверждённые вопросы + +- Фактическое разрешение и физический размер экрана. +- Является ли цена 10 рублей рабочей или демонстрационной. +- Финальные правила бонусных жетонов. +- Возможность возврата наличных и выдачи сдачи. +- Точная роль кнопки «Выдать» на домашнем экране. +- Формат взаимодействия с банковским терминалом через контроллер. +- Финальные бренд, логотип, персонаж, телефон и права на референсные ассеты. +- Требования к форматам промо-роликов, плейлисту и звуку. +- Визуальный сценарий успешной оплаты и частичной выдачи. diff --git a/docs/THEME_DLC.md b/docs/THEME_DLC.md new file mode 100644 index 0000000..e07ee89 --- /dev/null +++ b/docs/THEME_DLC.md @@ -0,0 +1,484 @@ +# Внешние DLC-темы Exchanger + +## Архитектура + +Основной проект Exchanger не содержит редактируемых ресурсов тем. В нём остаются только: + +- `BuiltInFallbackTheme` — единственная минимальная тема, создаваемая кодом; +- `VendingThemeDefinition` — runtime-представление уже загруженной темы; +- `ThemeDlcLoader` и валидатор manifest; +- `ThemeManager`, выбирающий fallback либо один внешний пакет при запуске. +- `ThemeBindableScreen` и `ThemeBindingResolver`, связывающие app-owned логику с визуальными + сценами DLC по стабильным binding-id. + +Все исходники визуальных тем находятся в соседнем проекте `../ExchangerThemeDlcBuilder/`. В Exchanger отсутствуют `themes/`, исходные `.tres`-темы, фоновые картинки и шаблоны их разработки. + +## Путь из пользовательских файлов + +Монтажный способ выбора темы задаётся в `user://config/technical_settings.toml`: + +```toml +[theme] +enabled = true +directory = "user://theme_dlc" +file_name = "active_theme" +``` + +Путь собирается как `/.pck`; расширение в `file_name` не указывается. +Разрешены `user://` и абсолютный локальный каталог, включая Linux-путь вроде +`/opt/exchanger/themes`. Если optional раздел `[theme]` отсутствует в старом TOML версии 1, +используется прежняя настройка из `appsettings.json`: + +Для Windows разрешены `directory = 'D:\Exchanger\themes'` (literal TOML-строка без +экранирования), `directory = "D:/Exchanger/themes"` либо двойные обратные слеши внутри обычной +двойной строки. + +Настройка хранится в `%APPDATA%\Godot\app_userdata\Exchanger\config\appsettings.json`. Значение по умолчанию: + +```json +{ + "Themes": { + "ReducedEffects": false, + "ExternalDlcEnabled": true, + "ExternalDlcPath": "user://theme_dlc/active_theme.pck" + } +} +``` + +На Windows этот `user://` соответствует `%APPDATA%\Godot\app_userdata\Exchanger\theme_dlc\active_theme.pck`. Также разрешён полный абсолютный путь. Относительные пути и `res://` отклоняются. Технический TOML имеет приоритет над JSON, а разовые `--theme-dlc=D:\ExchangerThemes\active_theme.pck` и `--no-theme-dlc` — над TOML. + +В debug-сборке эти параметры доступны во вкладке `F10 → Тема`. Корректный путь разрешено +сохранить до появления пакета: при следующем запуске отсутствующий файл безопасно оставит +встроенную тему. Включение DLC и изменение пути применяются только после перезапуска. +`ReducedEffects` имеет немедленный предварительный просмотр; кнопка «Отменить» возвращает +сохранённое значение. + +## Формат пакета + +DLC является доверенным Godot resource pack `.pck`: + +```text +res://exchanger_theme_dlc/ +├── manifest.json +├── ui_theme.tres +├── background.png|webp|jpg|svg # необязательно, только legacy-композиция +├── background_decoration.tscn # необязательно, только legacy-композиция +├── components/ # необязательные theme-owned runtime-компоненты +│ └── interactive_pet.tscn # рекомендуемое имя сцены питомца +├── visuals/ # необязательные runtime-сцены экранов +├── scripts/ # GDScript темы +├── contracts/ # обязательно для manifest v2 +│ └── screen_bindings.v2.json +└── scenes/ # обязательно для manifest v2 + ├── screen_home.tscn + ├── screen_cash_payment.tscn + ├── screen_card_amount.tscn + ├── screen_card_custom_amount.tscn + ├── screen_card_terminal.tscn + ├── screen_success.tscn + ├── screen_error.tscn + ├── screen_service_access.tscn + └── screen_settings.tscn +``` + +Manifest версии 1: + +```json +{ + "Format": "ExchangerThemeDlc", + "FormatVersion": 1, + "ThemeId": "sample-theme", + "DisplayName": "Название темы", + "UiThemePath": "res://exchanger_theme_dlc/ui_theme.tres", + "BackgroundTexturePath": "res://exchanger_theme_dlc/background.svg", + "BackgroundDecorationPath": "res://exchanger_theme_dlc/background_decoration.tscn", + "BackgroundDecorationScale": 1.0, + "InteractivePetScene": "res://exchanger_theme_dlc/components/interactive_pet.tscn", + "VisualSlots": { + "home.top": "res://exchanger_theme_dlc/visuals/home_top.tscn", + "card.terminal": "res://exchanger_theme_dlc/visuals/card_terminal.tscn" + }, + "FallbackColor": "#061229", + "UseNearestTextureFilter": false +} +``` + +Версия 1 остаётся совместимой и меняет стили, фон и visual slots встроенных экранов. Для новой +темы следует использовать manifest версии 2: он передаёт теме всё видимое дерево каждого экрана. + +```json +{ + "Format": "ExchangerThemeDlc", + "FormatVersion": 2, + "ThemeId": "sample-theme", + "DisplayName": "Название темы", + "UiThemePath": "res://exchanger_theme_dlc/ui_theme.tres", + "InteractivePetScene": "res://exchanger_theme_dlc/components/interactive_pet.tscn", + "ScreenScenes": { + "screen.home": "res://exchanger_theme_dlc/scenes/screen_home.tscn", + "screen.cash_payment": "res://exchanger_theme_dlc/scenes/screen_cash_payment.tscn", + "screen.card_amount": "res://exchanger_theme_dlc/scenes/screen_card_amount.tscn", + "screen.card_custom_amount": "res://exchanger_theme_dlc/scenes/screen_card_custom_amount.tscn", + "screen.card_terminal": "res://exchanger_theme_dlc/scenes/screen_card_terminal.tscn", + "screen.success": "res://exchanger_theme_dlc/scenes/screen_success.tscn", + "screen.error": "res://exchanger_theme_dlc/scenes/screen_error.tscn", + "screen.service_access": "res://exchanger_theme_dlc/scenes/screen_service_access.tscn", + "screen.settings": "res://exchanger_theme_dlc/scenes/screen_settings.tscn" + }, + "VisualSlots": {}, + "FallbackColor": "#061229", + "UseNearestTextureFilter": true +} +``` + +`UiThemePath` обязателен. Фон и декорация могут быть пустыми строками. +`UseNearestTextureFilter` необязателен и по умолчанию равен `false`. Его следует включать +только для pixel-art тем; тогда приложение применяет nearest-фильтрацию к фону и Control-узлам, +не меняя глобальные настройки рендера для других тем. +`BackgroundDecorationScale` необязателен, по умолчанию равен `1.0` и допускает значения 0.1–4.0. +Он нужен только для decoration, подготовленной не в координатах host 720×1280. + +`InteractivePetScene` необязателен. Он указывает на `PackedScene` внутри +`res://exchanger_theme_dlc/`; рекомендуемый путь — `components/interactive_pet.tscn`, но manifest +может объявить любое другое имя сцены внутри package. Exchanger безопасно проверяет namespace, +расширение и наличие ресурса, загружает сцену в `VendingThemeDefinition.InteractivePetScene`, но +показывает её на всех экранах, кроме `screen.settings`, для которых тема предоставила корректный +навигационный граф. Актуальный Builder требует такой граф в каждой из восьми non-settings сцен +темы с питомцем; host сохраняет совместимость со старыми пакетами и скрывает питомца только на +конкретной сцене без графа. +Обычная навигация и ввод остаются app-owned, а сцена питомца, анимации, размеры и геометрия +доступных поверхностей — theme-owned. Для уникальной многошаговой реакции тема может временно +управлять экранной опорной точкой через scoped runtime, не получая ссылок на внутренние узлы host. + +Корень компонента питомца — `Node2D`. Нейтральный API состоит из методов +`get_pet_animation_names`, `get_pet_animation_frame_count`, `has_pet_animation`, +`play_pet_animation`, `pause_pet_animation`, `stop_pet_animation`, +`get_current_pet_animation`, `get_current_pet_frame` и сигналов `pet_animation_started` / +`pet_animation_completed`. Имена и количество анимаций определяет тема. Сцена напрямую ссылается +на свои ресурсы, поэтому каталог текстур может называться как угодно и не входит в контракт. + +Для поведения тема дополнительно может реализовать методы `get_pet_action_animation`, +`get_pet_runtime_scale`, `get_pet_walk_speed`, `get_pet_climb_speed`, `get_pet_hit_size` и +`get_pet_ground_offset`. Первый метод сопоставляет нейтральные действия приложения с +фактическими именами клипов конкретной темы; в том числе `sit` для посадки после приземления. +Это сохраняет совместимость с уже выпущенными DLC. + +Во время обычного падения host запрашивает действие `drop`, после контакта с объявленной +поверхностью — один полный цикл `landing`, а затем включает `idle`. Даже если при смене экрана +anchor уже совпадает с новой поверхностью, состояние `landing` не пропускается. Если старая тема +не содержит mapping или клип `landing`, host выдерживает безопасную фазу `Landing` в 0,5 секунды +и пишет предупреждение вместо немедленного перехода к `idle`. `celebrate` запускается при переходе +к клиентской выдаче жетонов: host последовательно проигрывает четыре полных цикла. Если тема не +содержит его, для обратной совместимости используется `interact`. Длительность цикла определяется +обязательным `get_pet_animation_frame_count` и optional `get_pet_animation_frames_per_second`; при +отсутствии корректной скорости действует безопасный fallback. Запрошенное во время `falling` или `landing` +празднование ждёт завершения приземления и только затем начинает первый цикл. + +После завершения обычного маршрута host выбирает паузу независимо от темы: с вероятностью 35% +он показывает `idle` на 3–5 секунд, в остальных случаях — спокойный `sitting` на 1,5–3,5 секунды. +Темы без `sitting` остаются совместимыми: в этой ветке используется `idle`. + +Необязательный составной контракт позволяет теме самой выполнить действие из нескольких клипов, +визуальных преобразований и перемещений. Он принимается только целиком: методы +`has_pet_composite_action`, `start_pet_composite_action`, `cancel_pet_composite_action` и сигналы +`pet_composite_action_started` / `pet_composite_action_finished`. При отсутствии или неполной +реализации Exchanger использует одиночную анимацию с тем же каноническим именем. + +`start_pet_composite_action(action, runtime, parameters)` возвращает run id переданного runtime. +Для `interact` параметры содержат `action_repetitions` (1–16) и `reduced_effects`. Scoped runtime +даёт методы `GetRunId`, `IsActive`, `GetViewportRect`, `GetAnchor`, `GetHighestSupport`, +`SetMotionPolicy`, `SetAnchor`, `MoveAnchor` и `LandOnSupport`. Политика отдельно управляет обычной +навигацией (`suspended`/`theme_driven`), контактами с опорами (`ignore`, `solid`, +`after_vertical_wrap`), границами (`clamp`, `allow`, `wrap_vertical_once`) и пользовательским +вводом. Для посадки тема указывает `landing_surface_id`; host проверяет, что такая поверхность +существует и сейчас доступна. + +Каждый runtime привязан к одному запуску. Смена экрана/темы, начало drag и конфликтующее действие +инвалидируют его; последующие команды старого runtime отклоняются. После сигнала успешного +завершения host возвращает обычное состояние Sitting. Поэтому GDScript темы обязан проверять +`IsActive()` после каждого `await`, корректно обрабатывать `cancel_pet_composite_action` и не +сохранять runtime для будущих запусков. + +Маршруты задаются отдельными невидимыми metadata-маркерами внутри каждой готовой сцены, кроме +`screen.settings`: + +- один root с `exchanger_pet_navigation_root = true`, версией, `Rect2` границами и id + поверхности по умолчанию; +- поверхности с уникальным id, диапазоном X, координатой опорной точки Y и необязательными + точками посадки; +- двунаправленные рёбра подъёма с id исходной/целевой поверхности, X края и двумя Y. + +Поверхность может дополнительно объявить строковую metadata +`exchanger_pet_surface_visibility_binding_id`. Она должна ссылаться на `CanvasItem` этой же +экранной сцены по `exchanger_binding_id`. Если готовый визуальный элемент скрыт пользовательской +настройкой, host исключает такую поверхность и все связанные с ней рёбра из активного графа. + +Все координаты описывают экранную опорную точку питомца в системе 720×1280. Host не вычисляет +поверхности из имён или геометрии `Control` и не меняет визуалы темы. Он ходит по объявленным +поверхностям, строит путь по рёбрам, поднимается и спускается у заданных краёв, а после +перетаскивания первым пальцем или зажатой ЛКМ сажает питомца на ближайшую нижнюю поверхность. +На каждом ненулевом участке подъёма или спуска host выбирает случайную точку между 20% и 80% +пути, приостанавливает в ней перемещение и последовательно запрашивает действия +`climbing_action_start`, `climbing_action` и `climbing_action_stop`. Средняя анимация выполняется +один полный цикл, после чего питомец продолжает тот же маршрут и направление. Последовательность +включается только при наличии всех трёх действий и клипов; тема без любого из них сохраняет +обычное непрерывное движение для обратной совместимости. +При переключении экрана host выбирает граф новой сцены, сохраняет текущую экранную позицию +питомца и запускает `falling` до её поверхности по умолчанию; после посадки доступен весь новый граф. +На `screen.settings` питомец скрыт, а его сохранённая позиция используется при выходе из настроек. +`hanging` действует только пока пользователь удерживает питомца, а `falling` — во время его падения +к выбранной поверхности после отпускания. +Режим reduced-effects отключает автономное блуждание, сохраняя явное взаимодействие и drag. + +Новые темы используют самодостаточную композицию экранов. В этом режиме каждый root из +`ScreenScenes` имеет metadata `exchanger_self_contained_visuals = true`, назначенный `Theme` и +два прямых дочерних узла: `ThemeBackground` типа `TextureRect` с текстурой и +`BackgroundDecoration` типа `CanvasItem`. Все девять сцен пакета обязаны выбрать одинаковый +режим. `BackgroundTexturePath` и `BackgroundDecorationPath` при этом оставляют пустыми, иначе +приложение отклонит DLC как дублирующую визуальную композицию. Смешивать самодостаточные и +legacy-сцены в одном пакете также нельзя. + +После инстанцирования host сохраняет присутствующее визуальное дерево самодостаточной сцены в том +виде, в каком оно собрано в Theme Builder. Он не назначает другой `Theme`, `ThemeTypeVariation`, +размеры, отступы или локальные theme overrides. Разрешены функциональные операции через +binding-id: подключение сигналов, обновление данных, видимости, доступности и состояния. Если +обязательного binding-id нет, host сначала принимает совместимый узел старой темы по закреплённому +`FallbackPath`, а при отсутствии самого узла переносит на его место готовый элемент встроенной +fallback-сцены с её оформлением. Внешние элементы, у которых binding-id присутствует, не меняются. + +Для управления видимостью Home приложение использует готовые bindings +`home.scroll.content.stock_status`, `home.scroll.content.advertisement_panel` и необязательный +`home.decoration.custom_text_block`. Последний объединяет theme-owned фон пользовательской +речевой плашки и персонажа справа; для старых тем без этой группы сохранён fallback +`home.decoration.right_character`. Экран Settings предоставляет готовую +панель `settings.scroll.content.menu_visibility_panel` и три `CheckButton` с окончаниями +`show_stock_status`, legacy `show_right_character` (пользовательский текст и персонаж) и +`show_promotion_block`. Host только читает состояния +переключателей и меняет `Visible` соответствующих готовых элементов. + +Фиксированный футер Settings задаётся supplemental bindings `settings.footer` и +`settings.footer.save_and_exit_button`; он является корневым соседом `SafeMargin`, а не потомком +`settings.scroll`. В конец прокручиваемого `Content` добавляется +`settings.scroll.content.footer_clearance`, чтобы нижние поля не перекрывались футером. Все три +узла обязательны для новых тем; в уже выпущенной теме без этих ID host переносит готовый футер и +зазор встроенной темы, не переоформляя остальные элементы DLC. Старый полноэкранный Scroll при +этом может проходить под непрозрачным футером; `footer_clearance` позволяет прокрутить последние +поля выше него без изменения геометрии выпущенной сцены. + +Сервисный переключатель учёта использует supplemental binding +`settings.scroll.content.service_inventory_panel.margin.content.inventory_enabled` типа +`CheckButton`; независимый переключатель ограничения покупки — +`settings.scroll.content.service_inventory_panel.margin.content.purchase_limit_enabled` того же +типа. Изменяемое пояснение рядом с ними — +`settings.scroll.content.service_inventory_panel.margin.content.description` типа `Label`. +При выключении host меняет только функциональные `Visible`, `Disabled`, `ButtonPressed` и текст +готовых элементов этой панели. Старые PCK без metadata получают совместимые узлы по каноническим +fallback-путям; закреплённый JSON-каталог остаётся на 481 binding. + +На всех пользовательских экранах, кроме Home и Settings, предусмотрена готовая кнопка +`home_navigation_button` с изображением дома. Его основа — `KeypadButton`; в `space-pixel` этот +вариант использует готовый `assets/ui/button_square.png`. На CashPayment, CardAmount, CardCustomAmount и +CardTerminal она расположена рядом с `BackButton`; на Success, Error и ServiceAccess занимает +обычную верхнюю левую позицию. Host только подписывается на `pressed`: незавершённую оплату он +безопасно отменяет, а на Success до завершения фактической выдачи кнопка недоступна. Новые темы +обязаны объявить семь соответствующих supplemental ID; старые PCK получают готовые fallback-узлы +из встроенных сцен. + +Тексты нижних анимированных плашек с НЛО на CashPayment, CardAmount, CardCustomAmount и +CardTerminal настраиваются в разделе «Общие» через готовую панель темы +`settings.scroll.content.animated_banner_texts_panel`. Текст CashPayment выводится в +`cash_payment.content.banner_text`; для таймера CardTerminal в шаблоне нужно оставить +`{seconds}`, которое host заменяет количеством оставшихся секунд. Эти два новых supplemental ID +не изменяют immutable JSON-каталог; старой DLC-теме host подставляет встроенные узлы. + +`VisualSlots` — необязательный словарь именованных `PackedScene`. Поддерживаемые host-слоты: + +| Slot | Область preview | +|---|---| +| `home.top` | НЛО и реплика на главном экране | +| `home.advertisement` | тематическая рамка промо-блока | +| `cash.instructions` | купюра и монета | +| `cash.tip` | маскот и предупреждение о сдаче | +| `card.terminal` | анимация карты у терминала | +| `result.success` | анимация успешной выдачи | +| `result.error` | анимация ошибки | + +Сцены слотов располагаются в нативной системе координат 720×1280 либо в локальном размере +соответствующего контейнера. Они не заменяют интерактивные узлы приложения: суммы, состояния, +кнопки и переходы всегда принадлежат host. + +## Полносценовый контракт v2 + +Приложение всегда инстанцирует собственный C#-контроллер экрана, содержащий бизнес-логику, +навигацию и обращения к оборудованию. До входа контроллера в SceneTree его встроенный визуальный +корень `SafeMargin` заменяется сценой из DLC. Поэтому тема полностью определяет композицию и +вложенность `Control`, но не получает доступ к оплате, COM-порту или состоянию сессии. + +Имена файлов, ключи `ScreenScenes` и имена корневых узлов фиксированы: + +| Scene binding | Файл | Имя root | +|---|---|---| +| `screen.home` | `screen_home.tscn` | `ThemeScreen_Home` | +| `screen.cash_payment` | `screen_cash_payment.tscn` | `ThemeScreen_CashPayment` | +| `screen.card_amount` | `screen_card_amount.tscn` | `ThemeScreen_CardAmount` | +| `screen.card_custom_amount` | `screen_card_custom_amount.tscn` | `ThemeScreen_CardCustomAmount` | +| `screen.card_terminal` | `screen_card_terminal.tscn` | `ThemeScreen_CardTerminal` | +| `screen.success` | `screen_success.tscn` | `ThemeScreen_Success` | +| `screen.error` | `screen_error.tscn` | `ThemeScreen_Error` | +| `screen.service_access` | `screen_service_access.tscn` | `ThemeScreen_ServiceAccess` | +| `screen.settings` | `screen_settings.tscn` | `ThemeScreen_Settings` | + +Root каждой сцены — `Control` с metadata `exchanger_screen_binding_id`, равной ключу из таблицы. +Интерактивные и динамические узлы получают уникальную metadata `exchanger_binding_id`. +Пример кнопки наличной оплаты: + +```text +exchanger_binding_id = "home.scroll.content.payment_panel.margin.content.buttons.cash_button" +``` + +Binding-id вычисляется из стабильного fallback NodePath: префикс `SafeMargin/` удаляется, +каждый оставшийся сегмент переводится из PascalCase в snake_case, перед ним добавляется ключ +экрана. Фактическое положение узла в тематической сцене на binding-id не влияет. Точный +машиночитаемый каталог находится в `../ExchangerThemeDlcBuilder/contracts/screen_bindings.v2.json`, +а готовый шаблон — в `../ExchangerThemeDlcBuilder/themes/example/`. Preview-overlay является +инструментом Builder и не входит в production-сцены. + +Manifest v2 обязан включать точную копию каталога в +`res://exchanger_theme_dlc/contracts/screen_bindings.v2.json`. Приложение закрепляет SHA-256 +этого файла и проверяет девять экранов. Для присутствующих биндингов проверяются ID и Godot-тип; +неизвестные ID, дубли и неверные типы отклоняются. Отсутствующий обязательный ID не отключает весь +DLC: он разрешается через канонический `FallbackPath` из закреплённого каталога. Если точечная +подстановка невозможна, встроенная сцена используется только для проблемного экрана. Корневой +контракт сцены, self-contained композиция и подлинность каталога остаются строгими. + +Все присутствующие визуальные узлы принадлежат теме. Приложение не переделывает их стили или +компоновку: оно находит узлы по binding-id, подключает сигналы и обновляет функциональные значения. +Единственное исключение — отсутствующий обязательный узел: для обратной совместимости на его +каноническое место переносится готовый элемент встроенной темы-заглушки. + +Для итогов наличной оплаты предусмотрены три независимых обязательных `Label`: + +- `cash_payment.content.summary.margin.values.balance` получает только внесённую сумму в рублях; +- `cash_payment.content.summary.margin.values.tokens` получает базовое количество жетонов; +- `cash_payment.content.summary.margin.values.bonus` получает бонус в формате + `+ N ЖЕТОНОВ\nВ ПОДАРОК` либо `БЕЗ БОНУСА`. + +Контроллер вычисляет жетоны через общую `PricingPolicy`, заполняет все три узла и не объединяет +значения в одну строку. Геометрия, перенос строк, выравнивание и оформление остаются частью темы. + +Панель «К ВЫДАЧЕ» на экране готовых карточных сумм использует существующий обязательный Label +`card_amount.content.reward_panel.content.value` только для базового количества жетонов. Бонус +выводится отдельно через supplemental runtime binding +`card_amount.content.reward_panel.content.bonus` типа `Label` с каноническим fallback-путём +`SafeMargin/Content/RewardPanel/Content/Bonus`. Формат совпадает с наличной оплатой: +`+ N ЖЕТОНОВ\nВ ПОДАРОК` либо `БЕЗ БОНУСА`. Supplemental ID не входит в закреплённый JSON-каталог +481 binding; старая тема получает готовый встроенный Label побиндинговым fallback. + +На экране ручной карточной суммы введённое число выводится отдельно через обязательный Label +`card_custom_amount.content.keypad_panel.content.input_value`. Верхние Label +`...amount_panel.margin.values.amount` и `...tokens` получают соответственно базовые и бонусные +жетоны; второй Label использует тот же двухстрочный формат либо текст `БЕЗ БОНУСА`. Таким образом +верхняя панель не содержит рублей, а поле под «ВВЕДИТЕ СУММУ» всегда отражает фактически набранное +значение. + +Изменяемые списки представлены заранее созданными фиксированными слотами: 16 кнопок сумм, +16 правил дополнительных жетонов, 16 сумм оплаты и 12 промо-роликов. Неиспользуемые слоты +скрыты. Home аналогично содержит готовые узлы состояния запаса, связи, постера, видео и +резервного текста. Благодаря этому внешний вид полной актуальной темы совпадает с предпросмотром; +дерево дополняется только при отсутствии обязательного binding в старом пакете. + +Строка запаса Home состоит из готовых узлов темы: текстового состояния слева, полоски по центру +и Label приблизительного общего остатка справа. Для последнего используется supplemental +runtime binding home.scroll.content.stock_status.approximate_count; приложение меняет только +его Text и скрывает Label при отключённом учёте. В Settings, напротив, сервисная панель получает +точное учётное количество, а при отключённом учёте скрывает остатки, пересчёт и пополнение. + +Экран Settings дополнительно содержит две готовые панели `KeyboardOverlay`: текстовую и цифровую. +Они дают 57 обязательных биндингов: 33 символьные клавиши, 10 цифр, две кнопки скрытия и +12 служебных действий. Панели по умолчанию скрыты, все их кнопки имеют `focus_mode = None`, +чтобы нажатие не отнимало каретку у редактируемого поля. Host подключает `Pressed` и меняет только +`Visible`, `Text`, `Disabled` и `ButtonPressed`; создание, перестановка и стилизация узлов runtime +запрещены. В preview Builder предусмотрены состояния `KEYBOARD: OFF/TEXT/NUM`. + +## Семантический UI-контракт + +Runtime применяет один `Theme` ко всем девяти экранам, включая `ServiceAccess` и `Settings`. +Тема может оформлять следующие стабильные type variations: + +| Variation | Базовый Godot-тип | Назначение | +|---|---|---| +| `ScreenTitle` | `Label` | главный заголовок экрана | +| `ScreenDescription` | `Label` | пояснение под заголовком | +| `PanelTitle` | `Label` | заголовок панели | +| `PanelText` | `Label` | крупное содержимое пользовательской панели | +| `FieldLabel` | `Label` | подпись или обычный текст поля настроек | +| `SupportText` | `Label` | подсказка и вторичный текст | +| `StatusText` | `Label` | текущее состояние операции или оборудования | +| `WarningText` | `Label` | предупреждение | +| `ErrorText` | `Label` | ошибка валидации или операции | +| `PrimaryButton` | `Button` | главное действие | +| `CompactButton` | `Button` | цифровая клавиша или компактное действие | +| `BackButton` | `Button` | компактный возврат с пользовательского экрана | +| `SectionTabButton` | `Button` | вкладка сервисных настроек | +| `SecondaryButton` | `Button` | отмена, закрытие или сброс | +| `DangerButton` | `Button` | удаление/необратимое действие | +| `WhitePanel` | `PanelContainer` | основная смысловая панель | +| `AdvertisementPanel` | `PanelContainer` | контейнер постера, текста или промо-ролика OGV/MP4/MOV/M4V | +| `FooterPanel` | `PanelContainer` | техподдержка и служебный footer Home | +| `StatusPanel` | `PanelContainer` | компактный индикатор связи/состояния | + +Host всегда регистрирует базовый тип каждой variation. Поэтому старый корректный DLC v1, +в котором новый семантический тип ещё не оформлен, наследует безопасный стандартный стиль и +остаётся совместимым. + +Экран настроек дополнительно использует базовые классы `LineEdit`, `SpinBox`, `OptionButton`, +`CheckButton`, `HSlider`, `VScrollBar` и `HScrollBar`. Полноценная тема должна явно задавать их +normal/focus/pressed/disabled-состояния и сохранять читаемость внутри `WhitePanel`. + +## Доверенное выполнение и fallback + +- Пакет монтируется с `replace_files=false` и не может заменить ресурсы Exchanger. +- Все пути manifest обязаны находиться внутри `res://exchanger_theme_dlc/`; `..`, обратные слеши и ссылки на сцены приложения запрещены. +- Decoration, visual slots и полносценовые view могут содержать GDScript и любые стандартные + runtime-узлы Godot. Код начинает исполняться при инстанцировании сцены. +- Проверяются формат, версия, ThemeId, цвет, расширения, существование и тип каждого ресурса. +- Для manifest v2 проверяются закреплённый каталог биндингов, namespace, дубли и типы присутствующих + узлов. Неизвестный либо неверно типизированный биндинг отключает DLC; отсутствующий обязательный + биндинг восстанавливается по `FallbackPath` встроенным элементом. +- Самодостаточная сцена дополнительно проверяется на собственный `Theme`, текстурированный + `ThemeBackground` и `BackgroundDecoration`; смешанный режим девяти сцен и одновременное + объявление глобального фона или decoration запрещены. +- При отсутствии, повреждении или несовместимости DLC приложение продолжает запуск со встроенной fallback-темой. +- В журнал не записывается полный пользовательский путь к DLC. +- Одновременно загружается не более одного пакета. После замены `.pck` приложение нужно перезапустить. + +## Runtime-возможности темы + +В legacy-композиции `BackgroundTexturePath` задаёт общий фон, а `BackgroundDecorationPath` может +ссылаться на произвольную доверенную `PackedScene`. В самодостаточной композиции те же роли +выполняют `ThemeBackground` и `BackgroundDecoration` внутри каждой сцены. + +Разрешены GDScript, сигналы, `Timer`, `Tween`, `AnimatedSprite2D`, `AnimationPlayer`, method tracks, +аудио, видео, частицы, шейдеры, процедурная графика, сетевые и файловые API Godot. Host не +применяет лимиты количества узлов, кадров, FPS или скорости анимации и не ограничивает размер PCK. + +При `ReducedEffects=true` глобальная decoration не создаётся, а узел `BackgroundDecoration` +самодостаточного экрана скрывается и перестаёт обрабатываться. Остальная скриптовая логика сцены +продолжает работать; тема при желании может самостоятельно учитывать эту настройку. + +## Разработка и сборка + +Откройте соседний `ExchangerThemeDlcBuilder/project.godot` в Godot 4.7.1. После редактирования выполните: + +```powershell +powershell -ExecutionPolicy Bypass -File .\build-theme.ps1 -ThemeId space-pixel +``` + +Пакет появится в `build/space-pixel.pck`; совместимая копия будет записана в +`build/active_theme.pck`. Для одновременной установки в стандартный пользовательский путь: + +```powershell +powershell -ExecutionPolicy Bypass -File .\build-theme.ps1 -ThemeId space-pixel -InstallToDefaultUserPath +``` + +Сборщик проверяет, что запущен настоящий Godot 4.7, а не MCP-сервер `godot-ai`. Сборка DLC не требует C#-кода или ссылки на проект Exchanger. diff --git a/docs/architecture/decisions.md b/docs/architecture/decisions.md new file mode 100644 index 0000000..8c13adc --- /dev/null +++ b/docs/architecture/decisions.md @@ -0,0 +1,182 @@ +# Архитектурные решения Exchanger + +Дата первичной фиксации: **2026-08-20**. + +Документ хранит решения, которые определяют границы подсистем и не должны заново пересматриваться без явной причины. Неизвестные параметры будущего оборудования не заполняются предположениями: они оформляются как входные данные соответствующего этапа интеграции. + +## DEC-001. Универсальность до появления целевого оборудования + +Статус: **принято**. + +Целевой ПК, GPU, тач-контроллер и точная версия Windows пока отсутствуют. До получения реального аппарата приложение разрабатывается без привязки к конкретной модели оборудования: + +- базовый рендерер — Godot Mobile (Vulkan): это требуется runtime-расширением Native Video для + MP4/MOV/M4V; UI сохраняет логический пиксельный viewport и nearest-фильтрацию; +- UI использует логический портретный viewport 720×1280 — тот же, что и theme-preview; на панели другого размера применяется `canvas_items/expand`; +- размеры, таймауты, тарифы, аппаратный транспорт и контент задаются конфигурацией; +- ввод поддерживает тач и мышь без функций, доступных только по hover; +- код не полагается на конкретный DPI, частоту обновления, GPU или имя COM-порта; +- тяжёлые необязательные элементы должны отключаться конфигурацией; +- фактическое железо позже добавляется как профиль проверки, а не как основание для переработки UI и бизнес-логики. + +Следствие: отсутствие целевого оборудования не блокирует интерфейс, mock-сценарии и основную архитектуру. Финальная проверка производительности и эксплуатации остаётся обязательной после появления устройства. + +## DEC-002. Граница аппаратной интеграции + +Статус: **принято**. + +Приложение взаимодействует с автоматом только через абстракцию `IHardwarePort` и типизированный слой протокола. UI и `SessionController` не открывают COM-порт, не знают wire-формат сообщений и не обращаются напрямую к купюроприёмнику, монетоприёмнику, банковскому терминалу или диспенсеру. + +До появления документации контроллера используется `MockHardwarePort`. Реальный COM-транспорт подключается позднее отдельным адаптером без изменения экранов. + +## DEC-003. Протокол контроллера не проектируется заранее + +Статус: **принято**. + +Список команд и документация контроллера будут добавлены в `references/` на более позднем этапе. До этого запрещено придумывать окончания строк, кодировку, heartbeat, названия команд, ответы, идентификаторы операций и семантику ошибок. + +После появления документации: + +1. На Этапе 3 создаётся версия внутреннего документа протокола и типизированный адаптер. +2. Команды и события проверяются по документации и примерам реального обмена. +3. На Этапе 4 подключается реальный Windows COM-транспорт. +4. Любая неподтверждённая возможность контроллера остаётся недоступной, а не имитируется в production. + +Это входная зависимость Этапов 3–4, но не незавершённая задача Этапа 0. + +## DEC-004. Контроллер — единственный источник аппаратных событий + +Статус: **принято**. + +Контроллер сообщает ПК все сведения об аппаратуре по протоколу из будущей документации. В их число по потребности сценария входят: + +- связь и готовность контроллера; +- запас жетонов; +- принятая наличная сумма и состояние приёмников; +- результат карточной оплаты; +- начало, прогресс и результат выдачи; +- отмена, таймауты и аппаратные ошибки. + +Конкретный набор сообщений и их wire-формат определяются только документацией контроллера. На стороне приложения они преобразуются в типизированные события, с которыми работает `SessionController`. + +## DEC-005. Статический фон и отдельные анимированные спрайты + +Статус: **заменено DEC-009**. + +Фоновая композиция интерфейса статична. Тема предоставляет fallback-цвет и при необходимости неподвижную текстуру. НЛО, маскот и другие движущиеся элементы подключаются отдельной пассивной `PackedScene` с анимированными спрайтами. Фоновые шейдеры, частицы и видео не используются. Промо-ролик является отдельным UI-блоком `HomeScreen`. + +## DEC-006. Проектные инструкции агентов версионируются + +Статус: **принято**. + +Файл `.agents/AGENTS.md` является частью проекта и должен храниться в Git. Это позволяет новым агентам восстановить правила работы, требования к документации, использованию Godot MCP и `agentmemory`. Каталог `.agents/` не исключается через `.gitignore`. + +## DEC-007. Состояние репозитория + +Статус: **принято**. + +Локальный Git-репозиторий инициализирован 2026-08-20. Удалённый репозиторий, стратегия веток и первый коммит на этом этапе не назначаются без отдельного решения владельца проекта. + +## DEC-008. Полные визуальные сцены принадлежат теме, бизнес-логика — приложению + +Статус: **дополнено DEC-009**. + +Новая DLC-тема формата v2 предоставляет полные визуальные сцены всех девяти экранов. Она может +свободно менять композицию и вложенность `Control`, но не содержит исполняемых скриптов и не +обращается к сессии, оплате, настройкам или оборудованию. + +Приложение сохраняет app-owned C#-контроллер каждого экрана. До `_Ready` встроенный визуальный +корень контроллера заменяется сценой DLC, после чего кнопки, поля и динамические области находятся +по metadata `exchanger_binding_id`. Имена файлов, scene binding-id и root-имена зафиксированы +`ThemeSceneContract`; фактические NodePath внутри темы частью runtime-контракта не являются. + +Следствия: + +- встроенные сцены остаются единственным безопасным fallback без внешнего пакета; +- manifest v1 продолжает работать как стилевой DLC без замены сцен; +- manifest v2 активируется только полным набором экранов, а не смесью разных тем; +- новые сцены могут быть самодостаточными: root содержит собственный `Theme`, прямой статический + `ThemeBackground` и прямой `BackgroundDecoration`; все девять сцен обязаны использовать один + режим, а глобальные background/decoration пути manifest в нём остаются пустыми; +- host не меняет визуальные свойства самодостаточной сцены после загрузки: запрещены повторное + назначение Theme, type variations, геометрии и theme overrides; контроллеры только находят + готовые узлы по binding-id, подключают события и обновляют функциональные значения; +- визуальные узлы запаса, связи и промо принадлежат сцене темы; приложение находит их по + биндингам, передаёт только состояние и медиаресурсы и не добавляет дочерние Control-узлы; +- production-сцены темы не содержат GDScript/C#; допустимы только данные, стандартные Godot-узлы, + `AnimationPlayer` и `AnimatedSprite2D`; +- точный каталог содержит 481 обязательный биндинг и входит в PCK по каноническому пути; + приложение закрепляет его SHA-256, поэтому DLC не может объявить себе ослабленный контракт; +- небольшой набор supplemental runtime-биндингов проверяется приложением поверх каталога: + состояния полоски запаса, приблизительный остаток на Home и сервисные действия двух хопперов; +- `ReducedEffects` и эксплуатационный бюджет применяются как к прежней глобальной decoration, + так и к `BackgroundDecoration` внутри самодостаточной сцены; +- проект создания тем находится отдельно в `../ExchangerThemeDlcBuilder/themes/`, а единый + каталог — в `../ExchangerThemeDlcBuilder/contracts/screen_bindings.v2.json`. + +## DEC-009. Внешние темы являются доверенным исполняемым кодом + +Статус: **принято**. + +Владелец приложения самостоятельно разрабатывает и устанавливает все PCK-темы; стороннее +распространение пакетов не предполагается. Поэтому Exchanger не ограничивает тему пассивной +графикой и считает всё содержимое `res://exchanger_theme_dlc/` доверенным. + +Следствия: + +- production-сцены, вложенные компоненты, legacy decoration и visual slots могут содержать + GDScript и любые стандартные runtime-узлы Godot; +- разрешены сигналы, method tracks, таймеры, аудио, видео, частицы, шейдеры, процедурная графика, + сетевые и файловые API; +- удалён эксплуатационный decoration budget и ограничение размера PCK; +- manifest v2, девять канонических сцен, 481 binding-id, их типы и закреплённый SHA-256 контракта + остаются обязательными для подключения app-owned C#-логики; +- пакет по-прежнему монтируется с `replace_files=false` и живёт в namespace + `res://exchanger_theme_dlc/`, чтобы его ресурсы имели стабильные пути; +- старое требование статического фона и запрет исполняемых скриптов больше не действуют. + +Скрипт темы исполняется при инстанцировании PackedScene. Контрактная проверка также временно +инстанцирует сцену, поэтому код `_init()` может выполниться до фактического показа экрана; логику, +которой нужен SceneTree, следует размещать в `_ready()`. + +## DEC-010. Первый хоппер имеет строгий приоритет при обычной выдаче + +Статус: **принято**. + +В профиле `DualHopperAuto` приложение строит план по точному программному остатку, а не выбирает +стартовый хоппер по бинарному датчику уровня или по сравнению запасов. Для запроса `N`: + +- из hopper 1 планируется `min(N, остаток hopper 1)`; +- из hopper 2 планируется только разница `N - hopper 1`; +- команда hopper 2 отправляется после подтверждения всех запланированных жетонов hopper 1; +- объём одного пакета ограничен 99 жетонами; при большем объёме пакеты одного хоппера идут + последовательно, и следующий отправляется только после всех `OK` предыдущего (`APPEND=N` + подтверждает лишь постановку в очередь); +- если суммарного учётного остатка меньше `N`, выдача отклоняется до отправки `309N/409N`. + +Бинарные датчики `Low/Enough` продолжают описывать уровень, но не меняют порядок маршрутизации. +Если уже активный хоппер возвращает ошибку или связь теряется, автоматического перехода на другой +хоппер нет: сохраняется at-most-once-политика, учитывается только подтверждённая выдача и операция +завершается безопасной ошибкой. + +## DEC-011. Точный учёт жетонов является отключаемой бизнес-политикой + +Статус: **принято**. + +`AppSettings.TokenInventory.Enabled` отделяет сохранённый точный остаток от бинарных аппаратных +датчиков. `TokenInventory.PurchaseLimitEnabled` независимо определяет, должен ли этот остаток +ограничивать покупку. Оба флага включены по умолчанию ради совместимости. При активном лимите +полное количество к выдаче, включая бонус, проверяется до карточного запроса оплаты и повторно +перед выдачей; наличная ветка проверяется до команды хопперу. + +При включённом учёте и выключенном лимите остаток продолжает отображаться и уменьшаться по +подтверждённой выдаче, но не блокирует оплату. Доступность Home определяется датчиками. В +`DualHopperAuto` записанный остаток hopper 1 используется как первая часть плана, а вся разница +направляется в hopper 2 независимо от его записанного остатка. + +При выключенном учёте `user://data/token_inventory.json` сохраняется, но не читается как лимит +и не уменьшается. Сервисные действия пересчёта/пополнения и числовая индикация скрываются, тогда +как качественное состояние `Low/Enough/Unknown` продолжает определяться датчиками. Для +`DualHopperAuto` запрос направляется в hopper 1 последовательными пакетами до 99 жетонов. +Автоматический переход на другой хоппер после ошибки запрещён прежней at-most-once-политикой. +Перед повторным включением точного учёта оператор должен пересчитать физические остатки. diff --git a/docs/hardware/BOARD_ACCEPTANCE_TESTS.md b/docs/hardware/BOARD_ACCEPTANCE_TESTS.md new file mode 100644 index 0000000..b4da0fe --- /dev/null +++ b/docs/hardware/BOARD_ACCEPTANCE_TESTS.md @@ -0,0 +1,147 @@ +# Аппаратные приёмочные тесты контроллера + +## Назначение + +Проект `tests/Exchanger.HardwareTests` предназначен для проверки реальной платы через Windows USB-COM сразу после её подключения. Он использует те же `SerialPortHardware`, `ControllerAuthenticator`, AES-ключ, parser и `PeripheryMachineController`, что и приложение, поэтому проверяет production-путь, а не отдельную тестовую реализацию. + +Аппаратные тесты включены в solution для проверки компиляции, но без `EXCHANGER_BOARD_TESTS=1` пропускаются. Обычный `dotnet test Exchanger.sln` не открывает COM-порт, не включает приёмники оплаты и не запускает хоппер. + +## Перед запуском + +1. Подключить и запитать контроллер. +2. Узнать его COM-порт в диспетчере устройств Windows. +3. Закрыть Exchanger, терминал производителя и другие программы, которые могут удерживать этот порт. +4. Освободить лоток хоппера и подготовить тестовые деньги только перед интерактивными группами. +5. Начинать с группы `Safe`. + +Все команды ниже выполняются из корня репозитория. Результат каждого запуска сохраняется как TRX в локальном каталоге `artifacts/board-tests/`, который исключён из Git. + +## Безопасная автоматическая проверка + +```powershell +powershell -ExecutionPolicy Bypass -File .\tests\Exchanger.HardwareTests\run-board-tests.ps1 ` + -Port COM5 ` + -Group Safe +``` + +Группа `HardwareSafe` проверяет: + +- открытие порта с профилем 115200 8N1/None; +- аппаратный RTS-reset и полный startup-handshake `periphery controller ver_ → 2000 ms → 07 → CHAL → 08 → RAES → READY!` с production AES-256 ECB/NoPadding и обязательной проверкой proof; `AUTH_PC_OK` и `AUTH_CNT_OK` распознаются как промежуточные кадры, но не заменяют точный `READY!`; +- переходы `Authenticating → Ready → Disconnected`; +- ответ `INPUT` на команду `91`; +- соответствие active-low входу: сигнал на `IN1` (`бит 0`) → `Low`, отсутствие сигнала (`бит 1`) → `Enough`; +- ответы на `140`, `150`, `160`, `3090` и `99` без вывода сырых кадров в отчёт; +- три цикла закрытия, повторного открытия и повторной авторизации; число циклов меняется параметром `-ReconnectCycles` от 1 до 20. + +Привязка кнопок и переходов приложения к `141/142`, `151/152`, `161/162/163`, обязательным +`ASK:*` и пакетным командам `309N` проверяется обычным набором `Exchanger.Tests` через +wire-симулятор. Группа Safe намеренно не включает приём денег и мотор. + +Status-тест намеренно требует хотя бы один ответный не-handshake кадр. Если реальная прошивка не отвечает на команду или формат отличается от документации, тест завершится ошибкой и тем самым зафиксирует несовместимость для корректировки parser/документации. + +На подключённой плате CP210x/COM3 группа `Safe` исторически пройдена 2026-08-27: 9/9 тестов, включая `INPUT`, active-low преобразование `IN1` в типизированный уровень запаса, ответы на status-команды и три повторные авторизации. Эти результаты относятся к прежней прошивке и старым запросам `309?/409?`; актуальный runner использует `3090`, поэтому после подключения обновлённой платы пакет требуется повторить. + +Повторный прогон 2026-08-31 подтвердил новый startup-контракт: отдельный `Probe` прошёл 1/1, +а `Safe` — 8/9. Исторически были успешны авторизация, `INPUT`/`IN1`, `140`, `150`, старый запрос состояния хоппера, `99` и три +reconnect-цикла. Только `160` дважды не получил ответ, поэтому эта проверка остаётся красной до +уточнения наличия/состояния Вендиста или поведения прошивки. Результаты: +`artifacts/board-tests/board-probe-20260831-105348.trx` и +`artifacts/board-tests/board-safe-20260831-104124.trx`. + +Если плата возвращает `CHAL`/`RAES`, но production-проверка proof не проходит, используйте безопасный +фиксированный probe. Он не запускает периферию и не пишет сырые handshake-блоки в отчёт: сравнивает +только семантику proof и короткие SHA-256 fingerprints. + +```powershell +powershell -ExecutionPolicy Bypass -File .\tests\Exchanger.HardwareTests\run-board-tests.ps1 ` + -Port COM5 ` + -Group Probe +``` + +## Кнопка SERVICE, монетник, купюроприёмник и датчик + +Эти тесты ждут ручное действие и не запускаются без `-ConfirmInteractive`. + +```powershell +powershell -ExecutionPolicy Bypass -File .\tests\Exchanger.HardwareTests\run-board-tests.ps1 ` + -Port COM5 ` + -Group Interactive ` + -ConfirmInteractive ` + -CoinRubles 10 ` + -BillRubles 100 ` + -StockInput 1 ` + -ExpectedStock Enough ` + -InteractionTimeoutSeconds 90 +``` + +Во время запуска тест попросит: + +- нажать физическую кнопку `SERVICE`; +- внести одну монету указанного номинала; +- внести одну купюру указанного номинала; +- заранее привести датчик хоппера к ожидаемому состоянию. + +Для проверки обоих сигналов датчика тест запускается дважды: сначала с `-ExpectedStock Enough`, затем после физического изменения уровня с `-ExpectedStock Low`. По умолчанию используется подтверждённая active-low разводка: сигнал на `IN1` (`бит 0`) → `Low`; альтернативная active-high полярность задаётся как `-StockLowWhenHigh:$true`. + +Если конкретная периферия ещё не подключена, соответствующий номинал можно не передавать: такой тест будет отмечен пропущенным, остальные продолжат работу. + +## Реальная банковская операция + +Тест Вендиста может списать реальные деньги и требует отдельного осознанного подтверждения: + +```powershell +powershell -ExecutionPolicy Bypass -File .\tests\Exchanger.HardwareTests\run-board-tests.ps1 ` + -Port COM5 ` + -Group Payment ` + -CardRubles 10 ` + -ConfirmRealPayment ` + -InteractionTimeoutSeconds 120 +``` + +Проверяется команда оплаты, событие `MONEY:CASHLESS:<сумма>`, обязательный `ASK:CASHLESS:<сумма>` и типизированный итог `Approved`. Автоматический возврат денежных средств тест не выполняет. + +## Физическая выдача жетонов + +Тест запускает мотор хоппера и требует отдельного подтверждения: + +```powershell +powershell -ExecutionPolicy Bypass -File .\tests\Exchanger.HardwareTests\run-board-tests.ps1 ` + -Port COM5 ` + -Group Dispense ` + -DispenseCount 2 ` + -ConfirmDispense ` + -InteractionTimeoutSeconds 60 +``` + +За один тест разрешено от 1 до 10 жетонов. Текущий интерактивный runner физически проверяет первый хоппер командой `309N`; production-runtime дополнительно поддерживает второй канал `409N`, который покрыт программными тестами. Перед аппаратной приёмкой двух хопперов runner нужно запускать отдельными явно подтверждёнными сценариями, чтобы один запуск не включал два двигателя неожиданно. + +Прошивочный предел одной пакетной команды — 99 жетонов: приложение не отправляет `309100` или `409100`, на которые плата отвечает ошибками групп 30 и 40. Крупные выдачи обоих каналов проверяются программными тестами как последовательность пакетов максимум по 99. + +Отдельный интерактивный тест прямого мотора пока использует только `301/300` и считает строки `HOPPER1 PULSE=1`. Production-приложение уже поддерживает симметричный пересчёт второго хоппера `401/400 → HOPPER2 PULSE=1`; его физический прогон требует отдельного явного подтверждения владельца. + +Реальный приёмочный runner сохраняет предел 10 за один запуск, чтобы случайная проверка не опустошила хоппер. Многожетонная логика и суммарный partial-result проверяются детерминированно в симуляторе. + +## Отключение USB-кабеля + +```powershell +powershell -ExecutionPolicy Bypass -File .\tests\Exchanger.HardwareTests\run-board-tests.ps1 ` + -Port COM5 ` + -Group Cable ` + -ConfirmCable ` + -InteractionTimeoutSeconds 120 +``` + +После приглашения нужно отключить USB, дождаться сообщения о потере связи и подключить кабель обратно. Тест периодически пытается открыть то же имя COM-порта и требует второй успешный handshake. Если Windows назначит другое имя порта, запуск завершится ошибкой; новый порт следует передать в следующем прогоне. + +## Границы набора + +Набор проверяет все интерфейсы, которые сейчас использует Exchanger. Он специально не отправляет: + +- `00` RESET и команды обновления прошивки; +- произвольные команды силовых выходов `20/21/22`; +- команды световых каналов и конфигурации конкретного автомата; +- автоматический повтор выдачи после обрыва; +- недокументированные команды возврата платежа. + +Такие операции требуют отдельной схемы конкретного аппарата и явного решения владельца. Сырые handshake-кадры, AES-данные и полные ответы платы не включаются в NUnit/TRX-отчёты; сохраняются только безопасные категории сообщений и результаты проверок. diff --git a/docs/hardware/PERIPHERY_CONTROLLER_2_3_5.md b/docs/hardware/PERIPHERY_CONTROLLER_2_3_5.md new file mode 100644 index 0000000..4b6b636 --- /dev/null +++ b/docs/hardware/PERIPHERY_CONTROLLER_2_3_5.md @@ -0,0 +1,260 @@ +# Интеграция универсального контроллера 2.3.5 + +## Источник + +Реализация основана на локальной спецификации `references/docs/periphery_controller.md`, версия 2.3.5. Каталог `references/` не входит в Git; этот документ фиксирует только принятые для приложения технические решения и не заменяет оригинальную документацию производителя. + +## Физический транспорт + +- USB-COM/UART, `115200`, 8 data bits, parity `None`, 1 stop bit, flow control `None`. +- ASCII-кадры завершаются `CR`, `LF` либо парой `CRLF`. +- Минимальный кадр — два символа. +- Незавершённый кадр отбрасывается через 100 мс. +- Максимальная длина входного кадра ограничена настройкой, по умолчанию 1024 байта. После переполнения хвост кадра игнорируется до следующего разделителя. +- Исходящие команды завершаются `CRLF` и записываются последовательно одним worker-потоком. + +`SerialPortHardware` не вызывает Godot API и пользовательские события из фонового потока. Worker складывает кадры и изменения соединения в потокобезопасную очередь; `App._Process()` доставляет их в главный поток через `ProcessPendingEvents()`. + +## Авторизация + +Поддержан строгий startup-handshake, совпадающий с актуальным `plate_config_app`: + +```text +open → RTS reset → periphery controller ver_ → wait 2000 ms +→ 07 → CHAL → 08 +→ RAES → [AUTH_PC_OK/AUTH_CNT_OK] → READY! +``` + +Сразу после открытия `SerialPortHardware` очищает буферы, устанавливает DTR в `false`, удерживает RTS в `true` 100 мс и возвращает RTS в `false`. До отправки `07` приложение требует регистрозависимый префикс `periphery controller ver_` и непустую версию, затем выдерживает 2000 мс. Challenge и криптографические ответы содержат по 16 байт/32 HEX-символа в верхнем регистре. Разбор входящих `CHAL` и `RAES`, как в `plate_config_app`, принимает слитный payload, а также необязательный пробел или двоеточие после префикса. После `CHAL` приложение отправляет `08`, затем в постоянном времени проверяет, что `RAES` равен AES-ответу для исходного host challenge. Даже корректный `RAES` ещё не разрешает рабочие команды: завершением авторизации является только точный, полностью очищенный кадр `READY!`. `AUTH_PC_OK` и `AUTH_CNT_OK` распознаются как промежуточные подтверждения; `READY`, `ready!` и любые варианты с другим регистром не принимаются. + +Таймауты отдельных стадий не блокируют главный поток: + +- стартовый баннер ожидается до 20 секунд; +- после баннера всегда выдерживается 2000 мс; +- `HandshakeTimeoutMilliseconds` задаёт отдельный таймаут ожидания `CHAL` и `RAES` (по умолчанию 2000 мс, как в актуальном `plate_config_app`; диапазон 1000–60000 мс); +- точный `READY!` после `RAES` ожидается до 5 секунд; +- таймаут любой стадии переводит авторизацию в `Failed`, закрывает текущий порт и оставляет reconnect безопасно начать весь процесс заново; +- disconnect сбрасывает автомат и отменяет текущее ожидание. + +Для диагностики сохраняется только тип последнего ответа (`CHAL`, `RAES`, `AUTH_CNT_OK`), но не секретный payload. + +Владелец проекта предоставил 32-байтовое обфусцированное представление ключа: + +```text +6940C70EF2C7457072CD2858998F73A85F5FEDB4C162B424ACD7A3D6D80B5037 +``` + +Оно зафиксировано в `PeripheryControllerSecurity.AesEncryptedKey`. Перед использованием каждый байт восстанавливается операцией `storedByte XOR 0x37`, как в рабочем Unity-проекте. В документации и логах эффективный ключ не раскрывается. Переменная окружения `EXCHANGER_CONTROLLER_AES_KEY` может переопределить встроенное значение для другой ревизии платы и должна содержать уже эффективный 32-байтовый ключ в HEX — XOR к override повторно не применяется. + +Владелец проекта предоставил рабочую функцию шифрования и подтвердил профиль: + +- `aes.Key` — 32-байтовый ключ контроллера; +- `CipherMode.ECB`; +- `PaddingMode.None`; +- `CreateEncryptor().TransformFinalBlock(data, 0, data.Length)`; +- каждый handshake-блок содержит ровно 16 байт; IV для ECB не используется. + +`Aes256EcbBlockCipher` реализует тот же алгоритм. `ControllerAesMode: "ECB"` теперь установлен по умолчанию, а пользовательская конфигурация версий до 6 автоматически мигрирует на подтверждённый профиль. + +Контрольный пример спецификации теперь воспроизводится точно: challenge `8C704E9C4CBF4BA2255741C566FB0F7A` после восстановления ключа шифруется в `99ED731648AB8C1709CC4C3C8C3BB0E1`. Тот же алгоритм подтвердил реальный случайный handshake на COM3. + +## Платёжные команды + +| Действие приложения | Команды/события протокола | +| --- | --- | +| Начать наличную сессию | `141`, затем `151` | +| Остановить наличную сессию | `142`, `152` | +| Принять сумму монет | `MONEY:COINS:zzz`, немедленно `ASK:COINS:zzz` | +| Принять купюру/сумму | `MONEY:BILL:zzz`, немедленно `ASK:BILL:zzz` | +| Начать безналичную оплату | `161`, затем `163` | +| Поддержать Вендист активным | `161` каждые 120 секунд в idle/card-состоянии; прошивка требует интервал меньше 180 секунд | +| Подтвердить безналичную сумму | `MONEY:CASHLESS:zzz`, немедленно `ASK:CASHLESS:zzz` | +| Отменить безналичную оплату | `162` | + +### Привязка пользовательских действий + +Команды привязаны не к визуальному оформлению темы, а к типизированным действиям `SessionFlow`. +Поэтому внешний DLC может полностью заменять сцены, не меняя аппаратный сценарий. + +| Действие покупателя или приложения | Последовательность на проводе | +| --- | --- | +| Нажать «Наличные» на Home | `162` (гарантированно выключить Вендист), `141` (smart-монетник), `151` (разрешить купюры) | +| Внести монеты | плата: `MONEY:COINS:<сумма>`; ПК немедленно: `ASK:COINS:<сумма>`; только затем сумма прибавляется к текущему балансу | +| Внести купюру | плата: `MONEY:BILL:<сумма>`; ПК немедленно: `ASK:BILL:<сумма>`; только затем сумма прибавляется к текущему балансу | +| Нажать «Выдать» после наличной оплаты | `142`, `152`, `162`, затем последовательность `309N`/`409N` по выбранному плану двух хопперов; N в каждом пакете 1–99, а каждый `HOPPER1/2 OK` подтверждает один фактический жетон | +| Нажать «Безналичные» на Home | Аппаратная команда пока не отправляется: покупатель сначала безопасно выбирает сумму | +| Подтвердить карточную сумму | `142`, `152`, `161`, `163<сумма>` | +| Успешная карточная оплата | плата: `MONEY:CASHLESS:<сумма>`; ПК: `ASK:CASHLESS:<сумма>`, затем `162`; выдача начинается только при точном совпадении с суммой `163` | +| Отмена или таймаут на экране терминала | `162`; команда выдачи не отправляется | +| Назад/таймаут во время наличной оплаты | `142`, `152`; команда выдачи не отправляется | +| Потеря связи | все активные платёжные состояния сбрасываются; после reconnect команды оплаты и выдачи автоматически не повторяются | + +Платёжные каналы взаимоисключающие. Перед запуском наличной ветки приложение выключает +Вендист, а перед `161/163` выключает монетник и купюроприёмник. Повторная отмена идемпотентна и +не добавляет одинаковые команды в FIFO-очередь платы. + +Повторное `MONEY:CASHLESS` после первого подтверждённого результата подтверждается контроллеру, но не применяется к уже завершённой card-сессии. Сумма должна точно совпасть с запросом `163`; несовпадение не считается успешной оплатой. + +Событие `COIN` без номинала всегда подтверждается командой `10`, но не зачисляется: приложение после успешного `RAES` включает smart-режим и ожидает `MONEY:COINS:zzz`. + +Команды status-запросов `140`, `150`, `160` и `99` представлены типизированными константами. Форматы ответов производителем не заданы, поэтому приложение не пытается интерпретировать произвольный developer-текст как рабочее состояние. + +## Выдача и запас жетонов + +В протоколе есть две подтверждённые группы хопперов: `30X` для первого и `40X` для второго. Целевой production-профиль `DualHopperAuto` использует оба канала. Для подтверждения выдачи и пересчёта приложение читает строки `HOPPER1/2 OK`, `CREDIT` и `PULSE`, поэтому физический вход импульсного датчика второго хоппера не требуется. + +Безопасное поведение универсальной конфигурации по умолчанию: + +- `DispenseMode: "Unsupported"`; +- приём наличных и безналичной оплаты блокируется до наличия безопасного способа выдачи; +- приложение не отправляет предполагаемую команду силового выхода; +- аппаратный контроллер не сообщает точное число жетонов; отдельный учётный остаток владельца + хранится приложением и не подменяет бинарное показание датчика. + +Для подключённого автомата первый хоппер использует датчик малого остатка `IN1` и команды `30X`, второй — датчик `IN4` и команды `40X`. Конфигурация версии 18 мигрирует ранее выбранный одноканальный профиль `Hopper1Auto`/`Hopper2Auto` в `DualHopperAuto`, сохраняет сервисную кнопку на `IN8` и active-low полярность обоих датчиков уровня. Репозиторный default остаётся `Unsupported`: перенос приложения на другой автомат не должен самовольно запускать мотор. + +Каждый хоппер имеет бинарный датчик уровня: `Enough` или `Low`. Точного числа жетонов датчики не сообщают. Двухканальная аппаратная граница передаёт `Hopper1StockLevel` и `Hopper2StockLevel`, а устаревшее агрегированное `MachineStockLevel` сохранено только для совместимости: + +- `Enough` — датчик сообщает «много»; +- `Low` — датчик сообщает «мало»; +- `Unknown` — состояние ещё не получено, вход не настроен или связь потеряна. + +Точные учётные остатки хранятся отдельно для каждого хоппера в `user://data/token_inventory.json`, начинаются с нуля, меняются раздельным ручным пополнением или пересчётом и списываются по фактически подтверждённому каналу выдачи. Покупателю и владельцу показывается только приблизительный общий итог: `<100` для 1–99, шаг 100 до 1000 включительно и шаг 500 выше 1000. + +Адаптер разбирает фактический ответ `INPUT`; для совместимости принимается и `INPUT `. Подтверждённая разводка production-профиля: + +| Вход | Электрическая семантика | Действие приложения | +| --- | --- | --- | +| `IN8` | pull-up, `0` при нажатии | Один active-low фронт публикует `ServiceRequested`: из свободного Home настройки открываются напрямую при выключенной защите либо через PIN при включённой; следующий фронт в Settings завершает автосохранение и возвращает Home. Удержание не создаёт повторов. Кадр `SERVICE` используется как fallback только когда отдельный сервисный вход не настроен. | +| `IN1` | active-low датчик запаса первого хоппера | активный сигнал (`бит 0`) → `Low`, отсутствие сигнала (`бит 1`) → `Enough`; повтор одинакового снимка не публикует лишнее изменение. | +| `IN24` | физический датчик выдачи первого хоппера | Сохранён в конфигурации и доступен для диагностики. Runtime не считает его периодические `INPUT`-снимки: обычную выдачу подтверждает `HOPPER1 OK`, прямой пересчёт — `HOPPER1 PULSE=1`. | +| `IN4` | active-low датчик запаса второго хоппера | активный сигнал (`бит 0`) → `Low`, отсутствие сигнала (`бит 1`) → `Enough`; участвует в общей четырёхуровневой индикации. | +| `???` | физический датчик выдачи второго хоппера | Вход не требуется runtime: обычную выдачу подтверждает `HOPPER2 OK`, прямой пересчёт — `HOPPER2 PULSE=1`. | + +Индексы и полярности остаются переопределяемыми во внешней технической конфигурации: + +- `ServiceButtonInputIndex` / `ServiceButtonActiveHigh`; +- `StockSensorInputIndex` / `StockLowWhenInputHigh` для первого хоппера; +- `Hopper2StockSensorInputIndex` / `Hopper2StockLowWhenInputHigh` для второго; +- `Hopper1DispenseSensorInputIndex` / `Hopper1DispenseSensorActiveHigh`; +- `InputPollMilliseconds` — резервный опрос быстрых входов, по умолчанию 100 мс; +- `StockPollSeconds` — старый медленный интервал, используемый только если кнопка и импульсный датчик отключены значением `-1`. + +Плата также может присылать `INPUT` асинхронно. Команда `91` используется как резервный опрос, чтобы состояние не зависело только от доставки событий. + +Общая индикация объединяет учётный итог и два датчика: нулевой остаток — `Empty`; оба `Enough` — `Much`; остаток меньше 100 или оба `Low` — `Low`; остаток от 100 либо хотя бы один `Enough` — `Enough`. Покупатель видит соответственно «нет жетонов», «мало», «достаточно» или «много» и заранее подготовленную темой полоску 0%, красную 25%, красную 50% или зелёную 100%. + +В целевом профиле `DualHopperAuto` обычная покупка формирует безопасный план по точным учётным остаткам двух хопперов и отправляет `309N` либо `409N`. За один пакет передаётся 1–99 жетонов; большие выдачи разбиваются последовательно. `309100` и `409100` возвращают соответственно `ERROR:30:invalid count (0-99)` и `ERROR:40:invalid count (0-99)`. Значение 0 зарезервировано для запросов `3090`/`4090` текущего `CREDIT`. Ответы обоих каналов симметричны: + +- `HOPPER1/2 APPEND=N` — N кредитов добавлено в очередь; это ещё не выдача; +- `HOPPER1/2 OK` — фактически выдан один жетон; +- `HOPPER1/2 ERROR` — выбранный хоппер не смог продолжить текущую очередь; +- `HOPPER1/2 CREDIT=N` — осталось выдать N кредитов; +- `3090`/`4090` — запрос текущего `CREDIT`. + +После `ERROR` адаптер ждёт `CREDIT` до 3000 мс, вычисляет частичный результат и завершает только текущую операцию. Новая прошивка больше не защёлкивает хоппер в ошибке до перезагрузки, поэтому следующая явная операция владельца или покупателя разрешена. Автоматического retry всё равно нет: повтор без решения вызывающего кода мог бы выдать жетоны дважды. + +Сервисный автоматический пересчёт — отдельный взаимоисключающий режим: + +- выбранный хоппер включается `301` либо `401` и обязательно выключается парной командой `300` либо `400`; +- каждый физически прошедший жетон плата сообщает строкой `HOPPER1 PULSE=1` либо `HOPPER2 PULSE=1`; +- приложение считает только строки активного хоппера и не опрашивает физические импульсные входы, поэтому события не теряются и не дублируются; +- каждый `PULSE=1` заново запускает интервал ожидания; 10 секунд тишины означают конец пересчёта; +- `HOPPER1/2 OK` в режиме прямого мотора не увеличивает счётчик; +- отмена, закрытие приложения и потеря связи завершают операцию безопасно; при доступной связи + сначала отправляется команда выключения двигателя. + +На границе протокольного адаптера действует at-most-once-политика: + +- пока предыдущая выдача не завершена, повторный вызов `DispenseTokens` не отправляет вторую команду; +- после обрыва связи команда автоматически не повторяется, а результат остаётся неизвестным; +- `HOPPER1/2 ERROR/CREDIT` завершает активную выдачу с уточнённым partial-result, но не блокирует следующую команду; +- обратная связь неактивного в текущем пакете хоппера игнорируется и не может завершить чужую выдачу или пересчёт. + +## Wire-симулятор + +`PeripheryControllerSimulator` реализует `IHardwarePort` и детерминированно воспроизводит документированную часть протокола без COM-порта: + +- полный double handshake через тот же `ControllerAuthenticator` и cipher; +- `INPUT` (также принимается вариант с пробелом); +- `MONEY:COINS/BILL/CASHLESS` и обязательные `ASK:*`; +- успешную и частично неуспешную выдачу `309N → APPEND/OK` либо `ERROR/CREDIT`; +- наличную и безналичную ветки целиком, включая взаимоисключение приёмников, отмену и пакетную + выдачу количества больше 99; +- `SERVICE`, malformed/unknown кадры и disconnect. + +Симулятор не придумывает status/heartbeat-ответы и production-команду силового канала. Он используется интеграционными тестами совместно с настоящими `PeripheryProtocolParser`, `PeripheryMachineController` и `SessionFlow`. + +## Потеря связи и повторное подключение + +- При исчезновении порта активная операция получает `ConnectionLost`; во время выдачи `SessionFlow` переводит её в `DispenseStatusUnknown`. +- `DISPENSE` автоматически не повторяется. +- Приложение пытается повторно открыть COM-порт с настраиваемым интервалом, по умолчанию 5 секунд. +- После каждого подключения аппаратный reset, startup-handshake и безопасная инициализация выполняются заново. +- Только после точного `READY!` монетник переводится в smart-режим, а все платёжные приёмники сначала отключаются. + +### Сервисное состояние соединения + +`PeripheryMachineController` публикует типизированное состояние `Disconnected`, `Authenticating`, `Ready` или `Faulted`. Оно не содержит имени COM-порта, сырых кадров, AES-данных и текста внутренних исключений. + +- при физическом подключении состояние переходит в `Authenticating`; +- только после стартового баннера, криптографической проверки `RAES` и точного `READY!` публикуется `Ready`; +- штатный обрыв переводит состояние в `Disconnected`, а запас — в `Unknown`; +- ошибка конфигурации, криптографической проверки или таймаут handshake переводят состояние в `Faulted`; +- в production индикатор скрыт при `Ready`, но остаётся видимым при авторизации, обрыве и ошибке; в debug отображается и штатное состояние. + +Автоматический тест выполняет 200 циклов подключения, авторизации и отключения во время незавершённой выдачи. Он подтверждает, что reconnect не повторяет команду выдачи, отложенный ответ хоппера не завершает оборванную операцию, а последовательность состояний остаётся ровно одной на цикл. Проверка реального worker-потока при многократном отключении USB-кабеля остаётся обязательной аппаратной приёмкой. + +## Фактическая проверка платы 2026-08-24 + +Подключённый контроллер определился как `Silicon Labs CP210x USB to UART Bridge` на `COM3`. +Безопасный прогон использовал 115200 8N1/None и не запускал оплату, RESET, силовые выходы или хоппер. + +Ниже сохранён исторический результат до синхронизации startup-фазы с `plate_config_app`. Он подтвердил ключ и доказательство `RAES`, но больше не является достаточным условием готовности production-адаптера: + +1. ПК отправляет `07` с новым случайным 16-байтовым блоком. +2. Плата возвращает корректно сформированный `CHAL`. +3. ПК отправляет `08 = AES-256-ECB-Encrypt(CHAL)` с ключом приложения и `Padding=None`. +4. Плата возвращает корректно сформированный `RAES`. +5. После восстановления ключа через XOR `0x37` `RAES` точно совпадает с + `AES-256-ECB-Encrypt(07)`. +6. На тот момент отсутствие `AUTH_CNT_OK` трактовалось как допустимое, а адаптер переходил в + `Ready` после `RAES`. Это поведение отменено: актуальная реализация требует стартовый баннер, + паузу 2000 мс и точный завершающий кадр `READY!`. +7. После привязки входов безопасная группа повторно прошла 9/9 2026-08-27: цифровой вход `91`, + преобразование `IN1` в `Enough/Low`, status-запросы `140`, `150`, `160`, `309?`, `99` и три + цикла повторной авторизации. Во время последнего прогона активный `IN1` корректно дал `Low`. + Все status-команды получили непустые неошибочные кадры; их недокументированное содержимое + намеренно не сохраняется. Один краткий отказ открытия COM3 при быстром переоткрытии был + автоматически восстановлен предусмотренным retry. + +## Повторная проверка строгой авторизации 2026-08-31 + +После синхронизации startup-последовательности с актуальным `plate_config_app` плата на COM3 +успешно прошла отдельный безопасный auth-probe 1/1. Физически подтверждены аппаратный RTS-reset, +точный startup-баннер, пауза 2000 мс, `CHAL`, криптографически верный `RAES` и завершающий +`READY!`. Production-адаптер перешёл в `Ready` только после последнего кадра. + +На предыдущей версии прошивки группа `Safe` прошла 8/9: `91`, active-low `IN1`, `140`, `150`, старый запрос состояния хоппера, `99` и три +цикла повторной авторизации были успешны. Команда `160` в двух независимых запусках не получила +ответа. Это отдельная несовместимость status-запроса/подключения Вендиста и не является ошибкой +startup-handshake. Моторы, выдача жетонов, приём наличных и реальная безналичная операция не +запускались. + +Диагностический probe не сохраняет сырые challenge/proof: в TRX остаются только категории, +булевы результаты сравнений и короткие SHA-256 fingerprints. Обход криптографической проверки +не используется. Ни оплата, ни выдача в безопасном прогоне не запускались. + +## Вопросы для последующей проверки на целевом оборудовании + +1. После подключения платы физически проверить из приложения одну и несколько выдач первого хоппера через `309N`, включая `HOPPER1 APPEND=N`, число кадров `HOPPER1 OK` и фактических жетонов. +2. Подтвердить порядок `HOPPER1 ERROR → HOPPER1 CREDIT=N`, ответ на `3090` и возможность следующей явной выдачи без перезапуска платы. +3. Подтвердить сервисный пересчёт `301 → HOPPER1 PULSE=1… → 300` и окончание по 10 секундам без импульса. +4. Уточнить, `MONEY:BILL/COINS:zzz` — дельта одного события или накопительный итог сессии. +5. Описать сообщения отказа/отмены/таймаута Вендиста, если они существуют. +6. Расшифровать точные форматы ответов на status-команды `140`, `150`, `160`, `3090`, `99` и heartbeat. +7. После исправления прошивки второго хоппера получить вход его датчика выдачи и отдельно специфицировать `40X`; до этого приложение не отправляет такие команды. + +Эти вопросы не оставляют незавершённого кода внутри документированного профиля Этапа 3: неподтверждённые возможности представлены безопасными состояниями `Unsupported`/`Unknown`. Они блокируют только включение production-профиля на физическом автомате. + +Для проверки реальной реализации этих ответов подготовлен отдельный аппаратный набор: [BOARD_ACCEPTANCE_TESTS.md](BOARD_ACCEPTANCE_TESTS.md). Он компилируется вместе с solution, но открывает COM-порт и активирует периферию только при явных флагах запуска. diff --git a/docs/operations/ON_SCREEN_KEYBOARD.md b/docs/operations/ON_SCREEN_KEYBOARD.md new file mode 100644 index 0000000..7bbf44a --- /dev/null +++ b/docs/operations/ON_SCREEN_KEYBOARD.md @@ -0,0 +1,73 @@ +# Экранная клавиатура + +## Назначение + +Владелец автомата может полностью редактировать настройки с тач-экрана без физической клавиатуры. +Тап по `LineEdit` открывает текстовую клавиатуру, тап по внутреннему полю `SpinBox` — цифровую. +Существующие полноэкранные клавиатуры PIN и произвольной суммы оплаты остаются отдельными +сценариями и не используют этот компонент. + +## Возможности + +Текстовая клавиатура поддерживает: + +- русскую раскладку по умолчанию, включая `Ё`; +- английскую раскладку; +- Shift для регистра букв; +- страницу из 33 цифр и спецсимволов, в том числе знаки для локальных путей; +- пробел, очистку, удаление и перемещение каретки; +- скрытие кнопкой в правом верхнем углу. + +Цифровая клавиатура содержит цифры 0–9, очистку, удаление и отдельную кнопку скрытия. +Для текущих `SpinBox` не показываются минус и десятичный разделитель: все доступные владельцу +числовые настройки являются неотрицательными целыми значениями. + +При открытии нижней панели `ScrollContainer` поднимает активное поле выше клавиатуры. Смена раздела, +повторное нажатие сервисной кнопки и выход из Settings применяют введённое значение `SpinBox`, +скрывают клавиатуру и освобождают фокус. Валидные изменения продолжают использовать обычное +автосохранение с задержкой 0,5 секунды. + +## Архитектура + +Логика находится в `src/ui/OnScreenKeyboard/`: + +- `OnScreenKeyboardState` хранит RU/EN/symbols/numeric и Shift без зависимости от Godot; +- `OnScreenKeyboardView` описывает обязательные ссылки на уже готовые узлы темы; +- `OnScreenKeyboardController` связывает поля, кнопки и прокрутку. + +Контроллер использует `LineEdit.InsertTextAtCaret`, `DeleteText`, выделение и составные Unicode- +символы. Для числового поля после изменения вызывается `SpinBox.Apply()`. Синтетические +`InputEventKey` не отправляются, поэтому `TextChanged`/`ValueChanged`, валидация и автосохранение +работают обычным путём. У обслуживаемых полей отключены `VirtualKeyboardEnabled` и +`VirtualKeyboardShowOnFocus`. + +В fallback-сцене панели находятся в `SafeMargin/KeyboardOverlay`. Внешняя тема может располагать +их иначе, но обязана предоставить все 57 metadata binding-id из каталога v2. Приложение не создаёт, +не перемещает и не стилизует визуальные узлы внешней сцены; их внешний вид полностью принадлежит +теме и совпадает с её preview. + +## Проверка + +Перед выпуском необходимо проверить на 720×1280: + +1. ввод русского и английского текста, Shift и возврат со страницы `?123`; +2. вставку в середину строки, выделение, удаление и `MaxLength`; +3. ввод цены, бонусов и карточных сумм через цифровую панель; +4. повторное открытие после кнопки «Скрыть»; +5. переключение между полями и вкладками; +6. закрытие Settings повторным нажатием `IN8` и сохранение последнего числа; +7. одинаковую композицию fallback, preview и установленной DLC-темы. + +Чистое состояние раскладок покрыто NUnit-тестами. Наличие панелей, отсутствие runtime-создания +визуальных узлов и интеграционные маркеры сцены проверяются smoke-тестами. + +Автоматический Godot smoke запускается из корня проекта сначала с установленной темой, затем с +fallback: + +```powershell +$godot = "D:\Applications\Godot\Godot_v4.7.1-stable_mono_win64\Godot_v4.7.1-stable_mono_win64_console.exe" +& $godot --headless --path . tests/runtime/OnScreenKeyboardSmoke.tscn -- --mock-hardware=true +& $godot --headless --path . tests/runtime/OnScreenKeyboardSmoke.tscn -- --no-theme-dlc --mock-hardware=true +``` + +Оба запуска обязаны вывести `ON_SCREEN_KEYBOARD_RUNTIME_SMOKE_OK` и завершиться с кодом 0. diff --git a/docs/operations/PERFORMANCE_BASELINE.md b/docs/operations/PERFORMANCE_BASELINE.md new file mode 100644 index 0000000..36f2b72 --- /dev/null +++ b/docs/operations/PERFORMANCE_BASELINE.md @@ -0,0 +1,65 @@ +# Базовый профиль производительности + +Дата замера: 2026-08-24. Этот документ фиксирует воспроизводимую отправную точку Этапа 7, +но не заменяет приёмку на целевом компьютере автомата. + +## Среда + +- Godot 4.7.1 stable, debug-запуск из редактора, Compatibility renderer (исторический замер до + перехода на Mobile/Vulkan для Native Video); +- Windows 11 Pro x64, сборка 10.0.26200; +- AMD Ryzen 5 7500F, 6 ядер / 12 потоков; +- AMD Radeon RX 7700 XT, драйвер 32.0.31035.1003; +- 31,7 ГиБ оперативной памяти; +- встроенная fallback-тема, промо-ролик не воспроизводился. + +## Результаты + +Показатели сняты через `Performance` работающего приложения после стабилизации сцены. +Каждая строка — диапазон шести последовательных срезов. + +| Экран | Разрешение | FPS | Process, мс | Physics, мс | Draw calls | Nodes | Static, МиБ | Video, МиБ | +|---|---:|---:|---:|---:|---:|---:|---:|---:| +| Home | 720×1280 | 60 | 1,19–1,26 | 0,047–0,049 | 23 | 578–585* | 124,07–124,17 | 20,62 | +| Settings | 720×1280 | 60 | 1,03–1,33 | 0,035–0,105 | 37 | 578 | 124,37–124,43 | 20,65 | +| Settings | 1080×1920 | 60 | 0,99–1,22 | 0,025–0,036 | 37 | 578 | 121,66–121,73 | 29,04 | + +После установки актуального `space_pixel` отдельно проверен Home при окне 720×1280 и логическом +viewport 1080×1920. В полном режиме decoration приложение держит 60 FPS и 26 draw calls, в +`ReducedEffects` — 60 FPS и 24 draw calls. После отбрасывания диагностического кадра process time +составил 1,20–1,94 мс и 1,16–1,58 мс соответственно. Переключение подтвердило фактическую смену +числа дочерних decoration-сцен `1 → 0 → 1`. + +\* Рост числа узлов в первом диагностическом цикле создавали вызовы MCP-helper, а не экраны +приложения; отдельная проверка после оптимизации стабильно показала 578 узлов. + +При бюджете кадра 16,67 мс CPU-обработка текущего UI занимает менее 1,4 мс в этой среде. +Видеопамять закономерно возрастает при переходе с 720×1280 на 1080×1920. + +## Выполненные ограничения нагрузки + +- Фон — статическая текстура; шейдеры, частицы и фоновое видео не используются. +- Анимация допускается только отдельными спрайтами темы; `ReducedEffects` полностью убирает + decoration-сцену. +- Все восемь скрытых экранов имеют `ProcessMode.Disabled`; обработка включена только у текущего + экрана. Runtime-проверка выполнена при переходе Home → Settings. +- `VideoStreamPlayer` промо-ролика останавливается и освобождает stream при скрытии Home. +- Сценарные таймауты используют `IMonotonicClock`, а не количество кадров; тест с единственным + обновлением после скачка времени на 120 секунд завершает ожидание оплаты немедленно. +- Runtime-аудит последовательно открыл все девять экранов. Пользовательские кнопки имеют не менее + 96 логических пикселей по короткой стороне; обе цифровые клавиатуры получили равные колонки + (ServiceAccess 281–282×120, CardCustomAmount 318–319×150 при viewport 1080×1920). +- В сервисном экране самые низкие интерактивные строки имеют размер 908×90; малых изолированных + touch-целей и поведения, зависящего от `MouseEntered`, в приложении нет. + +## Что остаётся проверить на стенде + +- внешний DLC, специально собранный у границ допустимого бюджета анимированных спрайтов; +- одновременное декодирование реального OGV или MP4 и работа decoration-сцены; +- яркое освещение, рабочее расстояние, касание пальцем и в перчатках; +- фактическое разрешение панели, драйвер GPU и длительный профиль памяти; +- автоматическое либо конфигурационное включение `ReducedEffects`, если целевой ПК не держит + стабильные 60 FPS. + +После появления целевого ПК эту таблицу следует повторить на production export, указав модель +панели, разрешение, версии драйверов, тему, ролик и число активных анимированных спрайтов. diff --git a/docs/operations/RECOVERY_AND_MOCK_QA.md b/docs/operations/RECOVERY_AND_MOCK_QA.md new file mode 100644 index 0000000..0683050 --- /dev/null +++ b/docs/operations/RECOVERY_AND_MOCK_QA.md @@ -0,0 +1,63 @@ +# Восстановление операций и проверка mock-сценариев + +Дополнительные эксплуатационные инструкции: [Windows kiosk setup](WINDOWS_KIOSK_SETUP.md), +[матрица доступа к настройкам](SETTINGS_ACCESS_MATRIX.md) и [длительный soak-тест](SOAK_TEST.md). + +## Назначение + +Документ фиксирует безопасное поведение Exchanger при сбое приложения или потере связи до появления спецификации реального контроллера. Описанные правила не предполагают существование wire-команд, идентификаторов транзакций или запроса статуса, которых ещё нет в документации. + +## Локальный идентификатор операции + +Каждая ветка оплаты получает уникальный `OperationId`. Это локальный диагностический идентификатор приложения, а не идентификатор банковской транзакции и не будущий идентификатор команды контроллера. После получения протокола эти значения можно будет связать отдельным полем, но смешивать их нельзя. + +## Журнал операций + +Жизненный цикл записывается построчно в JSONL-файл: + +```text +user://logs/operations.jsonl +``` + +Запись содержит время UTC, тип события `Started`/`Finished`, локальный `OperationId`, способ оплаты, сумму, расчётное число жетонов, итог и типизированный код ошибки. В журнал запрещено записывать номер карты, данные магнитной полосы/чипа, платёжные токены, сырые ответы оборудования и персональные данные. + +Повреждённая строка не мешает чтению остальных записей. При достижении текущим файлом настроенного лимита он переносится в `operations-.jsonl`. Архивы `exchanger`, `operations` и `settings-audit` автоматически очищаются по сроку хранения и общему объёму; активные файлы при очистке защищены. + +## Правила восстановления после перезапуска + +При старте приложение ищет `Started` без соответствующего `Finished` и закрывает такую запись итогом `UnknownAfterRestart`. Автоматическая повторная оплата или выдача не запускается. + +Для операции, прерванной в `CardTerminalWait`: + +1. Не считать платёж успешным или отклонённым без подтверждения терминала/контроллера. +2. Не запускать новую оплату автоматически. +3. Вернуть пользовательский интерфейс на домашний экран. +4. Оператор сверяет время и `OperationId` с журналом терминала и будущими журналами контроллера. + +Для операции, прерванной в `Dispensing`: + +1. Считать результат выдачи неизвестным. +2. Не повторять команду выдачи и не предлагать пользователю повторную оплату. +3. Оператор проверяет физически выданные жетоны, остаток и журнал контроллера. +4. Автоматическое восстановление допускается только после документированного запроса статуса либо подтверждённой идемпотентности команды. + +До получения протокола приложение не может автоматически различить «команда не дошла» и «команда выполнена, но подтверждение потеряно». Это намеренное безопасное ограничение. + +## Ручной mock-чек-лист + +Панели эмуляции отображаются только в debug-сборке. Перед проверкой выполнить `dotnet test Exchanger.sln`, затем запустить главную сцену. + +| Сценарий | Действия | Ожидаемый результат | +| --- | --- | --- | +| Наличные: успех | Открыть оплату наличными, добавить тестовые купюры, нажать выдачу | Сначала «Идёт выдача», затем подтверждённый успех; бинарный уровень запаса не изменяется без отдельного сигнала датчика | +| Карта: успех | Выбрать сумму, нажать `УСПЕХ (DEBUG)` | Выдача запускается один раз, успех показывается только после mock-подтверждения | +| Карта: отказ | Нажать `ОТКАЗ (DEBUG)` | Без выдачи показывается безопасная ошибка оплаты | +| Ошибка выдачи | Нажать `ОШИБКА ВЫДАЧИ` | Показывается типизированная ошибка; сырая строка mock-контроллера не выводится | +| Частичная выдача | Выбрать сумму более одного жетона, нажать `ЧАСТИЧНАЯ ВЫДАЧА` | Показывается обращение в поддержку; повтор выдачи недоступен | +| Потеря связи до выдачи | Нажать `ПОТЕРЯ СВЯЗИ` на экране ожидания карты | Операция завершается `ConnectionLost`, пользователь направляется в поддержку | +| Потеря связи во время выдачи | Задать увеличенную `DispenseDelaySeconds`, подтвердить карту и вызвать `SimulateConnectionLoss()` через разрешённый `godot-ai` | Итог `DispenseStatusUnknown`; интерфейс предупреждает не повторять оплату | +| Таймаут | Не подтверждать оплату до истечения настроенного времени | Выдача не запускается, итог `PaymentTimeout` | +| Повторный ввод | Быстро нажать действие несколько раз | Создаётся одна операция и не более одной выдачи | +| Перезапуск | Завершить приложение с активной операцией, затем запустить снова | Незакрытая запись получает `UnknownAfterRestart`; автоматического retry нет | + +После каждого сценария проверить `user://logs/exchanger.log`, `user://logs/operations.jsonl`, а также game/editor logs. В них не должно быть платёжных секретов, необработанных исключений и дублированных итогов одной операции. diff --git a/docs/operations/SETTINGS_ACCESS_MATRIX.md b/docs/operations/SETTINGS_ACCESS_MATRIX.md new file mode 100644 index 0000000..45bf2cb --- /dev/null +++ b/docs/operations/SETTINGS_ACCESS_MATRIX.md @@ -0,0 +1,112 @@ +# Матрица доступа к настройкам Exchanger + +## Назначение экрана + +Экран настроек предназначен для владельца автомата, а не для технического специалиста. +В production он открывается физической кнопкой `SERVICE`; опциональный единый PIN включается +в самом приложении. В debug-сборке `F10` открывает тот же состав пользовательских настроек. + +## Доступные владельцу разделы + +| Раздел UI | Секции `AppSettings` | Применение | +| --- | --- | --- | +| Общие | `Branding.ShortText`, `Branding.SupportPhone`, `Security` | сразу после автосохранения | +| Звук | `Audio` | сразу, включая live-preview | +| Промо | `Advertisement` | сразу после автосохранения | +| Тарифы | `Pricing` | сразу, только когда нет операции | +| Оплата | `Payments`, `Timeouts` | сразу, только когда нет операции | +| Сервис | `MenuVisibility`, `TokenInventory.Enabled`, отдельный `user://data/token_inventory.json` | сразу после автосохранения; остаток — после ручного добавления или подтверждения пересчёта | + +## Технические данные, отсутствующие в UI владельца + +- внешний DLC темы, путь к `.pck`, текущая тема и `ReducedEffects`; +- сводки применения restart-only изменений и технический итог плейлиста промо-роликов; +- mock-режим, COM-порт, baud rate, reconnect и остальные параметры контроллера; +- fullscreen, borderless, debug-window и target FPS; +- версия приложения, состояние соединения, порт, запас и последние диагностические предупреждения; +- уровень журналирования, размер и срок хранения журналов; +- инженерная тестовая выдача одного жетона (владелец вместо неё видит безопасный учёт остатка); +- AES-ключ, платёжные секреты, сырые кадры, команды и ответы контроллера; +- framing, handshake, профиль силового канала и привязки `IN8/IN1/IN4/IN24`. + +Аппаратные значения находятся в отдельном +`user://config/technical_settings.toml` и изменяются только при техническом обслуживании вне +приложения. Порт, оба хоппера, привязки входов и параметры связи описаны в +[TECHNICAL_CONFIGURATION.md](TECHNICAL_CONFIGURATION.md). Они не участвуют в валидации формы +владельца и не могут заблокировать автосохранение доступных ему параметров. + +## PIN и безопасность операции + +После включения или сброса PIN владелец при следующем входе дважды вводит 4–12 цифр. Открытый PIN +не сохраняется: в JSON попадают только соль, PBKDF2-SHA256-хеш и число итераций. Пять ошибок +блокируют проверку на 30 секунд. + +Экран открывается только из `Home`. Пользовательская сессия получает снимок настроек при создании +`SessionFlow`, поэтому изменения не попадают в середину оплаты или выдачи. Допустимые изменения +сохраняются атомарно через 0,5 секунды после последнего ввода. Закреплённая снизу кнопка +«Сохранить и выйти» немедленно завершает ожидающее сохранение и закрывает экран только после +успеха. Повторный IN8 использует тот же безопасный путь. При ошибках в полях, незавершённом +пересчёте или тестовой выдаче пользователь остаётся в настройках. + +Футер находится вне `ScrollContainer`, поэтому остаётся на нижней границе экрана при прокрутке +одним пальцем или зажатой ЛКМ. Нижний технический зазор в содержимом позволяет поднять последние +поля выше футера, а жест, начатый на самой кнопке, список не прокручивает. + +В разделе «Общие» владелец редактирует только «Свой текст» для речевого bubble и телефон +поддержки. Поле названия автомата и отдельный branding-preview не показываются. Сохранённое +`Branding.ApplicationName` остаётся совместимым с существующей конфигурацией и продолжает +использоваться там, где его отображает текущая тема, но через экран владельца не изменяется. + +## Сервисный учёт жетонов + +Число в разделе «Сервис» — учётный остаток владельца, а не показание датчика хоппера. +При первом запуске он равен нулю и хранится отдельно от настроек в +`user://data/token_inventory.json`. Подтверждённая обычная выдача уменьшает остаток, но не +уходит ниже нуля. + +Переключатели «Учитывать остаток жетонов» и «Не продавать больше остатка» включены по умолчанию. +Первый отвечает за ведение, списание и отображение точного остатка. Второй независимо включает +лимит полного количества к выдаче с учётом бонуса. При активном лимите недопустимая карточная +сумма отклоняется до запроса оплаты у терминала, а наличная выдача — до команды хопперу; кнопки +готовых карточных сумм недоступны, а ручной ввод показывает ошибку. + +Если учёт включён, а лимит выключен, остатки и сервисные действия остаются видимыми, подтверждённая +выдача продолжает списываться, но сохранённое число не блокирует оплату. Качественное состояние +Home для доступности покупки в этом режиме определяется бинарными датчиками. В `DualHopperAuto` +из hopper 1 планируется его записанный остаток, а вся недостающая часть направляется в hopper 2. + +При выключенном учёте отдельный переключатель лимита скрывается, сохранённое число не ограничивает +оплату и не уменьшается при выдаче. +Точный общий и раздельные остатки, кнопки пересчёта и добавления, а также их статус скрываются; +на Home скрывается только приблизительное число, но бинарное состояние датчиков продолжает +показываться. В `DualHopperAuto` выдача без учёта направляется в hopper 1 и сохраняет разбиение +команд на последовательные пакеты не более 99. Автоматического failover после ошибки нет. +Файл остатка не удаляется: перед повторным включением учёта после выдач без него необходимо +пересчитать хопперы, иначе будет использовано устаревшее сохранённое значение. + +Владелец может: + +- вручную ввести добавляемое количество и подтвердить его отдельным шагом; +- запустить автоматический пересчёт: приложение включает активный хоппер, считает фронты + датчика выдачи и завершает операцию после 10 секунд без нового импульса; +- исправить полученное число перед окончательной записью, например если оставшиеся в хоппере + жетоны были извлечены вручную и добавлены к общей куче. + +Во время пересчёта нельзя начать оплату, обычную выдачу или закрыть настройки. При отмене, +потере связи либо ошибке старый учётный остаток сохраняется. После штатного завершения старое +значение обнуляется, а новый остаток записывается только после подтверждения владельцем. + +## Скрытие элементов главного экрана + +Панель «Скрытие элементов меню» находится в разделе «Сервис» и управляет тремя независимыми +флагами `MenuVisibility`: показом учётного остатка жетонов, пользовательского текста вместе с +theme-owned персонажем справа и целого промо-блока. Все элементы по умолчанию показаны, поэтому миграция старой конфигурации +не меняет существующий интерфейс. Переключатели применяются сразу после автосохранения. + +Host изменяет только свойство видимости готовых узлов по binding-id. Он не создаёт, не перемещает +и не переоформляет содержимое внешней темы. Если скрыта панель остатка или промо, связанные с ней +поверхности интерактивного питомца также исключаются из графа при следующем входе на Home. + +Аудит `user://logs/settings-audit.jsonl` содержит дату, внутренний уровень доступа, названия +изменённых разделов и флаг необходимости перезапуска. Значения, пути, PIN, платёжные данные и +протокольные кадры в него не записываются. diff --git a/docs/operations/SOAK_TEST.md b/docs/operations/SOAK_TEST.md new file mode 100644 index 0000000..a6e6461 --- /dev/null +++ b/docs/operations/SOAK_TEST.md @@ -0,0 +1,41 @@ +# Длительный soak-тест Exchanger + +## Автоматическая модель 24 часов + +Обычный NUnit-набор содержит ускоренный сценарий `OperationalSoakTests`: он моделирует 1440 минут, +480 подтверждённых выдач и 10 000 циклов создания/освобождения `SessionFlow`. Тест проверяет +детерминированное состояние Home, отсутствие повторной выдачи и отсутствие накопления подписок. +Это проверка логики, а не замена длительному процессному прогону. + +## Процессный прогон + +`tools/soak/run-runtime-soak.ps1` запускает указанный exe, проверяет его живучесть и рабочий набор +памяти, пишет CSV-сэмплы и итог в `artifacts/soak`. По умолчанию длительность равна 24 часам. + +Пример для экспортированной debug/mock-сборки: + +```powershell +.\tools\soak\run-runtime-soak.ps1 ` + -ExecutablePath 'C:\ExchangerSoak\Exchanger.exe' ` + -ApplicationArguments @('--mock-hardware=true', '--no-theme-dlc') ` + -DurationHours 24 ` + -SampleIntervalSeconds 60 ` + -MaximumWorkingSetMb 2048 +``` + +Для короткой проверки самого runner допускается `-DurationHours 0.0167` (около минуты), но такой +результат не является 24-часовой приёмкой. Перед production прогон выполняется на целевом ПК с +подключённым дисплеем; физическую выдачу и реальную оплату в soak-профиль не включают. + +Контрольный прогон runner 2026-08-24 прошёл 12/12 пятисекундных сэмплов с пиком working set +217.73 МБ. CSV использует invariant-формат десятичных чисел и проверен через `Import-Csv` под +русской локалью. Отчёты создаются в локальном игнорируемом каталоге `artifacts/soak/`. + +Критерии: + +- процесс не завершился и не завис; +- working set не превысил согласованный предел; +- журналы не вышли за лимит конфигурации; +- интерфейс остался на Home и принимает касания; +- COM-reconnect не создаёт повторной выдачи; +- после штатного завершения отсутствуют незакрытые операции, кроме явно смоделированных аварий. diff --git a/docs/operations/TECHNICAL_CONFIGURATION.md b/docs/operations/TECHNICAL_CONFIGURATION.md new file mode 100644 index 0000000..e59f62c --- /dev/null +++ b/docs/operations/TECHNICAL_CONFIGURATION.md @@ -0,0 +1,239 @@ +# Техническая конфигурация Exchanger + +## Назначение и расположение + +Монтажные параметры автомата хранятся отдельно от настроек владельца и не выводятся ни в одной +доступной вкладке приложения. Технический специалист меняет TOML при установке или обслуживании +автомата. + +Встроенный шаблон: + +```text +res://config/technical_settings.toml +``` + +Рабочий файл конкретного автомата: + +```text +user://config/technical_settings.toml +``` + +Для текущей Windows-сборки это обычно +`%APPDATA%\Godot\app_userdata\Exchanger\config\technical_settings.toml`. + +Для Linux-сборки это обычно +`~/.local/share/godot/app_userdata/Exchanger/config/technical_settings.toml`. + +При первом запуске приложение копирует встроенный шаблон в `user://config/`. Дальше рабочий файл +не перезаписывается автоматически, поэтому комментарии и монтажные значения сохраняются. + +## Порядок применения + +При старте приложение: + +1. загружает обычные настройки владельца из `appsettings.json`; +2. читает и полностью проверяет `technical_settings.toml`; +3. применяет аппаратные значения и optional `[theme]` из TOML поверх обычных JSON-настроек; +4. применяет явные аргументы `--theme-dlc`, `--no-theme-dlc` и `--mock-hardware` последними; +5. загружает выбранную тему и создаёт mock- или COM-транспорт. + +Изменение TOML во время работы ничего не переключает. После редактирования приложение необходимо +полностью перезапустить. + +## Полный пример + +```toml +version = 1 + +[theme] +enabled = true +directory = "user://theme_dlc" +file_name = "active_theme" + +[controller] +use_mock = true +port = "COM3" +baud_rate = 115200 +reconnect_interval_seconds = 30 +handshake_timeout_ms = 2000 +frame_timeout_ms = 100 +max_frame_length = 1024 +cashless_keep_alive_seconds = 120 + +[hopper_1] +enabled = true +stock_sensor_input = 1 +stock_low_active_high = false +dispense_sensor_input = 24 +dispense_pulse_active_high = false + +[hopper_2] +enabled = true +stock_sensor_input = 4 +stock_low_active_high = false +dispense_sensor_input = 25 +dispense_pulse_active_high = false + +[service] +button_input = 8 +button_active_high = false + +[polling] +input_poll_ms = 100 +stock_poll_seconds = 5 +``` + +## Каталог и выбор темы + +Необязательный раздел `[theme]` позволяет монтажнику выбрать PCK без изменения настроек владельца: + +```toml +[theme] +enabled = true +directory = "/opt/exchanger/themes" +file_name = "space-pixel" +``` + +Приложение загрузит `/opt/exchanger/themes/space-pixel.pck`. `directory` принимает `user://` либо +абсолютный локальный путь текущей ОС; относительные пути, `res://` и сегменты `..` запрещены. +`file_name` содержит только имя файла без каталога и расширения `.pck`. На Windows поддерживаются +оба обычных представления: + +```toml +# Рекомендуемый вариант с literal-строкой: обратные слеши не экранируются. +directory = 'D:\Exchanger\themes' + +# Либо путь с прямыми слешами. +directory = "D:/Exchanger/themes" +``` + +Если Windows-путь записывается в двойных кавычках с обратными слешами, каждый `\` по правилам +TOML необходимо удвоить: `directory = "D:\\Exchanger\\themes"`. + +`enabled = false` отключает внешний PCK. Раздел является авторитетным относительно полей Themes +в `appsettings.json`, но разовый аргумент `--theme-dlc=<полный путь>` или `--no-theme-dlc` имеет +более высокий приоритет. Старые файлы версии 1 без `[theme]` остаются совместимыми: тогда выбор +темы по-прежнему берётся из `appsettings.json`. + +## Основной контроллер + +| Параметр | Назначение | Допустимое значение | +|---|---|---| +| `use_mock` | Программный имитатор вместо платы | `true` или `false` | +| `port` | Порт основного контроллера | Windows: `COM1`…`COM256` или `COM` для автопоиска; Linux: `/dev/ttyUSB*`, `/dev/ttyACM*`, `/dev/serial/by-id/*` или `ttyUSB`/`/dev/ttyUSB` для автопоиска | +| `baud_rate` | Скорость последовательного порта | 9600, 19200, 38400, 57600, 115200, 230400, 460800 или 921600 | +| `reconnect_interval_seconds` | Пауза перед повторным подключением | 1…60 с | +| `handshake_timeout_ms` | Общий предел ожидания авторизации платы | 1000…60000 мс | +| `frame_timeout_ms` | Ожидание продолжения неполного кадра | 10…5000 мс | +| `max_frame_length` | Максимальная длина входного кадра | 2…65536 байт | +| `cashless_keep_alive_seconds` | Интервал keep-alive Вендиста | 30…170 с; штатно 120 с | + +Первое открытие порта выполняется сразу при запуске. Если платы нет или открыть устройство не +удалось, следующая попытка выполняется через `reconnect_interval_seconds`, после чего повторяется +с тем же интервалом. При физическом отключении уже работавшей платы новый полный интервал +отсчитывается от обнаруженного обрыва: старый дедлайн запуска не используется. Штатное значение — +30 секунд. Автоматически повторяются только подключение и авторизация; команда оплаты или выдачи +после обрыва не отправляется повторно. Полное имя (`COM3`, `/dev/ttyUSB0`, `ttyUSB0` и т. п.) +всегда открывается как один заданный порт. Значение `COM` включает автопоиск: на каждом +начальном подключении и каждом reconnect приложение получает список доступных COM-портов, +сортирует их по номеру от `COM0` и последовательно пробует до успешной авторизации. Значение +`ttyUSB` (также допустимо `/dev/ttyUSB`) аналогично перебирает `/dev/ttyUSB0`, +`/dev/ttyUSB1` и далее. Открытие чужого последовательного устройства или ошибка/таймаут +авторизации не считаются успешным подключением: поиск продолжается со следующим номером. + +Безопасный шаблон содержит `use_mock = true`: простого копирования файла недостаточно для выхода +на реальную плату. При вводе автомата в эксплуатацию нужно задать правильный порт, проверить +остальные разделы и только затем изменить значение на `false`. + +Формат `port` проверяется по ОС, на которой запущено приложение. Windows-сборка с реальной платой +принимает строгие имена `COM1`…`COM256` или префикс `COM`; Linux-сборка — `/dev/ttyUSB*`, +`/dev/ttyACM*`, стабильные udev-ссылки `by-id`, префикс `ttyUSB` (с необязательным `/dev/`) и короткие точные имена `ttyUSB0`, `ttyUSB1` и т. д. +При `use_mock = true` имя порта не используется и не проверяется, +поэтому общий безопасный шаблон с `COM3` запускается и в Linux. + +Для Silicon Labs CP210x после подключения обычно используется: + +```toml +[controller] +use_mock = false +port = "/dev/ttyUSB0" +``` + +Если каталог `/dev/serial/by-id/` создан udev, предпочтительнее указать находящуюся в нём +постоянную ссылку: она не меняется при перестановке USB-устройств. Отсутствие самого каталога +не является ошибкой — тогда используется `/dev/ttyUSB0` или другой фактически назначенный номер. +Каталог `/dev/usb/` не является заменой узла последовательного порта. + +## Хопперы + +Разделы `hopper_1` и `hopper_2` имеют одинаковую структуру: + +| Параметр | Назначение | +|---|---| +| `enabled` | Установлен ли хоппер | +| `stock_sensor_input` | Индекс входа датчика малого остатка | +| `stock_low_active_high` | `true`, если высокий уровень означает «мало жетонов» | +| `dispense_sensor_input` | Индекс отдельного физического датчика выдачи | +| `dispense_pulse_active_high` | `true`, если высокий уровень означает импульс выдачи | + +Индекс входа задаётся числом 0…25. Значение `-1` означает, что отдельный физический вход не +назначен. Для текущей разводки первый датчик выдачи использует `IN24`, второй — `IN25`. +Обычная выдача подтверждается ответами `HOPPER1/2 OK`, а сервисный пересчёт — ответами +`HOPPER1/2 PULSE=1`, поэтому физические входы не создают двойной программный учёт. + +По `enabled` автоматически выбирается профиль команд: + +| Хоппер 1 | Хоппер 2 | Профиль | +|---|---|---| +| включён | включён | `DualHopperAuto` — команды `30X` и `40X` | +| включён | выключен | `Hopper1Auto` — команды `30X` | +| выключен | включён | `Hopper2Auto` — команды `40X` | +| выключен | выключен | выдача не поддерживается | + +У отключённого хоппера его входы принудительно становятся неактивными независимо от записанных +чисел. Так узел можно временно отключить, не удаляя его монтажную схему из файла. + +Если включён только один хоппер, приложение работает как одноканальное: выдача, сервисный +пересчёт, ручное пополнение, доступный покупателю остаток и mock-режим используют только этот +хоппер. Строка и кнопки отключённого хоппера скрываются в разделе «Сервис». Его сохранённый +учётный остаток не удаляется и снова станет доступен, если хоппер вернуть в конфигурацию. + +## Сервисная кнопка и опрос + +`service.button_input` задаёт индекс сервисной кнопки, 0…25 либо `-1`, если физическая кнопка +отключена. `service.button_active_high` задаёт полярность. Для текущей разводки используются +`IN8` и `false`. + +`polling.input_poll_ms` задаёт частоту резервного чтения входов в диапазоне 50…1000 мс. +`polling.stock_poll_seconds` задаёт медленный опрос запаса в диапазоне 1…60 с. + +## Проверка и безопасное восстановление + +Все прежние разделы и поля обязательны; новый `[theme]` целиком необязателен для совместимости. +Если `[theme]` присутствует, обязательны все три его поля. Приложение отклоняет файл целиком, если: + +- TOML имеет синтаксическую ошибку; +- отсутствует поле или раздел; +- версия схемы не равна 1; +- значение вышло за разрешённый диапазон; +- один неотрицательный индекс `IN` назначен нескольким активным функциям. +- каталог темы не является `user://` или абсолютным локальным путём; +- `file_name` содержит путь либо расширение. + +Некорректный пользовательский файл не исправляется и не перезаписывается автоматически. Приложение +выдаёт предупреждение и запускается со встроенным профилем, где `use_mock = true`. Ошибочный +монтажный файл поэтому не может случайно включить реальное оборудование. + +AES-ключ, платёжные секреты, PIN владельца, сырые команды и ответы платы в TOML не добавляются. + +## Чек-лист технической настройки + +1. Остановить приложение. +2. Открыть рабочий `user://config/technical_settings.toml`. +3. Проверить имя последовательного порта текущей ОС и наличие каждого хоппера. +4. Проверить `reconnect_interval_seconds = 30` либо установить другой допустимый интервал. +5. Сверить индексы и полярности подключённых входов. +6. Проверить `[theme].directory` и указать `[theme].file_name` без `.pck`. +7. Оставить `use_mock = true` для первой проверки интерфейса. +8. После проверки платы изменить `use_mock` на `false`. +9. Полностью запустить приложение заново и выполнить отдельный приёмочный прогон оборудования. diff --git a/docs/operations/WINDOWS_EXPORT.md b/docs/operations/WINDOWS_EXPORT.md new file mode 100644 index 0000000..6fead63 --- /dev/null +++ b/docs/operations/WINDOWS_EXPORT.md @@ -0,0 +1,104 @@ +# Debug и Release export для Windows x64 + +## Требования + +- официальный Godot 4.7.1 Mono; +- export templates той же версии; +- .NET SDK 8; +- PowerShell 5.1 или новее. + +## Native Video + +`addons/native_video` — runtime GDExtension, а не editor-addon: его манифест и Windows DLL +автоматически входят в оба export-пресета. Для MP4/MOV/M4V проект работает с рендерером Mobile +(Vulkan); Compatibility для этого расширения не подходит. После каждого export нужно проверить +воспроизведение реального ролика на целевом GPU, потому что headless smoke не создаёт RenderingDevice. + +## Пресеты + +В проекте есть два самостоятельных Windows-пресета: + +- `Windows x64 Release` — production-фича, без debug symbols и консольного wrapper; +- `Windows x64 Debug` — development-фича, с debug symbols, исходниками C# и консольным wrapper. + +В Godot режим шаблона всё равно определяется действием экспорта. Для гарантированного результата +используйте скрипт ниже: он вызывает `--export-release` или `--export-debug` в соответствии с +выбранной конфигурацией. + +## Сборка + +Из корня проекта: + +```powershell +powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\export-windows.ps1 +``` + +Эта команда равнозначна явной Release-сборке: + +```powershell +.\tools\export-windows.ps1 -Configuration Release +``` + +Отладочная сборка: + +```powershell +.\tools\export-windows.ps1 -Configuration Debug +``` + +Другой путь к Godot передаётся явно: + +```powershell +.\tools\export-windows.ps1 -Configuration Release -GodotPath "D:\Godot\Godot_v4.7.1-stable_mono_win64.exe" +``` + +Результат создаётся в новом каталоге +`artifacts/windows/Exchanger-0.6.0--YYYYMMDD-HHMMSS/`; существующие сборки не +перезаписываются. Release-файл называется `Exchanger.exe`. Debug создаёт основной +`Exchanger.Debug.exe` и консольный wrapper `Exchanger.Debug.console.exe`. + +## Изоляция production-проекта + +Скрипт создаёт временную staging-копию внутри `artifacts/export-staging`, проверяет абсолютный +путь перед каждым рекурсивным удалением и очищает staging в `finally`. + +В staging и PCK не попадают: + +- `.git`, `.godot`, `.agents`, `.vscode`; +- `references/`, `tests/`, `tools/`, `docs/`, `artifacts/`; +- все editor/development addons. + +Из staging-версии `project.godot` удаляются editor plugins и два development-autoload: +`GodotxToast` и `_mcp_game_helper`. Исходный проект при этом не меняется, поэтому редакторская +автоматизация продолжает работать после экспорта. + +## Состав и проверка + +Оба пресета встраивают PCK и .NET outputs в EXE. Release не включает debug symbols и C#-исходники; +Debug включает их и использует консольный wrapper. Тестовые сборки и editor-addon файлы не входят +ни в один вариант. + +Контрольный экспорт 2026-09-02: + +- Debug: `Exchanger.Debug.exe` — 185175952 байта, console wrapper — 91136 байт; +- Release: один `Exchanger.exe` — 190151408 байт; +- оба основных EXE завершили headless smoke с mock-оборудованием и exit code 0; +- эти контрольные файлы не подписаны Authenticode; подпись остаётся отдельным release-шагом. + +Короткий автоматический smoke-run без открытия окна: + +```powershell +$exe = ".\artifacts\windows\\Exchanger.exe" +Start-Process $exe -ArgumentList "--headless", "--quit-after", "180", "--no-theme-dlc" -Wait +``` + +Первый проверенный export 0.6.0 содержал 189 файлов и занимал 180,8 МиБ; headless smoke завершился +с exit code 0. Эти числа являются диагностическими и могут меняться вместе с Godot/.NET. + +## Перед релизом + +- выполнить `dotnet test Exchanger.sln`; +- установить актуальный `active_theme.pck` либо отдельно проверить fallback; +- проверить реальный COM-порт и аппаратную приёмку; +- выполнить чистую установку на отдельном Windows-устройстве; +- при необходимости подписать EXE и DLL; +- сохранить checksum каталога релиза и совместимую версию конфигурации контроллера. diff --git a/docs/operations/WINDOWS_KIOSK_SETUP.md b/docs/operations/WINDOWS_KIOSK_SETUP.md new file mode 100644 index 0000000..076f70f --- /dev/null +++ b/docs/operations/WINDOWS_KIOSK_SETUP.md @@ -0,0 +1,78 @@ +# Настройка Windows-киоска Exchanger + +## Граница ответственности + +Exchanger в production включает borderless fullscreen, скрывает курсор и восстанавливает +полноэкранный режим после смены фокуса, дисплея или разрешения. Приложение не может блокировать +`Ctrl+Alt+Del`, системные жесты, переключение пользователя и аварийные средства Windows. +Эти ограничения настраиваются операционной системой. + +## Выделенная учётная запись + +1. Создайте локального пользователя без административных прав, предназначенного только для автомата. +2. Запретите интерактивный доступ к рабочим документам и сетевым ресурсам, которые не нужны Exchanger. +3. Выдайте пользователю права записи только в `%APPDATA%\Godot\app_userdata\Exchanger` и каталог установки, если обновление выполняется отдельным сервисом. +4. Настройте автоматический вход только после оценки физической безопасности автомата. +5. Для полной блокировки оболочки используйте Windows Assigned Access либо Shell Launcher в поддерживаемой редакции Windows. Не переименовывайте exe и не заменяйте системную оболочку до проверки процедуры восстановления. + +## Автозапуск и watchdog + +В `tools/windows` находятся: + +- `Exchanger.Watchdog.ps1` — запускает приложение и перезапускает его после завершения; +- `Install-ExchangerKioskTask.ps1` — создаёт задачу Планировщика при входе выделенного пользователя; +- `Uninstall-ExchangerKioskTask.ps1` — удаляет только эту задачу. + +Установка выполняется вручную из PowerShell под киоск-пользователем: + +```powershell +.\tools\windows\Install-ExchangerKioskTask.ps1 ` + -ExecutablePath 'C:\Program Files\Exchanger\Exchanger.exe' ` + -WhatIf + +.\tools\windows\Install-ExchangerKioskTask.ps1 ` + -ExecutablePath 'C:\Program Files\Exchanger\Exchanger.exe' +``` + +Сначала обязательно используйте `-WhatIf`. Watchdog хранит собственный ограниченный журнал в +`%LOCALAPPDATA%\Exchanger\watchdog`; пользовательские журналы приложения находятся отдельно в +`%APPDATA%\Godot\app_userdata\Exchanger\logs`. + +## Питание и дисплей + +- отключите сон, гибернацию и автоматическое выключение дисплея для киоск-профиля; +- запретите USB selective suspend для подтверждённого COM-контроллера; +- задайте фиксированную портретную ориентацию и масштаб Windows; +- отключите автоматическое подключение беспроводных дисплеев; +- после замены монитора проверьте 1080×1920 и fallback 720×1280; +- настройте автоматическое включение ПК после восстановления питания в BIOS/UEFI. + +## Защищённый сервисный вход + +Production не реагирует на `F10`. Экран PIN открывается только после физического сообщения +`SERVICE` от периферийного контроллера и только когда пользовательская операция не выполняется. +Защита включается в разделе «Общие» настроек владельца. После автосохранения и выхода следующий +вход показывает создание PIN: необходимо ввести и повторить от 4 до 12 цифр. Последующие входы +проверяют этот PIN; после пяти ошибок вход блокируется на 30 секунд. Кнопка «Сбросить PIN» удаляет +старые проверочные данные, после чего новый PIN задаётся при следующем входе. + +Открытый PIN не входит в `appsettings.json`, резервную копию, журналы или diagnostic UI. В секции +`Security` сохраняются только случайная соль, PBKDF2-SHA256-хеш и число итераций. Доступ к самому +файлу конфигурации и учётной записи Windows всё равно должен быть ограничен средствами ОС. +AES-ключ, платёжные данные и сырые команды контроллера через UI недоступны. + +## Приёмка после настройки + +1. Перезагрузите Windows и убедитесь, что появляется только Exchanger. +2. Завершите процесс через диспетчер задач из административной сессии и проверьте перезапуск. +3. Смените разрешение/отключите тестовый монитор и проверьте восстановление fullscreen. +4. Убедитесь, что клавиатура пользователя не открывает сервисные функции release-сборки. +5. Нажмите физическую кнопку `SERVICE`, проверьте PIN и блокировку после пяти ошибок. +6. Проверьте штатное удаление задачи через `Uninstall-ExchangerKioskTask.ps1 -WhatIf`, затем без `-WhatIf` на тестовом стенде. + +## Восстановление + +Держите отдельную административную учётную запись и документированный способ временно вернуть +Explorer. До обновления сохраняйте подписанный установочный пакет и последнюю рабочую версию. +Не удаляйте `appsettings.json.bak`: приложение использует её для восстановления после повреждения +или обрыва питания во время записи. diff --git a/export_presets.cfg b/export_presets.cfg new file mode 100644 index 0000000..6472ef3 --- /dev/null +++ b/export_presets.cfg @@ -0,0 +1,171 @@ +[preset.0] + +name="Windows x64 Release" +platform="Windows Desktop" +dedicated_server=false +custom_features="production" +export_filter="all_resources" +include_filter="config/*.toml" +exclude_filter="references/**,tests/**,tools/**,docs/**,artifacts/**,.agents/**,.vscode/**,addons/godot_ai/**,addons/log/**,addons/reload_current_scene/**" +export_path="artifacts/windows/Release/Exchanger.exe" +patches=PackedStringArray() +patch_delta_encoding=false +patch_delta_compression_level_zstd=19 +patch_delta_min_reduction=0.1 +patch_delta_include_filters="*" +patch_delta_exclude_filters="" +encryption_include_filters="" +encryption_exclude_filters="" +seed=0 +encrypt_pck=false +encrypt_directory=false +script_export_mode=2 + +[preset.0.options] + +custom_template/debug="" +custom_template/release="" +debug/export_console_wrapper=0 +binary_format/embed_pck=true +texture_format/s3tc_bptc=true +texture_format/etc2_astc=false +shader_baker/enabled=false +binary_format/architecture="x86_64" +codesign/enable=true +codesign/timestamp=true +codesign/timestamp_server_url="http://timestamp.digicert.com" +codesign/digest_algorithm=1 +codesign/description="Программа для аппарата размена жетонов" +codesign/custom_options=PackedStringArray() +application/modify_resources=true +application/icon="res://icon.svg" +application/console_wrapper_icon="res://icon.svg" +application/icon_interpolation=4 +application/file_version="0.6.0.0" +application/product_version="0.6.0.0" +application/company_name="Robotail" +application/product_name="Exchanger" +application/file_description="Вендинговый аппарат выдачи жетонов" +application/copyright="" +application/trademarks="" +application/export_angle=0 +application/export_d3d12=0 +application/d3d12_agility_sdk_multiarch=true +ssh_remote_deploy/enabled=false +ssh_remote_deploy/host="user@host_ip" +ssh_remote_deploy/port="22" +ssh_remote_deploy/extra_args_ssh="" +ssh_remote_deploy/extra_args_scp="" +ssh_remote_deploy/run_script="" +ssh_remote_deploy/cleanup_script="" +dotnet/include_scripts_content=false +dotnet/include_debug_symbols=false +dotnet/embed_build_outputs=true + +[preset.1] + +name="Windows x64 Debug" +platform="Windows Desktop" +dedicated_server=false +custom_features="development" +export_filter="all_resources" +include_filter="config/*.toml" +exclude_filter="references/**,tests/**,tools/**,docs/**,artifacts/**,.agents/**,.vscode/**,addons/godot_ai/**,addons/log/**,addons/reload_current_scene/**" +export_path="artifacts/windows/debug/Exchanger.Debug.exe" +patches=PackedStringArray() +patch_delta_encoding=false +patch_delta_compression_level_zstd=19 +patch_delta_min_reduction=0.1 +patch_delta_include_filters="*" +patch_delta_exclude_filters="" +encryption_include_filters="" +encryption_exclude_filters="" +seed=0 +encrypt_pck=false +encrypt_directory=false +script_export_mode=2 + +[preset.1.options] + +custom_template/debug="" +custom_template/release="" +debug/export_console_wrapper=1 +binary_format/embed_pck=true +texture_format/s3tc_bptc=true +texture_format/etc2_astc=false +shader_baker/enabled=false +binary_format/architecture="x86_64" +codesign/enable=false +codesign/timestamp=false +codesign/timestamp_server_url="http://timestamp.digicert.com" +codesign/digest_algorithm=1 +codesign/description="Отладочная сборка Exchanger" +codesign/custom_options=PackedStringArray() +application/modify_resources=true +application/icon="res://icon.svg" +application/console_wrapper_icon="res://icon.svg" +application/icon_interpolation=4 +application/file_version="0.6.0.0" +application/product_version="0.6.0.0" +application/company_name="Robotail" +application/product_name="Exchanger Debug" +application/file_description="Отладочная сборка вендингового аппарата выдачи жетонов" +application/copyright="" +application/trademarks="" +application/export_angle=0 +application/export_d3d12=0 +application/d3d12_agility_sdk_multiarch=true +ssh_remote_deploy/enabled=false +ssh_remote_deploy/host="user@host_ip" +ssh_remote_deploy/port="22" +ssh_remote_deploy/extra_args_ssh="" +ssh_remote_deploy/extra_args_scp="" +ssh_remote_deploy/run_script="" +ssh_remote_deploy/cleanup_script="" +dotnet/include_scripts_content=true +dotnet/include_debug_symbols=true +dotnet/embed_build_outputs=true + +[preset.2] + +name="Linux x86_64 (Debian 13)" +platform="Linux" +dedicated_server=false +custom_features="production" +export_filter="all_resources" +include_filter="config/*.toml" +exclude_filter="references/**,tests/**,tools/**,docs/**,artifacts/**,.agents/**,.vscode/**,addons/godot_ai/**,addons/log/**,addons/reload_current_scene/**" +export_path="artifacts/linux/debian13/Exchanger.x86_64" +patches=PackedStringArray() +patch_delta_encoding=false +patch_delta_compression_level_zstd=19 +patch_delta_min_reduction=0.1 +patch_delta_include_filters="*" +patch_delta_exclude_filters="" +encryption_include_filters="" +encryption_exclude_filters="" +seed=0 +encrypt_pck=false +encrypt_directory=false +script_export_mode=2 + +[preset.2.options] + +custom_template/debug="" +custom_template/release="" +debug/export_console_wrapper=1 +binary_format/embed_pck=true +texture_format/s3tc_bptc=true +texture_format/etc2_astc=false +shader_baker/enabled=false +binary_format/architecture="x86_64" +ssh_remote_deploy/enabled=false +ssh_remote_deploy/host="user@host_ip" +ssh_remote_deploy/port="22" +ssh_remote_deploy/extra_args_ssh="" +ssh_remote_deploy/extra_args_scp="" +ssh_remote_deploy/run_script="" +ssh_remote_deploy/cleanup_script="" +dotnet/include_scripts_content=false +dotnet/include_debug_symbols=false +dotnet/embed_build_outputs=true diff --git a/godot-ai-LICENSE.txt b/godot-ai-LICENSE.txt new file mode 100644 index 0000000..7806d22 --- /dev/null +++ b/godot-ai-LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Godot AI contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/icon.svg b/icon.svg new file mode 100644 index 0000000..c6bbb7d --- /dev/null +++ b/icon.svg @@ -0,0 +1 @@ + diff --git a/icon.svg.import b/icon.svg.import new file mode 100644 index 0000000..47fd7c0 --- /dev/null +++ b/icon.svg.import @@ -0,0 +1,43 @@ +[remap] + +importer="texture" +type="CompressedTexture2D" +uid="uid://bwshpc3cf1ni7" +path="res://.godot/imported/icon.svg-218a8f2b3041327d8a5756f3a245f83b.ctex" +metadata={ +"vram_texture": false +} + +[deps] + +source_file="res://icon.svg" +dest_files=["res://.godot/imported/icon.svg-218a8f2b3041327d8a5756f3a245f83b.ctex"] + +[params] + +compress/mode=0 +compress/high_quality=false +compress/lossy_quality=0.7 +compress/uastc_level=0 +compress/rdo_quality_loss=0.0 +compress/hdr_compression=1 +compress/normal_map=0 +compress/channel_pack=0 +mipmaps/generate=false +mipmaps/limit=-1 +roughness/mode=0 +roughness/src_normal="" +process/channel_remap/red=0 +process/channel_remap/green=1 +process/channel_remap/blue=2 +process/channel_remap/alpha=3 +process/fix_alpha_border=true +process/premult_alpha=false +process/normal_map_invert_y=false +process/hdr_as_srgb=false +process/hdr_clamp_exposure=false +process/size_limit=0 +detect_3d/compress_to=1 +svg/scale=1.0 +editor/scale_with_editor_scale=false +editor/convert_colors_with_editor_theme=false diff --git a/project.godot b/project.godot new file mode 100644 index 0000000..c4a3641 --- /dev/null +++ b/project.godot @@ -0,0 +1,82 @@ +; Engine configuration file. +; It's best edited using the editor UI and not directly, +; since the parameters that go here are not all obvious. +; +; Format: +; [section] ; section goes between [] +; param=value ; assign values to parameters + +config_version=5 + +[application] + +config/name="Exchanger" +config/name_localized={ +"ru_RU": "Размен жетонов" +} +config/description="Программа для аппарата размена жетонов" +config/version="0.6.0" +run/main_scene="res://src/scenes/App/App.tscn" +run/enable_alt_space_menu=true +config/features=PackedStringArray("4.7", "C#", "Mobile") +boot_splash/image="uid://bkcx4v1p6ajo3" +config/icon="uid://bexp3q7mygd6c" +config/macos_native_icon="res://src/images/icon.icns" +config/windows_native_icon="res://src/images/icon.ico" + +[autoload] + +GodotxToast="*uid://bgvixrj72u7rv" +ThemeManager="*res://src/core/ThemeManager/ThemeManager.cs" +ScreenManager="*res://src/core/Navigation/ScreenManager.cs" +_mcp_game_helper="*res://addons/godot_ai/runtime/game_helper.gd" + +[display] + +window/size/viewport_width=720 +window/size/viewport_height=1280 +window/size/mode=3 +window/size/borderless=true +window/stretch/mode="canvas_items" +window/stretch/aspect="expand" + +[dotnet] + +project/assembly_name="Exchanger" + +[editor_plugins] + +enabled=PackedStringArray("res://addons/godot_ai/plugin.cfg", "res://addons/godotx_toast/plugin.cfg", "res://addons/log/plugin.cfg", "res://addons/reload_current_scene/plugin.cfg") + +[input] + +kiosk_back={ +"deadzone": 0.5, +"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":4194305,"physical_keycode":0,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null) +] +} +debug_service_settings={ +"deadzone": 0.5, +"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":4194341,"physical_keycode":0,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null) +] +} + +[input_devices] + +pointing/emulate_touch_from_mouse=true + +[internationalization] + +locale/locale_filter_mode=0 + +[log_gd] + +config/timestamp_type=4 + +[physics] + +3d/physics_engine="Jolt Physics" + +[rendering] + +rendering_device/driver.windows="d3d12" diff --git a/src/Properties/AssemblyInfo.cs b/src/Properties/AssemblyInfo.cs new file mode 100644 index 0000000..b721102 --- /dev/null +++ b/src/Properties/AssemblyInfo.cs @@ -0,0 +1,3 @@ +using System.Runtime.CompilerServices; + +[assembly: InternalsVisibleTo("Exchanger.Tests")] diff --git a/src/Properties/AssemblyInfo.cs.uid b/src/Properties/AssemblyInfo.cs.uid new file mode 100644 index 0000000..5bf8c6e --- /dev/null +++ b/src/Properties/AssemblyInfo.cs.uid @@ -0,0 +1 @@ +uid://d0nowcw8vto1b diff --git a/src/core/Audio/AudioSettingsApplier.cs b/src/core/Audio/AudioSettingsApplier.cs new file mode 100644 index 0000000..61e092f --- /dev/null +++ b/src/core/Audio/AudioSettingsApplier.cs @@ -0,0 +1,56 @@ +using Exchanger.Core.Configuration; +using Godot; +using System; + +namespace Exchanger.Core.Audio; + +/// Применяет нормализованные настройки звука к Godot audio buses. +public static class AudioSettingsApplier +{ + public const float MinimumDecibels = -80.0f; + private const float LowestAudibleDecibels = -60.0f; + public const string MasterBusName = "Master"; + public const string AdvertisementBusName = "Advertisement"; + + public static void Apply(AudioSettings settings) + { + ArgumentNullException.ThrowIfNull(settings); + + ApplyBus( + MasterBusName, + settings.MasterVolumePercent, + settings.Muted || settings.MasterVolumePercent <= 0); + ApplyBus( + AdvertisementBusName, + settings.AdvertisementVolumePercent, + settings.AdvertisementVolumePercent <= 0); + } + + public static float PercentToDecibels(int percent) + { + int normalized = Math.Clamp(percent, 0, 100); + if (normalized == 0) + { + return MinimumDecibels; + } + + // «Процент громкости» в интерфейсе — это воспринимаемая пользователем + // шкала, а не линейная амплитуда. Равномерный диапазон -60..0 dB + // позволяет низким значениям быть действительно тихими: 3 % ≈ -58 dB. + return LowestAudibleDecibels + + (0.0f - LowestAudibleDecibels) * normalized / 100.0f; + } + + private static void ApplyBus(string busName, int volumePercent, bool muted) + { + int busIndex = AudioServer.GetBusIndex(busName); + if (busIndex < 0) + { + GD.PushWarning($"Не найден аудиоканал {busName}; настройки громкости не применены."); + return; + } + + AudioServer.SetBusVolumeDb(busIndex, PercentToDecibels(volumePercent)); + AudioServer.SetBusMute(busIndex, muted); + } +} diff --git a/src/core/Audio/AudioSettingsApplier.cs.uid b/src/core/Audio/AudioSettingsApplier.cs.uid new file mode 100644 index 0000000..0fe7475 --- /dev/null +++ b/src/core/Audio/AudioSettingsApplier.cs.uid @@ -0,0 +1 @@ +uid://d0jlktcdiphrf diff --git a/src/core/Configuration/AdvertisementPlaybackSettingsSnapshot.cs b/src/core/Configuration/AdvertisementPlaybackSettingsSnapshot.cs new file mode 100644 index 0000000..ab6f1b3 --- /dev/null +++ b/src/core/Configuration/AdvertisementPlaybackSettingsSnapshot.cs @@ -0,0 +1,46 @@ +using System; +using System.Linq; + +namespace Exchanger.Core.Configuration; + +/// +/// Неизменяемый снимок параметров, влияющих на уже созданный промо-поток. +/// Нужен, потому что Settings может изменить исходный объект до вызова Configure. +/// +internal sealed class AdvertisementPlaybackSettingsSnapshot +{ + private AdvertisementPlaybackSettingsSnapshot(AdvertisementSettings settings) + { + Enabled = settings.Enabled; + Muted = settings.Muted; + FallbackText = settings.FallbackText ?? string.Empty; + PosterPath = AdvertisementVideoLibrary.NormalizeSelectedVideo(settings.PosterPath ?? string.Empty); + VideoPaths = (settings.VideoPaths ?? Array.Empty()) + .Select(AdvertisementVideoLibrary.NormalizeSelectedVideo) + .ToArray(); + } + + private bool Enabled { get; } + private bool Muted { get; } + private string FallbackText { get; } + private string PosterPath { get; } + private string[] VideoPaths { get; } + + public static AdvertisementPlaybackSettingsSnapshot Capture(AdvertisementSettings settings) => new(settings); + + public bool Matches(AdvertisementSettings settings) + { + return Enabled == settings.Enabled + && Muted == settings.Muted + && string.Equals(FallbackText, settings.FallbackText ?? string.Empty, StringComparison.Ordinal) + && string.Equals( + AdvertisementVideoLibrary.GetComparisonKey(PosterPath), + AdvertisementVideoLibrary.GetComparisonKey(settings.PosterPath ?? string.Empty), + StringComparison.Ordinal) + && VideoPaths.SequenceEqual( + (settings.VideoPaths ?? Array.Empty()) + .Select(AdvertisementVideoLibrary.NormalizeSelectedVideo) + .Select(AdvertisementVideoLibrary.GetComparisonKey), + StringComparer.Ordinal); + } +} diff --git a/src/core/Configuration/AdvertisementPlaybackSettingsSnapshot.cs.uid b/src/core/Configuration/AdvertisementPlaybackSettingsSnapshot.cs.uid new file mode 100644 index 0000000..d3b988f --- /dev/null +++ b/src/core/Configuration/AdvertisementPlaybackSettingsSnapshot.cs.uid @@ -0,0 +1 @@ +uid://b5law3pgryl27 diff --git a/src/core/Configuration/AdvertisementSettingsValidator.cs b/src/core/Configuration/AdvertisementSettingsValidator.cs new file mode 100644 index 0000000..1c73d3d --- /dev/null +++ b/src/core/Configuration/AdvertisementSettingsValidator.cs @@ -0,0 +1,215 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; + +namespace Exchanger.Core.Configuration; + +public enum AdvertisementAssetType +{ + Poster, + Video, +} + +public enum AdvertisementValidationField +{ + FallbackText, + PosterPath, + VideoPath, + Playlist, +} + +public readonly record struct AdvertisementValidationIssue( + AdvertisementValidationField Field, + string Message, + int VideoIndex = -1); + +public sealed class AdvertisementValidationResult +{ + public AdvertisementValidationResult(IReadOnlyList issues) + { + Issues = issues ?? throw new ArgumentNullException(nameof(issues)); + } + + public IReadOnlyList Issues { get; } + + public bool IsValid => Issues.Count == 0; +} + +/// Проверяет только локальные промо-ресурсы и безопасные ограничения плейлиста. +public static class AdvertisementSettingsValidator +{ + public const int MaximumFallbackTextLength = 120; + public const int MaximumAssetPathLength = 512; + public const int MaximumVideoPaths = 12; + + private static readonly HashSet PosterExtensions = new(StringComparer.OrdinalIgnoreCase) + { + ".png", + ".jpg", + ".jpeg", + ".webp", + }; + + private static readonly HashSet VideoExtensions = new(StringComparer.OrdinalIgnoreCase) + { + ".ogv", + ".mp4", + ".mov", + ".m4v", + }; + + public static AdvertisementValidationResult Validate( + AdvertisementSettings settings, + Func? assetExists = null) + { + ArgumentNullException.ThrowIfNull(settings); + + var issues = new List(); + if (!settings.Enabled) + { + return new AdvertisementValidationResult(issues); + } + + ValidateFallback(settings.FallbackText, issues); + if (!string.IsNullOrWhiteSpace(settings.PosterPath)) + { + ValidateAssetPath( + settings.PosterPath, + AdvertisementAssetType.Poster, + AdvertisementValidationField.PosterPath, + -1, + assetExists, + issues); + } + + string[] paths = settings.VideoPaths ?? Array.Empty(); + if (paths.Length > MaximumVideoPaths) + { + issues.Add(new AdvertisementValidationIssue( + AdvertisementValidationField.Playlist, + $"Можно добавить не больше {MaximumVideoPaths} промо-роликов.")); + } + + for (int index = 0; index < paths.Length; index++) + { + ValidateAssetPath( + paths[index], + AdvertisementAssetType.Video, + AdvertisementValidationField.VideoPath, + index, + assetExists, + issues); + } + + foreach (IGrouping duplicate in paths + .Select((path, index) => (Path: AdvertisementVideoLibrary.NormalizeSelectedVideo(path ?? string.Empty), Index: index)) + .Where(item => item.Path.Length > 0) + .GroupBy(item => AdvertisementVideoLibrary.GetComparisonKey(item.Path), StringComparer.Ordinal) + .Where(group => group.Count() > 1)) + { + foreach ((string _, int index) in duplicate) + { + issues.Add(new AdvertisementValidationIssue( + AdvertisementValidationField.VideoPath, + "Этот промо-ролик уже добавлен.", + index)); + } + } + + return new AdvertisementValidationResult(issues); + } + + private static void ValidateFallback( + string? value, + ICollection issues) + { + string trimmed = value?.Trim() ?? string.Empty; + if (trimmed.Length == 0) + { + issues.Add(new AdvertisementValidationIssue( + AdvertisementValidationField.FallbackText, + "Введите текст, который будет показан вместо промо.")); + return; + } + + if (trimmed.Length > MaximumFallbackTextLength) + { + issues.Add(new AdvertisementValidationIssue( + AdvertisementValidationField.FallbackText, + $"Текст вместо промо — не больше {MaximumFallbackTextLength} знаков.")); + } + + if (trimmed.Any(char.IsControl)) + { + issues.Add(new AdvertisementValidationIssue( + AdvertisementValidationField.FallbackText, + "Введите текст вместо промо в одну строку.")); + } + } + + private static void ValidateAssetPath( + string? value, + AdvertisementAssetType assetType, + AdvertisementValidationField field, + int videoIndex, + Func? assetExists, + ICollection issues) + { + string path = value?.Trim() ?? string.Empty; + string caption = assetType == AdvertisementAssetType.Poster ? "Постер" : "Промо-ролик"; + if (path.Length == 0) + { + issues.Add(new AdvertisementValidationIssue(field, $"Укажите путь к файлу «{caption}».", videoIndex)); + return; + } + + if (path.Length > MaximumAssetPathLength || path.Any(char.IsControl)) + { + issues.Add(new AdvertisementValidationIssue(field, $"Проверьте путь к файлу «{caption}».", videoIndex)); + return; + } + + bool resourcePath = path.StartsWith("res://", StringComparison.OrdinalIgnoreCase) + || path.StartsWith("user://", StringComparison.OrdinalIgnoreCase); + if (!resourcePath && !Path.IsPathFullyQualified(path)) + { + issues.Add(new AdvertisementValidationIssue( + field, + $"Укажите полный путь к файлу «{caption}».", + videoIndex)); + return; + } + + string normalized = path.Replace('\\', '/'); + if (normalized.Split('/').Any(segment => segment == "..")) + { + issues.Add(new AdvertisementValidationIssue(field, $"Путь к файлу «{caption}» не должен содержать «..».", videoIndex)); + return; + } + + string extension = Path.GetExtension(path); + bool supported = assetType == AdvertisementAssetType.Poster + ? PosterExtensions.Contains(extension) + : VideoExtensions.Contains(extension); + if (!supported) + { + string formats = assetType == AdvertisementAssetType.Poster + ? "PNG, JPG, JPEG или WEBP" + : "OGV, MP4, MOV или M4V"; + issues.Add(new AdvertisementValidationIssue( + field, + $"Для файла «{caption}» нужен формат {formats}.", + videoIndex)); + return; + } + + if (assetExists is not null && !assetExists(path, assetType)) + { + issues.Add(new AdvertisementValidationIssue( + field, + $"Не удалось открыть файл «{caption}». Проверьте путь.", + videoIndex)); + } + } +} diff --git a/src/core/Configuration/AdvertisementSettingsValidator.cs.uid b/src/core/Configuration/AdvertisementSettingsValidator.cs.uid new file mode 100644 index 0000000..d4f2d55 --- /dev/null +++ b/src/core/Configuration/AdvertisementSettingsValidator.cs.uid @@ -0,0 +1 @@ +uid://cb5r70kf7ptb4 diff --git a/src/core/Configuration/AdvertisementVideoLibrary.cs b/src/core/Configuration/AdvertisementVideoLibrary.cs new file mode 100644 index 0000000..e5d2b93 --- /dev/null +++ b/src/core/Configuration/AdvertisementVideoLibrary.cs @@ -0,0 +1,29 @@ +using System; + +namespace Exchanger.Core.Configuration; + +/// +/// Нормализует выбранный путь, не копируя и не переименовывая внешний промо-ролик. +/// Native Video передаёт абсолютные Windows drive-path в Media Foundation как +/// UTF-16 file URI, поэтому Unicode-пути не требуют служебных ссылок. +/// +public static class AdvertisementVideoLibrary +{ + public static string NormalizeSelectedVideo(string sourcePath) + { + ArgumentNullException.ThrowIfNull(sourcePath); + return sourcePath.Trim().Replace('\\', '/'); + } + + /// + /// Возвращает ключ для поиска одного и того же файла в плейлисте и кэше. + /// На Windows имена файлов регистронезависимы, на Linux регистр сохраняется. + /// + public static string GetComparisonKey(string sourcePath) + { + string normalized = NormalizeSelectedVideo(sourcePath); + return OperatingSystem.IsWindows() + ? normalized.ToUpperInvariant() + : normalized; + } +} diff --git a/src/core/Configuration/AdvertisementVideoLibrary.cs.uid b/src/core/Configuration/AdvertisementVideoLibrary.cs.uid new file mode 100644 index 0000000..977f839 --- /dev/null +++ b/src/core/Configuration/AdvertisementVideoLibrary.cs.uid @@ -0,0 +1 @@ +uid://dtpnwl44dcxxn diff --git a/src/core/Configuration/AppSettings.cs b/src/core/Configuration/AppSettings.cs new file mode 100644 index 0000000..05bcbbf --- /dev/null +++ b/src/core/Configuration/AppSettings.cs @@ -0,0 +1,468 @@ +using System; +using System.Linq; +using System.Text.Json.Serialization; +using Exchanger.Hardware.PeripheryController; + +namespace Exchanger.Core.Configuration; + +/// +/// Типизированные настройки приложения. Значения могут переопределяться +/// пользователем без пересборки через user://config/appsettings.json. +/// +public sealed class AppSettings +{ + public const int CurrentConfigurationVersion = 25; + + public int ConfigurationVersion { get; set; } + + public WindowSettings Window { get; set; } = new(); + + public ThemeSettings Themes { get; set; } = new(); + + public HardwareSettings Hardware { get; set; } = new(); + + public TimeoutSettings Timeouts { get; set; } = new(); + + public PricingSettings Pricing { get; set; } = new(); + + public PaymentSettings Payments { get; set; } = new(); + + public BrandingSettings Branding { get; set; } = new(); + + public AnimatedBannerTextSettings AnimatedBannerTexts { get; set; } = new(); + + public AudioSettings Audio { get; set; } = new(); + + public AdvertisementSettings Advertisement { get; set; } = new(); + + public MenuVisibilitySettings MenuVisibility { get; set; } = new(); + + public TokenInventorySettings TokenInventory { get; set; } = new(); + + public LoggingSettings Logging { get; set; } = new(); + + public SecuritySettings Security { get; set; } = new(); + + public void Normalize() + { + if (ConfigurationVersion <= CurrentConfigurationVersion) + { + ConfigurationVersion = CurrentConfigurationVersion; + } + Window ??= new WindowSettings(); + Themes ??= new ThemeSettings(); + Hardware ??= new HardwareSettings(); + Timeouts ??= new TimeoutSettings(); + Pricing ??= new PricingSettings(); + Payments ??= new PaymentSettings(); + Branding ??= new BrandingSettings(); + AnimatedBannerTexts ??= new AnimatedBannerTextSettings(); + Audio ??= new AudioSettings(); + Advertisement ??= new AdvertisementSettings(); + MenuVisibility ??= new MenuVisibilitySettings(); + TokenInventory ??= new TokenInventorySettings(); + Logging ??= new LoggingSettings(); + Security ??= new SecuritySettings(); + + Window.DebugWindowWidth = Math.Clamp(Window.DebugWindowWidth, 640, 3840); + Window.DebugWindowHeight = Math.Clamp(Window.DebugWindowHeight, 360, 2160); + Window.TargetFps = Math.Clamp(Window.TargetFps, 30, 240); + + Themes.ExternalDlcPath = string.IsNullOrWhiteSpace(Themes.ExternalDlcPath) + || Themes.ExternalDlcPath.Trim().Length > ThemeSettingsValidator.MaximumDlcPathLength + ? "user://theme_dlc/active_theme.pck" + : Themes.ExternalDlcPath.Trim(); + + Hardware.PortName = string.IsNullOrWhiteSpace(Hardware.PortName) + ? "COM3" + : Hardware.PortName.Trim(); + Hardware.BaudRate = Math.Clamp(Hardware.BaudRate, 300, 921600); + Hardware.FrameTimeoutMilliseconds = Math.Clamp(Hardware.FrameTimeoutMilliseconds, 10, 5000); + Hardware.MaximumFrameLength = Math.Clamp(Hardware.MaximumFrameLength, 2, 65536); + Hardware.HandshakeTimeoutMilliseconds = Math.Clamp(Hardware.HandshakeTimeoutMilliseconds, 1000, 60000); + Hardware.CashlessKeepAliveSeconds = Math.Clamp(Hardware.CashlessKeepAliveSeconds, 30, 170); + Hardware.ReconnectIntervalSeconds = Math.Clamp(Hardware.ReconnectIntervalSeconds, 1, 60); + Hardware.ServiceButtonInputIndex = Math.Clamp(Hardware.ServiceButtonInputIndex, -1, 25); + Hardware.StockSensorInputIndex = Math.Clamp(Hardware.StockSensorInputIndex, -1, 25); + Hardware.Hopper2StockSensorInputIndex = Math.Clamp(Hardware.Hopper2StockSensorInputIndex, -1, 25); + Hardware.Hopper1DispenseSensorInputIndex = Math.Clamp(Hardware.Hopper1DispenseSensorInputIndex, -1, 25); + Hardware.Hopper2DispenseSensorInputIndex = Math.Clamp(Hardware.Hopper2DispenseSensorInputIndex, -1, 25); + Hardware.InputPollMilliseconds = Math.Clamp(Hardware.InputPollMilliseconds, 50, 1000); + Hardware.StockPollSeconds = Math.Clamp(Hardware.StockPollSeconds, 1, 60); + Hardware.ControllerAesMode = Hardware.ControllerAesMode?.Trim().ToUpperInvariant() ?? string.Empty; + Hardware.ControllerAesKeyEnvironmentVariable = string.IsNullOrWhiteSpace(Hardware.ControllerAesKeyEnvironmentVariable) + ? "EXCHANGER_CONTROLLER_AES_KEY" + : Hardware.ControllerAesKeyEnvironmentVariable.Trim(); + Hardware.DispenseMode = string.IsNullOrWhiteSpace(Hardware.DispenseMode) + ? "Unsupported" + : Hardware.DispenseMode.Trim(); + Hardware.MockStockLevel = Hardware.MockStockLevel?.Trim() switch + { + "Low" => "Low", + _ => "Enough", + }; + + Timeouts.SessionIdleSeconds = Math.Clamp(Timeouts.SessionIdleSeconds, 15, 600); + Timeouts.CashPaymentSeconds = Math.Clamp(Timeouts.CashPaymentSeconds, 15, 600); + Timeouts.CashlessPaymentSeconds = Math.Clamp(Timeouts.CashlessPaymentSeconds, 30, 600); + Timeouts.SuccessSeconds = Math.Clamp(Timeouts.SuccessSeconds, 3, 60); + + Pricing.TokenPriceRubles = Math.Clamp(Pricing.TokenPriceRubles, 1, 100000); + Pricing.MaxCardAmountRubles = Math.Clamp(Pricing.MaxCardAmountRubles, Pricing.TokenPriceRubles, 1000000); + Pricing.CustomAmountStepRubles = Math.Clamp(Pricing.CustomAmountStepRubles, 1, Pricing.MaxCardAmountRubles); + Pricing.PaymentPresets = (Pricing.PaymentPresets ?? Array.Empty()) + .Where(preset => preset is not null) + .Select(preset => new PaymentPreset + { + AmountRubles = Math.Clamp(preset.AmountRubles, Pricing.TokenPriceRubles, Pricing.MaxCardAmountRubles), + }) + .GroupBy(preset => preset.AmountRubles) + .Select(group => group.First()) + .OrderBy(preset => preset.AmountRubles) + .ToArray(); + Pricing.BonusRules = (Pricing.BonusRules ?? Array.Empty()) + .Where(rule => rule is not null) + .Select(rule => new BonusRule + { + MinimumAmountRubles = Math.Clamp(rule.MinimumAmountRubles, Pricing.TokenPriceRubles, Pricing.MaxCardAmountRubles), + BonusTokens = Math.Clamp(rule.BonusTokens, 0, 100000), + }) + .OrderBy(rule => rule.MinimumAmountRubles) + .ToArray(); + + Branding.ApplicationName = NormalizeText( + Branding.ApplicationName, + "РАЗМЕН ЖЕТОНОВ", + BrandingSettingsValidator.MaximumApplicationNameLength); + Branding.ShortText = NormalizeText( + Branding.ShortText, + "ПОЛУЧИ СВОИ ЖЕТОНЫ!", + BrandingSettingsValidator.MaximumShortTextLength); + Branding.SupportPhone = NormalizeText( + Branding.SupportPhone, + "Телефон поддержки уточняется", + BrandingSettingsValidator.MaximumSupportPhoneLength); + + AnimatedBannerTexts.CashPayment = NormalizeText( + AnimatedBannerTexts.CashPayment, + "АВТОМАТ НЕ ВЫДАЁТ СДАЧУ", + AnimatedBannerTextSettings.MaximumTextLength); + AnimatedBannerTexts.CardAmount = NormalizeText( + AnimatedBannerTexts.CardAmount, + "ВЫБЕРИТЕ СУММУ ДЛЯ ПЕРЕХОДА К ТЕРМИНАЛУ", + AnimatedBannerTextSettings.MaximumTextLength); + AnimatedBannerTexts.CardCustomAmount = NormalizeText( + AnimatedBannerTexts.CardCustomAmount, + "ВВЕДИТЕ СУММУ ДЛЯ ОПЛАТЫ", + AnimatedBannerTextSettings.MaximumTextLength); + AnimatedBannerTexts.CardTerminalCountdownTemplate = NormalizeText( + AnimatedBannerTexts.CardTerminalCountdownTemplate, + "ОСТАЛОСЬ {seconds} СЕК.", + AnimatedBannerTextSettings.MaximumTextLength); + + Audio.MasterVolumePercent = Math.Clamp(Audio.MasterVolumePercent, 0, 100); + Audio.AdvertisementVolumePercent = Math.Clamp(Audio.AdvertisementVolumePercent, 0, 100); + + if (string.Equals( + Advertisement.FallbackText?.Trim(), + "РЕКЛАМНЫЙ БЛОК", + StringComparison.OrdinalIgnoreCase)) + { + Advertisement.FallbackText = "ПРОМО-БЛОК"; + } + + Advertisement.FallbackText = NormalizeText( + Advertisement.FallbackText, + "ПРОМО-БЛОК", + AdvertisementSettingsValidator.MaximumFallbackTextLength); + Advertisement.PosterPath = NormalizeAssetPath(Advertisement.PosterPath); + Advertisement.VideoPaths = (Advertisement.VideoPaths ?? Array.Empty()) + .Where(path => !string.IsNullOrWhiteSpace(path)) + .Select(AdvertisementVideoLibrary.NormalizeSelectedVideo) + .Where(path => path.Length <= AdvertisementSettingsValidator.MaximumAssetPathLength) + .GroupBy(AdvertisementVideoLibrary.GetComparisonKey, StringComparer.Ordinal) + .Select(group => group.First()) + .Take(AdvertisementSettingsValidator.MaximumVideoPaths) + .ToArray(); + + Logging.MinimumLevel = LoggingSettingsValidator.NormalizeLevel(Logging.MinimumLevel); + Logging.MaxFileSizeMb = Math.Clamp(Logging.MaxFileSizeMb, 1, 100); + Logging.RetentionDays = Math.Clamp(Logging.RetentionDays, 1, 365); + + Security.ServicePinSaltBase64 = Security.ServicePinSaltBase64?.Trim() ?? string.Empty; + Security.ServicePinHashBase64 = Security.ServicePinHashBase64?.Trim() ?? string.Empty; + if (Security.ServicePinIterations is < ServiceAccessPolicy.MinimumPbkdf2Iterations + or > ServiceAccessPolicy.MaximumPbkdf2Iterations) + { + Security.ServicePinSaltBase64 = string.Empty; + Security.ServicePinHashBase64 = string.Empty; + Security.ServicePinIterations = ServiceAccessPolicy.DefaultPbkdf2Iterations; + } + } + + private static string NormalizeText(string? value, string fallback, int maximumLength = int.MaxValue) + { + if (string.IsNullOrWhiteSpace(value)) + { + return fallback; + } + + string normalized = string.Join( + " ", + value.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries)); + return normalized.Length <= maximumLength + ? normalized + : normalized[..maximumLength].TrimEnd(); + } + + private static string NormalizeAssetPath(string? value) + { + string path = value?.Trim() ?? string.Empty; + return path.Length <= AdvertisementSettingsValidator.MaximumAssetPathLength + ? AdvertisementVideoLibrary.NormalizeSelectedVideo(path) + : string.Empty; + } +} + +public sealed class WindowSettings +{ + public bool Fullscreen { get; set; } = true; + + public bool Borderless { get; set; } = true; + + public bool DebugWindowInDebugBuild { get; set; } = true; + + public int DebugWindowWidth { get; set; } = 1280; + + public int DebugWindowHeight { get; set; } = 720; + + public int TargetFps { get; set; } = 60; +} + +public sealed class ThemeSettings +{ + public bool ReducedEffects { get; set; } + + public bool ExternalDlcEnabled { get; set; } = true; + + /// + /// Путь из пользовательского appsettings.json: user:// либо абсолютный + /// путь к Godot resource pack с расширением .pck. + /// + public string ExternalDlcPath { get; set; } = "user://theme_dlc/active_theme.pck"; +} + +public sealed class HardwareSettings +{ + public bool UseMock { get; set; } = true; + + public string PortName { get; set; } = "COM3"; + + public int BaudRate { get; set; } = 115200; + + public int FrameTimeoutMilliseconds { get; set; } = 100; + + public int MaximumFrameLength { get; set; } = 1024; + + public int HandshakeTimeoutMilliseconds { get; set; } = 2000; + + public int CashlessKeepAliveSeconds { get; set; } = 120; + + public int ReconnectIntervalSeconds { get; set; } = 30; + + /// IN8 по актуальной разводке; -1 отключает физический сервисный вход. + public int ServiceButtonInputIndex { get; set; } = PeripheryControllerInputs.ServiceButton; + + /// Кнопочные входы платы имеют pull-up: нажатие переводит IN8 в ноль. + public bool ServiceButtonActiveHigh { get; set; } + + /// Номер бита INPUT, 0..25; -1 — вход ещё не назначен. + public int StockSensorInputIndex { get; set; } = PeripheryControllerInputs.Hopper1StockLow; + + public bool StockLowWhenInputHigh { get; set; } + + /// IN4 — датчик малого остатка второго хоппера; активный низкий уровень означает «мало». + public int Hopper2StockSensorInputIndex { get; set; } = PeripheryControllerInputs.Hopper2StockLow; + + public bool Hopper2StockLowWhenInputHigh { get; set; } + + /// IN24 — датчик выдачи первого хоппера; -1 отключает его программный подсчёт. + public int Hopper1DispenseSensorInputIndex { get; set; } = PeripheryControllerInputs.Hopper1DispensePulse; + + /// Датчик выдачи имеет pull-up: низкий уровень означает импульс жетона. + public bool Hopper1DispenseSensorActiveHigh { get; set; } + + /// IN25 — физический датчик выдачи второго хоппера; -1 отключает его использование. + public int Hopper2DispenseSensorInputIndex { get; set; } = PeripheryControllerInputs.Hopper2DispensePulse; + + /// Датчик выдачи имеет pull-up: низкий уровень означает импульс жетона. + public bool Hopper2DispenseSensorActiveHigh { get; set; } + + /// Частота резервного опроса INPUT для кнопки и импульсного датчика. + public int InputPollMilliseconds { get; set; } = 100; + + /// Интервал старого медленного опроса, если быстрые входы явно отключены. + public int StockPollSeconds { get; set; } = 5; + + public string ControllerAesMode { get; set; } = "ECB"; + + public string ControllerAesKeyEnvironmentVariable { get; set; } = "EXCHANGER_CONTROLLER_AES_KEY"; + + public string DispenseMode { get; set; } = "Unsupported"; + + public string MockStockLevel { get; set; } = "Enough"; +} + +public sealed class TimeoutSettings +{ + public int SessionIdleSeconds { get; set; } = 45; + + public int CashPaymentSeconds { get; set; } = 45; + + public int CashlessPaymentSeconds { get; set; } = 120; + + /// Поле конфигурации до v20; используется только при миграции. + [JsonPropertyName("PaymentSeconds")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] + public int LegacyPaymentSeconds { get; set; } + + public int SuccessSeconds { get; set; } = 10; +} + +public sealed class PricingSettings +{ + public int TokenPriceRubles { get; set; } = 10; + + public int MaxCardAmountRubles { get; set; } = 5000; + + public int CustomAmountStepRubles { get; set; } = 10; + + public PaymentPreset[] PaymentPresets { get; set; } = + new PaymentPreset[] + { + new() { AmountRubles = 10 }, + new() { AmountRubles = 50 }, + new() { AmountRubles = 100 }, + new() { AmountRubles = 150 }, + new() { AmountRubles = 200 }, + new() { AmountRubles = 300 }, + new() { AmountRubles = 400 }, + new() { AmountRubles = 500 }, + }; + + public BonusRule[] BonusRules { get; set; } = Array.Empty(); +} + +public sealed class PaymentSettings +{ + public bool CashEnabled { get; set; } = true; + + public bool CardEnabled { get; set; } = true; +} + +public sealed class PaymentPreset +{ + public int AmountRubles { get; set; } +} + +public sealed class BonusRule +{ + public int MinimumAmountRubles { get; set; } + + public int BonusTokens { get; set; } +} + +public sealed class BrandingSettings +{ + public string ApplicationName { get; set; } = "РАЗМЕН ЖЕТОНОВ"; + + public string ShortText { get; set; } = "ПОЛУЧИ СВОИ ЖЕТОНЫ!"; + + public string SupportPhone { get; set; } = "Телефон поддержки уточняется"; +} + +/// Тексты, накладываемые на нижние анимированные баннеры. +public sealed class AnimatedBannerTextSettings +{ + public const int MaximumTextLength = 120; + + public string CashPayment { get; set; } = "АВТОМАТ НЕ ВЫДАЁТ СДАЧУ"; + + public string CardAmount { get; set; } = "ВЫБЕРИТЕ СУММУ ДЛЯ ПЕРЕХОДА К ТЕРМИНАЛУ"; + + public string CardCustomAmount { get; set; } = "ВВЕДИТЕ СУММУ ДЛЯ ОПЛАТЫ"; + + /// Шаблон ожидания терминала; {seconds} заменяется числом секунд. + public string CardTerminalCountdownTemplate { get; set; } = "ОСТАЛОСЬ {seconds} СЕК."; +} + +public sealed class AudioSettings +{ + public int MasterVolumePercent { get; set; } = 100; + + public bool Muted { get; set; } + + public int AdvertisementVolumePercent { get; set; } = 100; +} + +public sealed class AdvertisementSettings +{ + public bool Enabled { get; set; } = true; + + public string[] VideoPaths { get; set; } = Array.Empty(); + + public string PosterPath { get; set; } = string.Empty; + + public bool Muted { get; set; } = true; + + public string FallbackText { get; set; } = "ПРОМО-БЛОК"; +} + +public sealed class MenuVisibilitySettings +{ + public bool ShowStockStatus { get; set; } = true; + + // Имя JSON намеренно сохранено, чтобы существующие пользовательские настройки + // продолжили управлять расширенным блоком без сброса значения при обновлении. + [JsonPropertyName("ShowRightCharacter")] + public bool ShowCustomText { get; set; } = true; + + public bool ShowPromotionBlock { get; set; } = true; + + /// Включает интерактивного питомца, объявленного активной темой. + public bool ShowInteractivePet { get; set; } = true; +} + +public sealed class TokenInventorySettings +{ + /// + /// Включает точный программный учёт и сервисные действия пересчёта/пополнения. + /// + public bool Enabled { get; set; } = true; + + /// Не позволяет купить больше жетонов, чем находится на учтённом остатке. + public bool PurchaseLimitEnabled { get; set; } = true; +} + +public sealed class LoggingSettings +{ + public string MinimumLevel { get; set; } = "Info"; + + public int MaxFileSizeMb { get; set; } = 5; + + public int RetentionDays { get; set; } = 14; +} + +public sealed class SecuritySettings +{ + /// Если включено, SERVICE и debug-действие требуют сервисный PIN. + public bool ServicePinEnabled { get; set; } + + /// Случайная соль PBKDF2 в Base64. Сам PIN в конфигурации не хранится. + public string ServicePinSaltBase64 { get; set; } = string.Empty; + + /// Результат PBKDF2-SHA256 в Base64. + public string ServicePinHashBase64 { get; set; } = string.Empty; + + public int ServicePinIterations { get; set; } = ServiceAccessPolicy.DefaultPbkdf2Iterations; +} diff --git a/src/core/Configuration/AppSettings.cs.uid b/src/core/Configuration/AppSettings.cs.uid new file mode 100644 index 0000000..e046e0e --- /dev/null +++ b/src/core/Configuration/AppSettings.cs.uid @@ -0,0 +1 @@ +uid://dycixxro1pv8h diff --git a/src/core/Configuration/AppSettingsLoader.cs b/src/core/Configuration/AppSettingsLoader.cs new file mode 100644 index 0000000..f35fe0b --- /dev/null +++ b/src/core/Configuration/AppSettingsLoader.cs @@ -0,0 +1,112 @@ +using Godot; +using System; +using System.IO; +using System.Text; +using Exchanger.Core.TechnicalConfiguration; + +namespace Exchanger.Core.Configuration; + +/// +/// Загружает встроенную конфигурацию, создаёт пользовательскую копию и +/// применяет безопасные аргументы командной строки. +/// +public static class AppSettingsLoader +{ + private const string DefaultSettingsPath = "res://config/default_settings.json"; + private const string UserSettingsPath = "user://config/appsettings.json"; + private const string DefaultTechnicalSettingsPath = "res://config/technical_settings.toml"; + private const string UserTechnicalSettingsPath = "user://config/technical_settings.toml"; + private const string MaterializedDefaultSettingsPath = "user://config/.embedded/default_settings.json"; + private const string MaterializedDefaultTechnicalSettingsPath = "user://config/.embedded/technical_settings.toml"; + + public static AppSettings Load() + { + return Load(CreateService()); + } + + public static SettingsService CreateService() + { + return new SettingsService( + MaterializeEmbeddedResource(DefaultSettingsPath, MaterializedDefaultSettingsPath), + ProjectSettings.GlobalizePath(UserSettingsPath), + message => GD.PushWarning(message)); + } + + public static AppSettings Load(SettingsService service) + { + ArgumentNullException.ThrowIfNull(service); + + AppSettings settings = service.Load(); + TechnicalSettings technicalSettings = CreateTechnicalSettingsService().Load(); + technicalSettings.ApplyTo(settings.Hardware); + technicalSettings.ApplyTo(settings.Themes); + ApplyCommandLineOverrides(settings, OS.GetCmdlineUserArgs()); + settings.Normalize(); + return settings; + } + + public static TechnicalSettingsService CreateTechnicalSettingsService() + { + return new TechnicalSettingsService( + MaterializeEmbeddedResource( + DefaultTechnicalSettingsPath, + MaterializedDefaultTechnicalSettingsPath), + ProjectSettings.GlobalizePath(UserTechnicalSettingsPath), + message => GD.PushWarning(message)); + } + + private static string MaterializeEmbeddedResource(string resourcePath, string userCachePath) + { + using Godot.FileAccess? source = Godot.FileAccess.Open( + resourcePath, + Godot.FileAccess.ModeFlags.Read); + if (source is null) + { + throw new InvalidDataException( + $"Встроенный ресурс конфигурации недоступен: {resourcePath}."); + } + + string targetPath = ProjectSettings.GlobalizePath(userCachePath); + string? targetDirectory = Path.GetDirectoryName(targetPath); + if (!string.IsNullOrWhiteSpace(targetDirectory)) + { + Directory.CreateDirectory(targetDirectory); + } + + File.WriteAllText(targetPath, source.GetAsText(), new UTF8Encoding(false)); + return targetPath; + } + + private static void ApplyCommandLineOverrides(AppSettings settings, string[] arguments) + { + foreach (string argument in arguments) + { + if (argument.Equals("--windowed", StringComparison.OrdinalIgnoreCase)) + { + settings.Window.Fullscreen = false; + } + else if (argument.Equals("--fullscreen", StringComparison.OrdinalIgnoreCase)) + { + settings.Window.Fullscreen = true; + } + else if (argument.Equals("--reduced-effects", StringComparison.OrdinalIgnoreCase)) + { + settings.Themes.ReducedEffects = true; + } + else if (argument.StartsWith("--theme-dlc=", StringComparison.OrdinalIgnoreCase)) + { + settings.Themes.ExternalDlcEnabled = true; + settings.Themes.ExternalDlcPath = argument[12..]; + } + else if (argument.Equals("--no-theme-dlc", StringComparison.OrdinalIgnoreCase)) + { + settings.Themes.ExternalDlcEnabled = false; + } + else if (argument.StartsWith("--mock-hardware=", StringComparison.OrdinalIgnoreCase) + && bool.TryParse(argument[16..], out bool useMock)) + { + settings.Hardware.UseMock = useMock; + } + } + } +} diff --git a/src/core/Configuration/AppSettingsLoader.cs.uid b/src/core/Configuration/AppSettingsLoader.cs.uid new file mode 100644 index 0000000..571c727 --- /dev/null +++ b/src/core/Configuration/AppSettingsLoader.cs.uid @@ -0,0 +1 @@ +uid://col6rrybd4w8g diff --git a/src/core/Configuration/BrandingSettingsValidator.cs b/src/core/Configuration/BrandingSettingsValidator.cs new file mode 100644 index 0000000..62c4c0a --- /dev/null +++ b/src/core/Configuration/BrandingSettingsValidator.cs @@ -0,0 +1,88 @@ +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Exchanger.Core.Configuration; + +public enum BrandingValidationField +{ + ApplicationName, + ShortText, + SupportPhone, +} + +public readonly record struct BrandingValidationIssue(BrandingValidationField Field, string Message); + +public sealed class BrandingValidationResult +{ + public BrandingValidationResult(IReadOnlyList issues) + { + Issues = issues ?? throw new ArgumentNullException(nameof(issues)); + } + + public IReadOnlyList Issues { get; } + + public bool IsValid => Issues.Count == 0; +} + +/// Проверяет короткие однострочные тексты, видимые пользователю на домашнем экране. +public static class BrandingSettingsValidator +{ + public const int MaximumApplicationNameLength = 48; + public const int MaximumShortTextLength = 48; + public const int MaximumSupportPhoneLength = 80; + + public static BrandingValidationResult Validate(BrandingSettings settings) + { + ArgumentNullException.ThrowIfNull(settings); + + var issues = new List(); + ValidateText( + settings.ApplicationName, + MaximumApplicationNameLength, + BrandingValidationField.ApplicationName, + "Название автомата", + issues); + ValidateText( + settings.ShortText, + MaximumShortTextLength, + BrandingValidationField.ShortText, + "Свой текст", + issues); + ValidateText( + settings.SupportPhone, + MaximumSupportPhoneLength, + BrandingValidationField.SupportPhone, + "Телефон поддержки", + issues); + + return new BrandingValidationResult(issues); + } + + private static void ValidateText( + string? value, + int maximumLength, + BrandingValidationField field, + string caption, + ICollection issues) + { + string trimmed = value?.Trim() ?? string.Empty; + if (trimmed.Length == 0) + { + issues.Add(new BrandingValidationIssue(field, $"Заполните поле «{caption}».")); + return; + } + + if (trimmed.Length > maximumLength) + { + issues.Add(new BrandingValidationIssue( + field, + $"{caption} — не больше {maximumLength} знаков.")); + } + + if (trimmed.Any(char.IsControl)) + { + issues.Add(new BrandingValidationIssue(field, $"Введите поле «{caption}» в одну строку.")); + } + } +} diff --git a/src/core/Configuration/BrandingSettingsValidator.cs.uid b/src/core/Configuration/BrandingSettingsValidator.cs.uid new file mode 100644 index 0000000..d125f83 --- /dev/null +++ b/src/core/Configuration/BrandingSettingsValidator.cs.uid @@ -0,0 +1 @@ +uid://xrxcday0o7qh diff --git a/src/core/Configuration/HardwareSettingsValidator.cs b/src/core/Configuration/HardwareSettingsValidator.cs new file mode 100644 index 0000000..312545d --- /dev/null +++ b/src/core/Configuration/HardwareSettingsValidator.cs @@ -0,0 +1,63 @@ +using System; +using System.Collections.Generic; + +namespace Exchanger.Core.Configuration; + +public enum HardwareValidationField +{ + PortName, + BaudRate, + ReconnectIntervalSeconds, +} + +public readonly record struct HardwareValidationIssue(HardwareValidationField Field, string Message); + +public sealed class HardwareValidationResult +{ + public HardwareValidationResult(IReadOnlyList issues) => Issues = issues; + + public IReadOnlyList Issues { get; } + + public bool IsValid => Issues.Count == 0; +} + +/// Проверяет только разрешённую UI-поверхность соединения, не затрагивая AES и wire-параметры. +public static class HardwareSettingsValidator +{ + public static readonly int[] AllowedBaudRates = [9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600]; + + public static HardwareValidationResult Validate(HardwareSettings settings) => + Validate(settings, SerialPortNameValidator.CurrentPlatform); + + public static HardwareValidationResult Validate( + HardwareSettings settings, + SerialPortPlatform serialPortPlatform) + { + ArgumentNullException.ThrowIfNull(settings); + var issues = new List(); + + string portName = settings.PortName?.Trim() ?? string.Empty; + if (!settings.UseMock && !SerialPortNameValidator.IsValid(portName, serialPortPlatform)) + { + issues.Add(new HardwareValidationIssue( + HardwareValidationField.PortName, + SerialPortNameValidator.GetExpectedFormatMessage(serialPortPlatform))); + } + + if (Array.IndexOf(AllowedBaudRates, settings.BaudRate) < 0) + { + issues.Add(new HardwareValidationIssue( + HardwareValidationField.BaudRate, + "Выберите поддерживаемую скорость соединения.")); + } + + if (settings.ReconnectIntervalSeconds is < 1 or > 60) + { + issues.Add(new HardwareValidationIssue( + HardwareValidationField.ReconnectIntervalSeconds, + "Повторное подключение должно выполняться через 1–60 секунд.")); + } + + return new HardwareValidationResult(issues); + } +} diff --git a/src/core/Configuration/HardwareSettingsValidator.cs.uid b/src/core/Configuration/HardwareSettingsValidator.cs.uid new file mode 100644 index 0000000..532005d --- /dev/null +++ b/src/core/Configuration/HardwareSettingsValidator.cs.uid @@ -0,0 +1 @@ +uid://br1coxeqks48h diff --git a/src/core/Configuration/LoggingSettingsValidator.cs b/src/core/Configuration/LoggingSettingsValidator.cs new file mode 100644 index 0000000..60e9dc6 --- /dev/null +++ b/src/core/Configuration/LoggingSettingsValidator.cs @@ -0,0 +1,78 @@ +using System; +using System.Collections.Generic; + +namespace Exchanger.Core.Configuration; + +public enum LoggingValidationField +{ + MinimumLevel, + MaxFileSizeMb, + RetentionDays, +} + +public readonly record struct LoggingValidationIssue(LoggingValidationField Field, string Message); + +public sealed class LoggingValidationResult +{ + public LoggingValidationResult(IReadOnlyList issues) => Issues = issues; + + public IReadOnlyList Issues { get; } + + public bool IsValid => Issues.Count == 0; +} + +/// Безопасные операторские границы файлового журнала. +public static class LoggingSettingsValidator +{ + public static readonly string[] AllowedLevels = ["Info", "Warning", "Error"]; + + public const int MinimumFileSizeMb = 1; + public const int MaximumFileSizeMb = 100; + public const int MinimumRetentionDays = 1; + public const int MaximumRetentionDays = 365; + + public static LoggingValidationResult Validate(LoggingSettings settings) + { + ArgumentNullException.ThrowIfNull(settings); + var issues = new List(); + + if (Array.FindIndex( + AllowedLevels, + level => level.Equals(settings.MinimumLevel?.Trim(), StringComparison.OrdinalIgnoreCase)) < 0) + { + issues.Add(new LoggingValidationIssue( + LoggingValidationField.MinimumLevel, + "Выберите уровень Info, Warning или Error.")); + } + + if (settings.MaxFileSizeMb is < MinimumFileSizeMb or > MaximumFileSizeMb) + { + issues.Add(new LoggingValidationIssue( + LoggingValidationField.MaxFileSizeMb, + $"Размер файла должен быть от {MinimumFileSizeMb} до {MaximumFileSizeMb} МБ.")); + } + + if (settings.RetentionDays is < MinimumRetentionDays or > MaximumRetentionDays) + { + issues.Add(new LoggingValidationIssue( + LoggingValidationField.RetentionDays, + $"Срок хранения должен быть от {MinimumRetentionDays} до {MaximumRetentionDays} дней.")); + } + + return new LoggingValidationResult(issues); + } + + public static string NormalizeLevel(string? value) + { + string candidate = value?.Trim() ?? string.Empty; + foreach (string level in AllowedLevels) + { + if (level.Equals(candidate, StringComparison.OrdinalIgnoreCase)) + { + return level; + } + } + + return "Info"; + } +} diff --git a/src/core/Configuration/LoggingSettingsValidator.cs.uid b/src/core/Configuration/LoggingSettingsValidator.cs.uid new file mode 100644 index 0000000..17dd4c7 --- /dev/null +++ b/src/core/Configuration/LoggingSettingsValidator.cs.uid @@ -0,0 +1 @@ +uid://tnvc52e3b506 diff --git a/src/core/Configuration/PaymentSettingsValidator.cs b/src/core/Configuration/PaymentSettingsValidator.cs new file mode 100644 index 0000000..03e3148 --- /dev/null +++ b/src/core/Configuration/PaymentSettingsValidator.cs @@ -0,0 +1,91 @@ +using System; +using System.Collections.Generic; + +namespace Exchanger.Core.Configuration; + +public enum PaymentValidationField +{ + PaymentMethods, + SessionIdleTimeout, + CashPaymentTimeout, + CashlessPaymentTimeout, + SuccessTimeout, +} + +public readonly record struct PaymentValidationIssue(PaymentValidationField Field, string Message); + +public sealed class PaymentValidationResult +{ + public PaymentValidationResult(IReadOnlyList issues) + { + Issues = issues ?? throw new ArgumentNullException(nameof(issues)); + } + + public IReadOnlyList Issues { get; } + + public bool IsValid => Issues.Count == 0; +} + +/// Проверяет операторские настройки способов оплаты и таймаутов до записи. +public static class PaymentSettingsValidator +{ + public static PaymentValidationResult Validate(AppSettings settings) + { + ArgumentNullException.ThrowIfNull(settings); + + var issues = new List(); + if (!settings.Payments.CashEnabled && !settings.Payments.CardEnabled) + { + issues.Add(new PaymentValidationIssue( + PaymentValidationField.PaymentMethods, + "Оставьте хотя бы один способ оплаты.")); + } + + ValidateRange( + settings.Timeouts.SessionIdleSeconds, + 15, + 600, + PaymentValidationField.SessionIdleTimeout, + "Время до возврата назад", + issues); + ValidateRange( + settings.Timeouts.CashPaymentSeconds, + 15, + 600, + PaymentValidationField.CashPaymentTimeout, + "Время оплаты наличными", + issues); + ValidateRange( + settings.Timeouts.CashlessPaymentSeconds, + 30, + 600, + PaymentValidationField.CashlessPaymentTimeout, + "Время безналичной оплаты", + issues); + ValidateRange( + settings.Timeouts.SuccessSeconds, + 3, + 60, + PaymentValidationField.SuccessTimeout, + "Время показа результата", + issues); + + return new PaymentValidationResult(issues); + } + + private static void ValidateRange( + int value, + int minimum, + int maximum, + PaymentValidationField field, + string caption, + ICollection issues) + { + if (value < minimum || value > maximum) + { + issues.Add(new PaymentValidationIssue( + field, + $"{caption} — от {minimum} до {maximum} секунд.")); + } + } +} diff --git a/src/core/Configuration/PaymentSettingsValidator.cs.uid b/src/core/Configuration/PaymentSettingsValidator.cs.uid new file mode 100644 index 0000000..de04f8c --- /dev/null +++ b/src/core/Configuration/PaymentSettingsValidator.cs.uid @@ -0,0 +1 @@ +uid://hua7qg8dhc14 diff --git a/src/core/Configuration/PricingSettingsValidator.cs b/src/core/Configuration/PricingSettingsValidator.cs new file mode 100644 index 0000000..d4f83ef --- /dev/null +++ b/src/core/Configuration/PricingSettingsValidator.cs @@ -0,0 +1,175 @@ +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Exchanger.Core.Configuration; + +public enum PricingValidationField +{ + TokenPrice, + MaximumCardAmount, + CustomAmountStep, + BonusRule, + PaymentPreset, +} + +public readonly record struct PricingValidationIssue( + PricingValidationField Field, + string Message, + int? RuleIndex = null, + int? PresetIndex = null); + +public sealed class PricingValidationResult +{ + public PricingValidationResult(IReadOnlyList issues) + { + Issues = issues ?? throw new ArgumentNullException(nameof(issues)); + } + + public IReadOnlyList Issues { get; } + + public bool IsValid => Issues.Count == 0; +} + +/// +/// Строгая проверка редактируемых тарифов до нормализации и записи. +/// В отличие от AppSettings.Normalize не исправляет пользовательский ввод молча. +/// +public static class PricingSettingsValidator +{ + public const int MinimumTokenPriceRubles = 1; + public const int MaximumTokenPriceRubles = 100000; + public const int MaximumBonusTokens = 100000; + public const int MaximumCardAmountRubles = 1000000; + + public static PricingValidationResult Validate(PricingSettings pricing) + { + ArgumentNullException.ThrowIfNull(pricing); + + var issues = new List(); + if (pricing.TokenPriceRubles < MinimumTokenPriceRubles + || pricing.TokenPriceRubles > MaximumTokenPriceRubles) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.TokenPrice, + $"Укажите цену от {MinimumTokenPriceRubles} до {MaximumTokenPriceRubles} ₽.")); + } + + if (pricing.TokenPriceRubles > pricing.MaxCardAmountRubles) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.TokenPrice, + $"Цена жетона должна быть не больше {pricing.MaxCardAmountRubles} ₽.")); + } + + if (pricing.MaxCardAmountRubles < pricing.TokenPriceRubles + || pricing.MaxCardAmountRubles > MaximumCardAmountRubles) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.MaximumCardAmount, + $"Укажите максимальную сумму от {Math.Max(1, pricing.TokenPriceRubles)} до {MaximumCardAmountRubles} ₽.")); + } + + if (pricing.CustomAmountStepRubles < 1 + || pricing.CustomAmountStepRubles > pricing.MaxCardAmountRubles) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.CustomAmountStep, + $"Укажите шаг от 1 до {Math.Max(1, pricing.MaxCardAmountRubles)} ₽.")); + } + + PaymentPreset[] presets = pricing.PaymentPresets ?? Array.Empty(); + var duplicatePresetAmounts = presets + .Where(preset => preset is not null) + .GroupBy(preset => preset.AmountRubles) + .Where(group => group.Count() > 1) + .Select(group => group.Key) + .ToHashSet(); + + for (int index = 0; index < presets.Length; index++) + { + PaymentPreset? preset = presets[index]; + if (preset is null) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.PaymentPreset, + "Укажите сумму.", + PresetIndex: index)); + continue; + } + + if (preset.AmountRubles < pricing.TokenPriceRubles + || preset.AmountRubles > pricing.MaxCardAmountRubles) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.PaymentPreset, + $"Укажите сумму от {pricing.TokenPriceRubles} до {pricing.MaxCardAmountRubles} ₽.", + PresetIndex: index)); + } + else if (pricing.CustomAmountStepRubles > 0 + && preset.AmountRubles % pricing.CustomAmountStepRubles != 0) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.PaymentPreset, + $"Сумма должна делиться на {pricing.CustomAmountStepRubles} ₽ без остатка.", + PresetIndex: index)); + } + + if (duplicatePresetAmounts.Contains(preset.AmountRubles)) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.PaymentPreset, + $"Сумма {preset.AmountRubles} ₽ уже добавлена.", + PresetIndex: index)); + } + } + + BonusRule[] rules = pricing.BonusRules ?? Array.Empty(); + var duplicateThresholds = rules + .Where(rule => rule is not null) + .GroupBy(rule => rule.MinimumAmountRubles) + .Where(group => group.Count() > 1) + .Select(group => group.Key) + .ToHashSet(); + + for (int index = 0; index < rules.Length; index++) + { + BonusRule? rule = rules[index]; + if (rule is null) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.BonusRule, + "Заполните условия бонуса.", + index)); + continue; + } + + if (rule.MinimumAmountRubles < pricing.TokenPriceRubles + || rule.MinimumAmountRubles > pricing.MaxCardAmountRubles) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.BonusRule, + $"Укажите сумму от {pricing.TokenPriceRubles} до {pricing.MaxCardAmountRubles} ₽.", + index)); + } + + if (rule.BonusTokens < 0 || rule.BonusTokens > MaximumBonusTokens) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.BonusRule, + $"Укажите от 0 до {MaximumBonusTokens} подарочных жетонов.", + index)); + } + + if (duplicateThresholds.Contains(rule.MinimumAmountRubles)) + { + issues.Add(new PricingValidationIssue( + PricingValidationField.BonusRule, + $"Бонус для суммы {rule.MinimumAmountRubles} ₽ уже добавлен.", + index)); + } + } + + return new PricingValidationResult(issues); + } +} diff --git a/src/core/Configuration/PricingSettingsValidator.cs.uid b/src/core/Configuration/PricingSettingsValidator.cs.uid new file mode 100644 index 0000000..93f49e5 --- /dev/null +++ b/src/core/Configuration/PricingSettingsValidator.cs.uid @@ -0,0 +1 @@ +uid://teel0lr0kc5r diff --git a/src/core/Configuration/SerialPortCandidateResolver.cs b/src/core/Configuration/SerialPortCandidateResolver.cs new file mode 100644 index 0000000..d21894b --- /dev/null +++ b/src/core/Configuration/SerialPortCandidateResolver.cs @@ -0,0 +1,103 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.RegularExpressions; + +namespace Exchanger.Core.Configuration; + +/// +/// Превращает технический префикс автоматического поиска в упорядоченный список +/// уже обнаруженных последовательных устройств. Сам порт не открывает. +/// +public static partial class SerialPortCandidateResolver +{ + /// + /// Windows: COM. Linux: ttyUSB или /dev/ttyUSB. + /// Полные имена остаются точной настройкой одного устройства. + /// + public static bool IsAutomaticSearchPrefix(string? configuredPort, SerialPortPlatform platform) + { + string normalized = configuredPort?.Trim() ?? string.Empty; + return platform switch + { + SerialPortPlatform.Windows => normalized.Equals("COM", StringComparison.OrdinalIgnoreCase), + SerialPortPlatform.Linux => normalized.Equals("ttyUSB", StringComparison.OrdinalIgnoreCase) + || normalized.Equals("/dev/ttyUSB", StringComparison.OrdinalIgnoreCase), + _ => false, + }; + } + + /// + /// Канонизирует короткую Linux-запись ttyUSBN в путь устройства + /// /dev/ttyUSBN, который ожидает System.IO.Ports. + /// + public static string NormalizePortName(string? configuredPort, SerialPortPlatform platform) + { + string normalized = configuredPort?.Trim() ?? string.Empty; + if (platform == SerialPortPlatform.Linux + && LinuxTtyUsbCandidateRegex().Match(normalized) is { Success: true } match + && long.TryParse(match.Groups["index"].Value, out long index)) + { + return $"/dev/ttyUSB{index}"; + } + + return normalized; + } + /// + /// Для обычной настройки возвращает один заданный порт. Для префикса поиска + /// отбирает только подходящий тип устройств и сортирует их по номеру с нуля. + /// + public static IReadOnlyList ResolveCandidates( + string? configuredPort, + SerialPortPlatform platform, + IEnumerable? availablePortNames) + { + string normalized = configuredPort?.Trim() ?? string.Empty; + if (!IsAutomaticSearchPrefix(normalized, platform)) + { + return normalized.Length == 0 ? Array.Empty() : new[] { NormalizePortName(normalized, platform) }; + } + + return platform switch + { + SerialPortPlatform.Windows => ResolveWindowsCandidates(availablePortNames), + SerialPortPlatform.Linux => ResolveLinuxTtyUsbCandidates(availablePortNames), + _ => Array.Empty(), + }; + } + + private static IReadOnlyList ResolveWindowsCandidates(IEnumerable? availablePortNames) => + Resolve(availablePortNames, WindowsCandidateRegex(), candidate => $"COM{candidate.Index}"); + + private static IReadOnlyList ResolveLinuxTtyUsbCandidates(IEnumerable? availablePortNames) => + Resolve(availablePortNames, LinuxTtyUsbCandidateRegex(), candidate => $"/dev/ttyUSB{candidate.Index}"); + + private static IReadOnlyList Resolve( + IEnumerable? availablePortNames, + Regex pattern, + Func format) + { + if (availablePortNames is null) + { + return Array.Empty(); + } + + return availablePortNames + .Where(name => !string.IsNullOrWhiteSpace(name)) + .Select(name => pattern.Match(name.Trim())) + .Where(match => match.Success && long.TryParse(match.Groups["index"].Value, out _)) + .Select(match => new PortCandidate(long.Parse(match.Groups["index"].Value))) + .Distinct() + .OrderBy(candidate => candidate.Index) + .Select(format) + .ToArray(); + } + + [GeneratedRegex("^COM(?[0-9]+)$", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] + private static partial Regex WindowsCandidateRegex(); + + [GeneratedRegex("^(?:/dev/)?ttyUSB(?[0-9]+)$", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] + private static partial Regex LinuxTtyUsbCandidateRegex(); + + private readonly record struct PortCandidate(long Index); +} diff --git a/src/core/Configuration/SerialPortCandidateResolver.cs.uid b/src/core/Configuration/SerialPortCandidateResolver.cs.uid new file mode 100644 index 0000000..ee0f112 --- /dev/null +++ b/src/core/Configuration/SerialPortCandidateResolver.cs.uid @@ -0,0 +1 @@ +uid://thejn2o6yp1f diff --git a/src/core/Configuration/SerialPortNameValidator.cs b/src/core/Configuration/SerialPortNameValidator.cs new file mode 100644 index 0000000..937c97d --- /dev/null +++ b/src/core/Configuration/SerialPortNameValidator.cs @@ -0,0 +1,82 @@ +using System; +using System.Linq; +using System.Text.RegularExpressions; + +namespace Exchanger.Core.Configuration; + +public enum SerialPortPlatform +{ + Unsupported, + Windows, + Linux, +} + +/// Проверяет имя последовательного порта по правилам текущей desktop-платформы. +public static partial class SerialPortNameValidator +{ + private const string LinuxByIdPrefix = "/dev/serial/by-id/"; + private const int MaximumLinuxByIdNameLength = 255; + + public static SerialPortPlatform CurrentPlatform => + OperatingSystem.IsWindows() + ? SerialPortPlatform.Windows + : OperatingSystem.IsLinux() + ? SerialPortPlatform.Linux + : SerialPortPlatform.Unsupported; + + public static bool IsValid(string? portName) => IsValid(portName, CurrentPlatform); + + public static bool IsValid(string? portName, SerialPortPlatform platform) + { + string normalized = portName?.Trim() ?? string.Empty; + return platform switch + { + SerialPortPlatform.Windows => normalized.Equals("COM", StringComparison.OrdinalIgnoreCase) + || WindowsComPortRegex().IsMatch(normalized), + SerialPortPlatform.Linux => IsValidLinuxPort(normalized), + _ => false, + }; + } + + public static string GetExpectedFormatMessage(SerialPortPlatform platform) => + platform switch + { + SerialPortPlatform.Windows => "Укажите COM1…COM256 либо COM для автоматического поиска.", + SerialPortPlatform.Linux => + "Укажите последовательный порт в формате /dev/ttyUSB*, /dev/ttyACM* " + + "или /dev/serial/by-id/*.", + _ => "Последовательные порты поддерживаются только в Windows и Linux.", + }; + + private static bool IsValidLinuxPort(string portName) + { + if (portName.Equals("ttyUSB", StringComparison.OrdinalIgnoreCase) + || portName.Equals("/dev/ttyUSB", StringComparison.OrdinalIgnoreCase) + || LinuxTtyPortRegex().IsMatch(portName) + || LinuxShortTtyUsbPortRegex().IsMatch(portName)) + { + return true; + } + + if (!portName.StartsWith(LinuxByIdPrefix, StringComparison.Ordinal)) + { + return false; + } + + string deviceId = portName[LinuxByIdPrefix.Length..]; + return deviceId.Length is > 0 and <= MaximumLinuxByIdNameLength + && deviceId is not "." and not ".." + && !deviceId.Any(character => + character is '/' or '\\' || char.IsControl(character)); + } + [GeneratedRegex( + "^COM(?:[1-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-6])$", + RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] + private static partial Regex WindowsComPortRegex(); + + [GeneratedRegex("^ttyUSB[0-9]+$", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] + private static partial Regex LinuxShortTtyUsbPortRegex(); + + [GeneratedRegex("^/dev/tty(?:USB|ACM)[0-9]+$", RegexOptions.CultureInvariant)] + private static partial Regex LinuxTtyPortRegex(); +} diff --git a/src/core/Configuration/SerialPortNameValidator.cs.uid b/src/core/Configuration/SerialPortNameValidator.cs.uid new file mode 100644 index 0000000..9663455 --- /dev/null +++ b/src/core/Configuration/SerialPortNameValidator.cs.uid @@ -0,0 +1 @@ +uid://bdmac4ilu61o2 diff --git a/src/core/Configuration/ServiceAccessPolicy.cs b/src/core/Configuration/ServiceAccessPolicy.cs new file mode 100644 index 0000000..a77b355 --- /dev/null +++ b/src/core/Configuration/ServiceAccessPolicy.cs @@ -0,0 +1,192 @@ +using System; +using System.Security.Cryptography; + +namespace Exchanger.Core.Configuration; + +public enum ServiceAccessLevel +{ + None, + Operator, + Engineer, + Debug, +} + +public enum ServiceAccessStatus +{ + Authorized, + InvalidPin, + Locked, + Unavailable, +} + +public readonly record struct ServiceAccessResult( + ServiceAccessStatus Status, + ServiceAccessLevel Level = ServiceAccessLevel.None, + int RemainingAttempts = 0, + int LockSeconds = 0); + +/// +/// Проверяет сервисный PIN по PBKDF2-SHA256. В конфигурации приложения +/// сохраняются только случайная соль, число итераций и производный хеш. +/// +public sealed class ServiceAccessPolicy +{ + public const int MinimumPinLength = 4; + public const int MaximumPinLength = 12; + public const int MaximumAttempts = 5; + public const int LockDurationSeconds = 30; + public const int DefaultPbkdf2Iterations = 210000; + public const int MinimumPbkdf2Iterations = 100000; + public const int MaximumPbkdf2Iterations = 1000000; + + private const int SaltSizeBytes = 16; + private const int HashSizeBytes = 32; + + private readonly byte[]? _salt; + private readonly byte[]? _expectedHash; + private readonly int _iterations; + private readonly Func _clock; + private int _failedAttempts; + private DateTimeOffset _lockedUntil; + + public ServiceAccessPolicy(SecuritySettings settings, Func? clock = null) + { + ArgumentNullException.ThrowIfNull(settings); + _clock = clock ?? (() => DateTimeOffset.UtcNow); + _iterations = settings.ServicePinIterations; + + if (!settings.ServicePinEnabled + || _iterations is < MinimumPbkdf2Iterations or > MaximumPbkdf2Iterations + || !TryDecode(settings.ServicePinSaltBase64, SaltSizeBytes, out _salt) + || !TryDecode(settings.ServicePinHashBase64, HashSizeBytes, out _expectedHash)) + { + _salt = null; + _expectedHash = null; + } + } + + public bool IsAvailable => _salt is not null && _expectedHash is not null; + + public static bool IsValidPin(string? pin) + { + if (pin is null || pin.Length is < MinimumPinLength or > MaximumPinLength) + { + return false; + } + + foreach (char character in pin) + { + if (character is < '0' or > '9') + { + return false; + } + } + + return true; + } + + public static void SetPin(SecuritySettings settings, string pin) + { + ArgumentNullException.ThrowIfNull(settings); + if (!IsValidPin(pin)) + { + throw new ArgumentException( + $"PIN должен содержать от {MinimumPinLength} до {MaximumPinLength} цифр.", + nameof(pin)); + } + + byte[] salt = RandomNumberGenerator.GetBytes(SaltSizeBytes); + byte[] hash = DeriveHash(pin, salt, DefaultPbkdf2Iterations); + try + { + settings.ServicePinEnabled = true; + settings.ServicePinSaltBase64 = Convert.ToBase64String(salt); + settings.ServicePinHashBase64 = Convert.ToBase64String(hash); + settings.ServicePinIterations = DefaultPbkdf2Iterations; + } + finally + { + CryptographicOperations.ZeroMemory(salt); + CryptographicOperations.ZeroMemory(hash); + } + } + + public static void ClearPin(SecuritySettings settings) + { + ArgumentNullException.ThrowIfNull(settings); + settings.ServicePinSaltBase64 = string.Empty; + settings.ServicePinHashBase64 = string.Empty; + settings.ServicePinIterations = DefaultPbkdf2Iterations; + } + + public ServiceAccessResult Verify(string? pin) + { + DateTimeOffset now = _clock(); + if (!IsAvailable) + { + return new ServiceAccessResult(ServiceAccessStatus.Unavailable); + } + + if (now < _lockedUntil) + { + return new ServiceAccessResult( + ServiceAccessStatus.Locked, + LockSeconds: Math.Max(1, (int)Math.Ceiling((_lockedUntil - now).TotalSeconds))); + } + + byte[] candidate = DeriveHash(pin ?? string.Empty, _salt!, _iterations); + bool matches = CryptographicOperations.FixedTimeEquals(candidate, _expectedHash!); + CryptographicOperations.ZeroMemory(candidate); + + if (matches) + { + _failedAttempts = 0; + _lockedUntil = default; + return new ServiceAccessResult( + ServiceAccessStatus.Authorized, + ServiceAccessLevel.Engineer, + MaximumAttempts); + } + + _failedAttempts++; + if (_failedAttempts >= MaximumAttempts) + { + _failedAttempts = 0; + _lockedUntil = now.AddSeconds(LockDurationSeconds); + return new ServiceAccessResult(ServiceAccessStatus.Locked, LockSeconds: LockDurationSeconds); + } + + return new ServiceAccessResult( + ServiceAccessStatus.InvalidPin, + RemainingAttempts: MaximumAttempts - _failedAttempts); + } + + private static byte[] DeriveHash(string pin, byte[] salt, int iterations) => + Rfc2898DeriveBytes.Pbkdf2( + pin, + salt, + iterations, + HashAlgorithmName.SHA256, + HashSizeBytes); + + private static bool TryDecode(string? value, int expectedSize, out byte[]? bytes) + { + bytes = null; + try + { + byte[] decoded = Convert.FromBase64String(value ?? string.Empty); + if (decoded.Length != expectedSize) + { + CryptographicOperations.ZeroMemory(decoded); + return false; + } + + bytes = decoded; + return true; + } + catch (FormatException) + { + return false; + } + } +} diff --git a/src/core/Configuration/ServiceAccessPolicy.cs.uid b/src/core/Configuration/ServiceAccessPolicy.cs.uid new file mode 100644 index 0000000..04697dd --- /dev/null +++ b/src/core/Configuration/ServiceAccessPolicy.cs.uid @@ -0,0 +1 @@ +uid://bnxswaphkjq4h diff --git a/src/core/Configuration/SettingsChangeSummary.cs b/src/core/Configuration/SettingsChangeSummary.cs new file mode 100644 index 0000000..5ea42b5 --- /dev/null +++ b/src/core/Configuration/SettingsChangeSummary.cs @@ -0,0 +1,72 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; + +namespace Exchanger.Core.Configuration; + +public sealed record SettingsChangeSummary( + IReadOnlyList ChangedSections, + IReadOnlyList RestartRequiredSections) +{ + public bool HasChanges => ChangedSections.Count > 0; + + public bool RestartRequired => RestartRequiredSections.Count > 0; +} + +/// Сравнивает секции без раскрытия значений в журнале изменений. +public static class SettingsChangeDetector +{ + public static SettingsChangeSummary Compare(AppSettings before, AppSettings after) + { + ArgumentNullException.ThrowIfNull(before); + ArgumentNullException.ThrowIfNull(after); + + var changed = new List(); + var restart = new List(); + + AddIfChanged("Общие", new { before.Branding, before.AnimatedBannerTexts, before.Security }, new { after.Branding, after.AnimatedBannerTexts, after.Security }, changed); + AddIfChanged("Звук", before.Audio, after.Audio, changed); + AddIfChanged("Тарифы", before.Pricing, after.Pricing, changed); + AddIfChanged("Оплата", new { before.Payments, before.Timeouts }, new { after.Payments, after.Timeouts }, changed); + AddIfChanged("Промо", before.Advertisement, after.Advertisement, changed); + AddIfChanged( + "Сервис", + new { before.MenuVisibility, before.TokenInventory }, + new { after.MenuVisibility, after.TokenInventory }, + changed); + AddIfChanged("Диагностика", before.Logging, after.Logging, changed); + + AddRestartIfChanged("Оформление", before.Themes, after.Themes, changed, restart); + AddRestartIfChanged("Оборудование", before.Hardware, after.Hardware, changed, restart); + AddRestartIfChanged("Окно", before.Window, after.Window, changed, restart); + + return new SettingsChangeSummary(changed, restart); + } + + private static void AddIfChanged(string name, object before, object after, ICollection changed) + { + if (!Serialize(before).Equals(Serialize(after), StringComparison.Ordinal)) + { + changed.Add(name); + } + } + + private static void AddRestartIfChanged( + string name, + object before, + object after, + ICollection changed, + ICollection restart) + { + if (Serialize(before).Equals(Serialize(after), StringComparison.Ordinal)) + { + return; + } + + changed.Add(name); + restart.Add(name); + } + + private static string Serialize(object value) => JsonSerializer.Serialize(value); +} diff --git a/src/core/Configuration/SettingsChangeSummary.cs.uid b/src/core/Configuration/SettingsChangeSummary.cs.uid new file mode 100644 index 0000000..78b80d7 --- /dev/null +++ b/src/core/Configuration/SettingsChangeSummary.cs.uid @@ -0,0 +1 @@ +uid://busmp3yma8mrl diff --git a/src/core/Configuration/SettingsService.cs b/src/core/Configuration/SettingsService.cs new file mode 100644 index 0000000..05d37ef --- /dev/null +++ b/src/core/Configuration/SettingsService.cs @@ -0,0 +1,474 @@ +using System; +using System.IO; +using System.Text; +using System.Text.Json; +using Exchanger.Hardware.PeripheryController; + +namespace Exchanger.Core.Configuration; + +public enum SettingsLoadSource +{ + User, + UserMigrated, + BackupRecovered, + DefaultsCreated, + DefaultsRecovered, +} + +/// +/// Владеет активным снимком пользовательской конфигурации и сохраняет его +/// атомарно. Godot-пути преобразуются снаружи, поэтому класс тестируется без +/// запуска движка. +/// +public sealed class SettingsService +{ + public const string BackupSuffix = ".bak"; + public const string TemporarySuffix = ".tmp"; + + private static readonly JsonSerializerOptions JsonOptions = new() + { + PropertyNameCaseInsensitive = true, + ReadCommentHandling = JsonCommentHandling.Skip, + AllowTrailingCommas = true, + WriteIndented = true, + }; + + private readonly string _defaultSettingsPath; + private readonly string _userSettingsPath; + private readonly string _backupSettingsPath; + private readonly string _temporarySettingsPath; + private readonly Action? _warningSink; + private AppSettings _current = new(); + + public SettingsService( + string defaultSettingsPath, + string userSettingsPath, + Action? warningSink = null) + { + if (string.IsNullOrWhiteSpace(defaultSettingsPath)) + { + throw new ArgumentException("Не указан путь настроек по умолчанию.", nameof(defaultSettingsPath)); + } + + if (string.IsNullOrWhiteSpace(userSettingsPath)) + { + throw new ArgumentException("Не указан путь пользовательских настроек.", nameof(userSettingsPath)); + } + + _defaultSettingsPath = Path.GetFullPath(defaultSettingsPath); + _userSettingsPath = Path.GetFullPath(userSettingsPath); + _backupSettingsPath = _userSettingsPath + BackupSuffix; + _temporarySettingsPath = _userSettingsPath + TemporarySuffix; + _warningSink = warningSink; + } + + public AppSettings Current => Clone(_current); + + public SettingsLoadSource LastLoadSource { get; private set; } + + public AppSettings Load() + { + DeleteStaleTemporaryFile(); + AppSettings defaults = TryReadSupported( + _defaultSettingsPath, + "встроенные настройки", + out _) ?? new AppSettings(); + AppSettingsMigration.Migrate(defaults); + defaults.Normalize(); + + if (!File.Exists(_userSettingsPath)) + { + _current = Clone(defaults); + TryPersistDuringLoad(_current, createBackup: false); + LastLoadSource = SettingsLoadSource.DefaultsCreated; + return Clone(_current); + } + + AppSettings? loaded = TryReadSupported( + _userSettingsPath, + "пользовательские настройки", + out bool unsupportedUserVersion); + bool recovered = loaded is null; + if (loaded is null) + { + loaded = TryReadSupported( + _backupSettingsPath, + "резервную копию настроек", + out _); + LastLoadSource = loaded is null + ? SettingsLoadSource.DefaultsRecovered + : SettingsLoadSource.BackupRecovered; + loaded ??= Clone(defaults); + } + else + { + LastLoadSource = SettingsLoadSource.User; + } + + bool migrated = AppSettingsMigration.Migrate(loaded); + loaded.Normalize(); + _current = Clone(loaded); + + if (recovered && !unsupportedUserVersion) + { + // Не перезаписываем последнюю корректную .bak повреждённым user-файлом. + TryPersistDuringLoad(_current, createBackup: false); + } + else if (migrated) + { + TryPersistDuringLoad(_current, createBackup: true); + LastLoadSource = SettingsLoadSource.UserMigrated; + } + + return Clone(_current); + } + + public AppSettings CreateWorkingCopy() => Clone(_current); + + public AppSettings CreateDefaultWorkingCopy() + { + AppSettings defaults = TryReadSupported( + _defaultSettingsPath, + "встроенные настройки", + out _) ?? new AppSettings(); + AppSettingsMigration.Migrate(defaults); + defaults.Normalize(); + return Clone(defaults); + } + + public AppSettings Save(AppSettings candidate) + { + ArgumentNullException.ThrowIfNull(candidate); + + AppSettings normalized = Clone(candidate); + AppSettingsMigration.Migrate(normalized); + normalized.Normalize(); + WriteAtomic(normalized, createBackup: true); + _current = Clone(normalized); + return Clone(_current); + } + + private AppSettings? TryRead(string path, string description) + { + if (!File.Exists(path)) + { + return null; + } + + try + { + string json = File.ReadAllText(path, Encoding.UTF8); + return JsonSerializer.Deserialize(json, JsonOptions); + } + catch (Exception exception) when (exception is IOException + or UnauthorizedAccessException + or JsonException + or NotSupportedException) + { + _warningSink?.Invoke($"Не удалось прочитать {description}: {exception.GetType().Name}."); + return null; + } + } + + private AppSettings? TryReadSupported(string path, string description, out bool unsupportedVersion) + { + unsupportedVersion = false; + AppSettings? settings = TryRead(path, description); + if (settings is null || settings.ConfigurationVersion <= AppSettings.CurrentConfigurationVersion) + { + return settings; + } + + unsupportedVersion = true; + _warningSink?.Invoke( + $"Не удалось применить {description}: версия {settings.ConfigurationVersion} новее поддерживаемой."); + return null; + } + + private void TryPersistDuringLoad(AppSettings settings, bool createBackup) + { + try + { + WriteAtomic(settings, createBackup); + } + catch (Exception exception) when (exception is IOException + or UnauthorizedAccessException + or InvalidDataException + or NotSupportedException) + { + _warningSink?.Invoke($"Не удалось сохранить пользовательские настройки: {exception.GetType().Name}."); + } + } + + private void WriteAtomic(AppSettings settings, bool createBackup) + { + string? directory = Path.GetDirectoryName(_userSettingsPath); + if (!string.IsNullOrEmpty(directory)) + { + Directory.CreateDirectory(directory); + } + + try + { + byte[] json = Encoding.UTF8.GetBytes(JsonSerializer.Serialize(settings, JsonOptions)); + using (var stream = new FileStream( + _temporarySettingsPath, + FileMode.Create, + FileAccess.Write, + FileShare.None, + bufferSize: 4096, + FileOptions.WriteThrough)) + { + stream.Write(json); + stream.Flush(flushToDisk: true); + } + + if (TryRead(_temporarySettingsPath, "временный файл настроек") is null) + { + throw new InvalidDataException("Временный файл настроек не прошёл проверку."); + } + + if (!File.Exists(_userSettingsPath)) + { + File.Move(_temporarySettingsPath, _userSettingsPath); + return; + } + + if (!createBackup) + { + File.Move(_temporarySettingsPath, _userSettingsPath, overwrite: true); + return; + } + + try + { + File.Replace( + _temporarySettingsPath, + _userSettingsPath, + _backupSettingsPath, + ignoreMetadataErrors: true); + } + catch (PlatformNotSupportedException) + { + ReplaceWithPortableFallback(); + } + catch (IOException) + { + ReplaceWithPortableFallback(); + } + } + finally + { + if (File.Exists(_temporarySettingsPath)) + { + try + { + File.Delete(_temporarySettingsPath); + } + catch (IOException) + { + _warningSink?.Invoke("Не удалось удалить временный файл настроек: IOException."); + } + catch (UnauthorizedAccessException) + { + _warningSink?.Invoke("Не удалось удалить временный файл настроек: UnauthorizedAccessException."); + } + } + } + } + + private void ReplaceWithPortableFallback() + { + File.Copy(_userSettingsPath, _backupSettingsPath, overwrite: true); + File.Move(_temporarySettingsPath, _userSettingsPath, overwrite: true); + } + + private void DeleteStaleTemporaryFile() + { + if (!File.Exists(_temporarySettingsPath)) + { + return; + } + + try + { + File.Delete(_temporarySettingsPath); + } + catch (IOException) + { + _warningSink?.Invoke("Не удалось удалить незавершённый временный файл настроек: IOException."); + } + catch (UnauthorizedAccessException) + { + _warningSink?.Invoke("Не удалось удалить незавершённый временный файл настроек: UnauthorizedAccessException."); + } + } + + private static AppSettings Clone(AppSettings settings) + { + string json = JsonSerializer.Serialize(settings, JsonOptions); + return JsonSerializer.Deserialize(json, JsonOptions) ?? new AppSettings(); + } +} + +public static class AppSettingsMigration +{ + public static bool Migrate(AppSettings settings) + { + ArgumentNullException.ThrowIfNull(settings); + + settings.Window ??= new WindowSettings(); + settings.Themes ??= new ThemeSettings(); + settings.Hardware ??= new HardwareSettings(); + settings.Audio ??= new AudioSettings(); + settings.Payments ??= new PaymentSettings(); + settings.AnimatedBannerTexts ??= new AnimatedBannerTextSettings(); + settings.Security ??= new SecuritySettings(); + settings.Timeouts ??= new TimeoutSettings(); + settings.MenuVisibility ??= new MenuVisibilitySettings(); + settings.TokenInventory ??= new TokenInventorySettings(); + + if (settings.ConfigurationVersion > AppSettings.CurrentConfigurationVersion) + { + throw new NotSupportedException( + $"Версия настроек {settings.ConfigurationVersion} новее поддерживаемой " + + AppSettings.CurrentConfigurationVersion + "."); + } + + if (settings.ConfigurationVersion >= AppSettings.CurrentConfigurationVersion) + { + return false; + } + + if (settings.ConfigurationVersion < 2 + && settings.Window.DebugWindowWidth == 1280 + && settings.Window.DebugWindowHeight == 720) + { + settings.Window.DebugWindowWidth = 720; + settings.Window.DebugWindowHeight = 1280; + } + + if (settings.ConfigurationVersion < 3 && settings.Hardware.BaudRate == 9600) + { + settings.Hardware.BaudRate = 115200; + } + + if (settings.ConfigurationVersion < 6 + && string.IsNullOrWhiteSpace(settings.Hardware.ControllerAesMode)) + { + settings.Hardware.ControllerAesMode = "ECB"; + } + + if (settings.ConfigurationVersion < 10 + && settings.Hardware.StockSensorInputIndex < 0) + { + settings.Hardware.StockSensorInputIndex = 1; + settings.Hardware.StockLowWhenInputHigh = false; + } + + if (settings.ConfigurationVersion < 13 + && settings.Hardware.StockSensorInputIndex == 1) + { + // Все цифровые входы платы имеют pull-up: активный сигнал сбрасывает бит. + // Поэтому IN1=0 означает «мало жетонов», а IN1=1 — «много жетонов». + settings.Hardware.StockLowWhenInputHigh = false; + } + + if (settings.ConfigurationVersion < 15 + && settings.Hardware.DispenseMode.Equals("Hopper1Auto", StringComparison.OrdinalIgnoreCase) + && settings.Hardware.StockSensorInputIndex == 1 + && settings.Hardware.Hopper1DispenseSensorInputIndex == 25) + { + // Подключённый автомат использует второй аппаратный хоппер: IN1/IN25 и команду 409. + settings.Hardware.DispenseMode = "Hopper2Auto"; + } + + if (settings.ConfigurationVersion < 16) + { + if (!settings.Hardware.DispenseMode.Equals("Hopper1Auto", StringComparison.OrdinalIgnoreCase)) + { + // До v16 единственное поле с именем Hopper1 фактически задавало датчик + // активного целевого второго хоппера. Переносим его в явную пару IN25. + if (settings.Hardware.Hopper1DispenseSensorInputIndex + != PeripheryControllerInputs.Hopper1DispensePulse) + { + settings.Hardware.Hopper2DispenseSensorInputIndex = + settings.Hardware.Hopper1DispenseSensorInputIndex; + settings.Hardware.Hopper2DispenseSensorActiveHigh = + settings.Hardware.Hopper1DispenseSensorActiveHigh; + } + + settings.Hardware.Hopper1DispenseSensorInputIndex = + PeripheryControllerInputs.Hopper1DispensePulse; + settings.Hardware.Hopper1DispenseSensorActiveHigh = false; + } + else + { + settings.Hardware.Hopper2DispenseSensorInputIndex = + 25; + settings.Hardware.Hopper2DispenseSensorActiveHigh = false; + } + } + + if (settings.ConfigurationVersion < 17) + { + // Актуальная прошивка полностью меняет целевую разводку. До уточнения + // второго датчика выдачи приложение использует только hopper 1 / 30X. + settings.Hardware.ServiceButtonInputIndex = PeripheryControllerInputs.ServiceButton; + settings.Hardware.ServiceButtonActiveHigh = false; + settings.Hardware.StockSensorInputIndex = PeripheryControllerInputs.Hopper1StockLow; + settings.Hardware.StockLowWhenInputHigh = false; + settings.Hardware.Hopper1DispenseSensorInputIndex = + PeripheryControllerInputs.Hopper1DispensePulse; + settings.Hardware.Hopper1DispenseSensorActiveHigh = false; + settings.Hardware.Hopper2DispenseSensorInputIndex = + PeripheryControllerInputs.Hopper2DispensePulse; + settings.Hardware.Hopper2DispenseSensorActiveHigh = false; + if (settings.Hardware.DispenseMode.Equals("Hopper2Auto", StringComparison.OrdinalIgnoreCase)) + { + settings.Hardware.DispenseMode = "Hopper1Auto"; + } + } + + if (settings.ConfigurationVersion < 18) + { + // Оба хоппера подтверждены владельцем: IN1/30X и IN4/40X. + settings.Hardware.ServiceButtonInputIndex = PeripheryControllerInputs.ServiceButton; + settings.Hardware.ServiceButtonActiveHigh = false; + settings.Hardware.StockSensorInputIndex = PeripheryControllerInputs.Hopper1StockLow; + settings.Hardware.StockLowWhenInputHigh = false; + settings.Hardware.Hopper2StockSensorInputIndex = PeripheryControllerInputs.Hopper2StockLow; + settings.Hardware.Hopper2StockLowWhenInputHigh = false; + if (settings.Hardware.DispenseMode.Equals("Hopper1Auto", StringComparison.OrdinalIgnoreCase) + || settings.Hardware.DispenseMode.Equals("Hopper2Auto", StringComparison.OrdinalIgnoreCase)) + { + settings.Hardware.DispenseMode = "DualHopperAuto"; + } + } + + if (settings.ConfigurationVersion < 19 + && settings.Hardware.HandshakeTimeoutMilliseconds == 5000) + { + // Актуальный plate_config_app ждёт CHAL и RAES по 2 секунды. + // Меняем только прежний стандартный default, не затирая явную + // пользовательскую настройку другого таймаута. + settings.Hardware.HandshakeTimeoutMilliseconds = 2000; + } + + if (settings.ConfigurationVersion < 20) + { + // До v20 наличная ветка использовала SessionIdleSeconds, а поле + // PaymentSeconds задавало ожидание безналичного терминала. + settings.Timeouts.CashPaymentSeconds = settings.Timeouts.SessionIdleSeconds; + if (settings.Timeouts.LegacyPaymentSeconds > 0) + { + settings.Timeouts.CashlessPaymentSeconds = settings.Timeouts.LegacyPaymentSeconds; + } + + settings.Timeouts.LegacyPaymentSeconds = 0; + } + + settings.ConfigurationVersion = AppSettings.CurrentConfigurationVersion; + return true; + } +} diff --git a/src/core/Configuration/SettingsService.cs.uid b/src/core/Configuration/SettingsService.cs.uid new file mode 100644 index 0000000..af94318 --- /dev/null +++ b/src/core/Configuration/SettingsService.cs.uid @@ -0,0 +1 @@ +uid://cvq0x60u62p2d diff --git a/src/core/Configuration/ThemeSettingsValidator.cs b/src/core/Configuration/ThemeSettingsValidator.cs new file mode 100644 index 0000000..dd79ab9 --- /dev/null +++ b/src/core/Configuration/ThemeSettingsValidator.cs @@ -0,0 +1,86 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; + +namespace Exchanger.Core.Configuration; + +public enum ThemeValidationField +{ + ExternalDlcPath, +} + +public readonly record struct ThemeValidationIssue(ThemeValidationField Field, string Message); + +public sealed class ThemeValidationResult +{ + public ThemeValidationResult(IReadOnlyList issues) + { + Issues = issues ?? throw new ArgumentNullException(nameof(issues)); + } + + public IReadOnlyList Issues { get; } + + public bool IsValid => Issues.Count == 0; +} + +/// Проверяет путь к единственному внешнему PCK без монтирования пакета. +public static class ThemeSettingsValidator +{ + public const int MaximumDlcPathLength = 512; + + public static ThemeValidationResult Validate(ThemeSettings settings) + { + ArgumentNullException.ThrowIfNull(settings); + + var issues = new List(); + if (!settings.ExternalDlcEnabled) + { + return new ThemeValidationResult(issues); + } + + string path = settings.ExternalDlcPath?.Trim() ?? string.Empty; + if (path.Length == 0) + { + issues.Add(new ThemeValidationIssue( + ThemeValidationField.ExternalDlcPath, + "Укажите путь к внешнему DLC или отключите его загрузку.")); + return new ThemeValidationResult(issues); + } + + if (path.Length > MaximumDlcPathLength || path.Any(char.IsControl)) + { + issues.Add(new ThemeValidationIssue( + ThemeValidationField.ExternalDlcPath, + "Путь к DLC содержит недопустимые символы или слишком длинный.")); + return new ThemeValidationResult(issues); + } + + bool userPath = path.StartsWith("user://", StringComparison.OrdinalIgnoreCase); + if (!userPath && !Path.IsPathFullyQualified(path)) + { + issues.Add(new ThemeValidationIssue( + ThemeValidationField.ExternalDlcPath, + "Используйте user:// или абсолютный локальный путь к PCK.")); + return new ThemeValidationResult(issues); + } + + string normalized = path.Replace('\\', '/'); + if (normalized.Split('/').Any(segment => segment == "..")) + { + issues.Add(new ThemeValidationIssue( + ThemeValidationField.ExternalDlcPath, + "Переходы «..» в пути к DLC запрещены.")); + return new ThemeValidationResult(issues); + } + + if (!Path.GetExtension(path).Equals(".pck", StringComparison.OrdinalIgnoreCase)) + { + issues.Add(new ThemeValidationIssue( + ThemeValidationField.ExternalDlcPath, + "Внешняя тема должна быть пакетом с расширением .pck.")); + } + + return new ThemeValidationResult(issues); + } +} diff --git a/src/core/Configuration/ThemeSettingsValidator.cs.uid b/src/core/Configuration/ThemeSettingsValidator.cs.uid new file mode 100644 index 0000000..56c1f34 --- /dev/null +++ b/src/core/Configuration/ThemeSettingsValidator.cs.uid @@ -0,0 +1 @@ +uid://c67qjdvkbh12p diff --git a/src/core/Inventory/TokenInventoryLoader.cs b/src/core/Inventory/TokenInventoryLoader.cs new file mode 100644 index 0000000..ba597af --- /dev/null +++ b/src/core/Inventory/TokenInventoryLoader.cs @@ -0,0 +1,13 @@ +using Exchanger.Core.Logging; +using Godot; + +namespace Exchanger.Core.Inventory; + +public static class TokenInventoryLoader +{ + private const string UserInventoryPath = "user://data/token_inventory.json"; + + public static TokenInventoryStore CreateStore() => new( + ProjectSettings.GlobalizePath(UserInventoryPath), + warningSink: message => AppLogger.Warning("TokenInventory", message)); +} diff --git a/src/core/Inventory/TokenInventoryLoader.cs.uid b/src/core/Inventory/TokenInventoryLoader.cs.uid new file mode 100644 index 0000000..c0fe2dc --- /dev/null +++ b/src/core/Inventory/TokenInventoryLoader.cs.uid @@ -0,0 +1 @@ +uid://cx0nrr0ya0ybo diff --git a/src/core/Inventory/TokenInventoryPolicy.cs b/src/core/Inventory/TokenInventoryPolicy.cs new file mode 100644 index 0000000..99ffdde --- /dev/null +++ b/src/core/Inventory/TokenInventoryPolicy.cs @@ -0,0 +1,123 @@ +using Exchanger.Core.Session; +using Exchanger.Hardware.Abstractions; +using System; + +namespace Exchanger.Core.Inventory; + +public enum TokenHopper +{ + Hopper1 = 1, + Hopper2 = 2, +} + +public enum TokenAvailabilityLevel +{ + Unknown, + Empty, + Low, + Enough, + Much, +} + +/// Единые правила показа общего запаса двух хопперов. +public static class TokenInventoryPolicy +{ + public static TokenAvailabilityLevel ResolveAvailability( + int totalCount, + MachineStockLevel hopper1, + MachineStockLevel hopper2) + { + if (totalCount <= 0) + { + return TokenAvailabilityLevel.Empty; + } + + bool bothEnough = hopper1 == MachineStockLevel.Enough + && hopper2 == MachineStockLevel.Enough; + if (bothEnough) + { + return TokenAvailabilityLevel.Much; + } + + bool bothLow = hopper1 == MachineStockLevel.Low + && hopper2 == MachineStockLevel.Low; + if (totalCount < 100 || bothLow) + { + return TokenAvailabilityLevel.Low; + } + + if (totalCount >= 100 + || hopper1 == MachineStockLevel.Enough + || hopper2 == MachineStockLevel.Enough) + { + return TokenAvailabilityLevel.Enough; + } + + return TokenAvailabilityLevel.Low; + } + + public static TokenAvailabilityLevel ResolveWithoutInventory( + MachineStockLevel hopper1, + MachineStockLevel hopper2, + bool hopper1Enabled, + bool hopper2Enabled) + { + if (!hopper1Enabled && !hopper2Enabled) + { + return TokenAvailabilityLevel.Unknown; + } + + bool anyEnough = hopper1Enabled && hopper1 == MachineStockLevel.Enough + || hopper2Enabled && hopper2 == MachineStockLevel.Enough; + if (anyEnough) + { + return TokenAvailabilityLevel.Enough; + } + + bool anyLow = hopper1Enabled && hopper1 == MachineStockLevel.Low + || hopper2Enabled && hopper2 == MachineStockLevel.Low; + return anyLow ? TokenAvailabilityLevel.Low : TokenAvailabilityLevel.Unknown; + } + + public static string FormatApproximateCount(int totalCount) + { + int count = Math.Max(0, totalCount); + if (count == 0) + { + return "нет жетонов"; + } + + if (count < 100) + { + return "<100"; + } + + int step = count > 1000 ? 500 : 100; + int lowerBound = count / step * step; + return count % step == 0 + ? $"~{count}" + : $">{lowerBound}"; + } + + public static string FormatExactCount(int totalCount) + => TokenCountFormatter.Format(totalCount); + + public static string FormatHopperExactCount(int hopperNumber, int count) + { + if (hopperNumber is not 1 and not 2) + { + throw new ArgumentOutOfRangeException(nameof(hopperNumber)); + } + + return $"ХОППЕР {hopperNumber} — ОСТАТОК: {TokenCountFormatter.FormatUpper(count)}"; + } + + public static string FormatAvailability(TokenAvailabilityLevel level) => level switch + { + TokenAvailabilityLevel.Empty => "НЕТ ЖЕТОНОВ", + TokenAvailabilityLevel.Low => "МАЛО", + TokenAvailabilityLevel.Enough => "ДОСТАТОЧНО", + TokenAvailabilityLevel.Much => "МНОГО", + _ => "НЕТ ДАННЫХ", + }; +} diff --git a/src/core/Inventory/TokenInventoryPolicy.cs.uid b/src/core/Inventory/TokenInventoryPolicy.cs.uid new file mode 100644 index 0000000..f66ef31 --- /dev/null +++ b/src/core/Inventory/TokenInventoryPolicy.cs.uid @@ -0,0 +1 @@ +uid://b0mcwtvy2tfti diff --git a/src/core/Inventory/TokenInventoryStore.cs b/src/core/Inventory/TokenInventoryStore.cs new file mode 100644 index 0000000..5cdacc8 --- /dev/null +++ b/src/core/Inventory/TokenInventoryStore.cs @@ -0,0 +1,320 @@ +using System; +using System.IO; +using System.Text.Json; + +namespace Exchanger.Core.Inventory; + +/// Точный внутренний учёт по двум хопперам. Count всегда равен их сумме. +public sealed record TokenInventorySnapshot +{ + public int Count { get; init; } + + public int Hopper1Count { get; init; } + + public int Hopper2Count { get; init; } + + public long Revision { get; init; } + + public DateTimeOffset UpdatedAtUtc { get; init; } +} + +/// +/// Атомарно хранит учётный остаток отдельно от appsettings.json. При повреждении +/// основного файла восстанавливается из последней проверенной копии. +/// +public sealed class TokenInventoryStore +{ + public const int MaximumTokenCount = 1_000_000; + + private static readonly JsonSerializerOptions JsonOptions = new() + { + WriteIndented = true, + PropertyNameCaseInsensitive = true, + }; + + private readonly object _syncRoot = new(); + private readonly string _path; + private readonly string _backupPath; + private readonly string _temporaryPath; + private readonly Func _utcNow; + private readonly Action? _warningSink; + private TokenInventorySnapshot? _current; + + public TokenInventoryStore( + string path, + Func? utcNow = null, + Action? warningSink = null) + { + if (string.IsNullOrWhiteSpace(path)) + { + throw new ArgumentException("Путь файла учёта жетонов не задан.", nameof(path)); + } + + _path = Path.GetFullPath(path); + _backupPath = _path + ".bak"; + _temporaryPath = _path + ".tmp"; + _utcNow = utcNow ?? (() => DateTimeOffset.UtcNow); + _warningSink = warningSink; + } + + public TokenInventorySnapshot Load() + { + lock (_syncRoot) + { + TokenInventorySnapshot? loaded = TryRead(_path, "основной файл") + ?? TryRead(_backupPath, "резервную копию"); + _current = loaded ?? CreateSnapshot(0, 0, 0); + + if (loaded is null || !File.Exists(_path)) + { + WriteAtomic(_current); + } + + return _current; + } + } + + /// Совместимость со старым API: заменяет общий остаток и относит его к первому хопперу. + public TokenInventorySnapshot SetCount(int count) => SetCounts(count, 0); + + public TokenInventorySnapshot SetCounts(int hopper1Count, int hopper2Count) + { + ValidateCounts(hopper1Count, hopper2Count); + lock (_syncRoot) + { + TokenInventorySnapshot current = EnsureLoaded(); + return Persist(hopper1Count, hopper2Count, current.Revision + 1); + } + } + + public TokenInventorySnapshot SetHopperCount(TokenHopper hopper, int count) + { + ValidateCount(count, nameof(count)); + lock (_syncRoot) + { + TokenInventorySnapshot current = EnsureLoaded(); + return hopper switch + { + TokenHopper.Hopper1 => Persist(count, current.Hopper2Count, current.Revision + 1), + TokenHopper.Hopper2 => Persist(current.Hopper1Count, count, current.Revision + 1), + _ => throw new ArgumentOutOfRangeException(nameof(hopper)), + }; + } + } + + /// Совместимость со старым API: добавляет жетоны в первый хоппер. + public TokenInventorySnapshot Add(int count) => Add(TokenHopper.Hopper1, count); + + public TokenInventorySnapshot Add(TokenHopper hopper, int count) + { + if (count <= 0) + { + throw new ArgumentOutOfRangeException(nameof(count), "Добавляемое количество должно быть больше нуля."); + } + + lock (_syncRoot) + { + TokenInventorySnapshot current = EnsureLoaded(); + int hopper1 = current.Hopper1Count; + int hopper2 = current.Hopper2Count; + switch (hopper) + { + case TokenHopper.Hopper1: + hopper1 = checked(hopper1 + count); + break; + case TokenHopper.Hopper2: + hopper2 = checked(hopper2 + count); + break; + default: + throw new ArgumentOutOfRangeException(nameof(hopper)); + } + + ValidateCounts(hopper1, hopper2); + return Persist(hopper1, hopper2, current.Revision + 1); + } + } + + /// Совместимость со старым API: списывает сначала первый, затем второй хоппер. + public TokenInventorySnapshot RemoveDispensed(int count) + { + if (count < 0) + { + throw new ArgumentOutOfRangeException(nameof(count)); + } + + lock (_syncRoot) + { + TokenInventorySnapshot current = EnsureLoaded(); + int fromFirst = Math.Min(current.Hopper1Count, count); + int remaining = count - fromFirst; + return count == 0 + ? current + : Persist( + current.Hopper1Count - fromFirst, + Math.Max(0, current.Hopper2Count - remaining), + current.Revision + 1); + } + } + + public TokenInventorySnapshot RemoveDispensed(TokenHopper hopper, int count) + { + if (count < 0) + { + throw new ArgumentOutOfRangeException(nameof(count)); + } + + lock (_syncRoot) + { + TokenInventorySnapshot current = EnsureLoaded(); + if (count == 0) + { + return current; + } + + return hopper switch + { + TokenHopper.Hopper1 => Persist( + Math.Max(0, current.Hopper1Count - count), + current.Hopper2Count, + current.Revision + 1), + TokenHopper.Hopper2 => Persist( + current.Hopper1Count, + Math.Max(0, current.Hopper2Count - count), + current.Revision + 1), + _ => throw new ArgumentOutOfRangeException(nameof(hopper)), + }; + } + } + + private TokenInventorySnapshot EnsureLoaded() => _current ?? Load(); + + private TokenInventorySnapshot Persist(int hopper1Count, int hopper2Count, long revision) + { + TokenInventorySnapshot next = CreateSnapshot(hopper1Count, hopper2Count, revision); + WriteAtomic(next); + _current = next; + return next; + } + + private TokenInventorySnapshot CreateSnapshot(int hopper1Count, int hopper2Count, long revision) => new() + { + Count = hopper1Count + hopper2Count, + Hopper1Count = hopper1Count, + Hopper2Count = hopper2Count, + Revision = revision, + UpdatedAtUtc = _utcNow(), + }; + + private TokenInventorySnapshot? TryRead(string path, string description) + { + if (!File.Exists(path)) + { + return null; + } + + try + { + TokenInventorySnapshot? snapshot = JsonSerializer.Deserialize( + File.ReadAllText(path), + JsonOptions); + if (snapshot is null || snapshot.Revision < 0) + { + return InvalidSnapshot(description); + } + + int hopper1 = snapshot.Hopper1Count; + int hopper2 = snapshot.Hopper2Count; + if (hopper1 == 0 && hopper2 == 0 && snapshot.Count > 0) + { + hopper1 = snapshot.Count; + } + + if (!AreCountsValid(hopper1, hopper2)) + { + return InvalidSnapshot(description); + } + + return snapshot with + { + Count = hopper1 + hopper2, + Hopper1Count = hopper1, + Hopper2Count = hopper2, + }; + } + catch (Exception exception) when (exception is IOException or UnauthorizedAccessException or JsonException) + { + _warningSink?.Invoke($"Не удалось прочитать {description} учёта жетонов: {exception.GetType().Name}."); + return null; + } + } + + private TokenInventorySnapshot? InvalidSnapshot(string description) + { + _warningSink?.Invoke($"Не удалось прочитать {description} учёта жетонов: данные некорректны."); + return null; + } + + private void WriteAtomic(TokenInventorySnapshot snapshot) + { + string? directory = Path.GetDirectoryName(_path); + if (!string.IsNullOrWhiteSpace(directory)) + { + Directory.CreateDirectory(directory); + } + + try + { + File.WriteAllText(_temporaryPath, JsonSerializer.Serialize(snapshot, JsonOptions)); + TokenInventorySnapshot? verified = TryRead(_temporaryPath, "временный файл"); + if (verified is null + || verified.Hopper1Count != snapshot.Hopper1Count + || verified.Hopper2Count != snapshot.Hopper2Count + || verified.Revision != snapshot.Revision) + { + throw new IOException("Временный файл учёта жетонов не прошёл проверку."); + } + + if (File.Exists(_path)) + { + File.Copy(_path, _backupPath, overwrite: true); + File.Move(_temporaryPath, _path, overwrite: true); + } + else + { + File.Move(_temporaryPath, _path); + } + } + finally + { + if (File.Exists(_temporaryPath)) + { + File.Delete(_temporaryPath); + } + } + } + + private static bool AreCountsValid(int hopper1Count, int hopper2Count) => + hopper1Count >= 0 + && hopper2Count >= 0 + && (long)hopper1Count + hopper2Count <= MaximumTokenCount; + + private static void ValidateCounts(int hopper1Count, int hopper2Count) + { + if (!AreCountsValid(hopper1Count, hopper2Count)) + { + throw new ArgumentOutOfRangeException( + nameof(hopper1Count), + $"Общий остаток двух хопперов должен быть от 0 до {MaximumTokenCount} жетонов."); + } + } + + private static void ValidateCount(int count, string parameterName) + { + if (count is < 0 or > MaximumTokenCount) + { + throw new ArgumentOutOfRangeException( + parameterName, + $"Остаток должен быть от 0 до {MaximumTokenCount} жетонов."); + } + } +} diff --git a/src/core/Inventory/TokenInventoryStore.cs.uid b/src/core/Inventory/TokenInventoryStore.cs.uid new file mode 100644 index 0000000..5237de1 --- /dev/null +++ b/src/core/Inventory/TokenInventoryStore.cs.uid @@ -0,0 +1 @@ +uid://dolj6tnmhg830 diff --git a/src/core/Logging/AppLogger.cs b/src/core/Logging/AppLogger.cs new file mode 100644 index 0000000..af43c76 --- /dev/null +++ b/src/core/Logging/AppLogger.cs @@ -0,0 +1,199 @@ +using Exchanger.Core.Configuration; +using Godot; +using System; +using System.Globalization; +using System.Collections.Generic; +using System.Diagnostics; +using System.IO; +using System.Linq; + +namespace Exchanger.Core.Logging; + +/// +/// Минимальный потокобезопасный журнал приложения с ограничением размера и +/// срока хранения. После инициализации не обращается к объектам Godot. +/// +public static class AppLogger +{ + private const int RecentEntryCapacity = 20; + private static readonly object SyncRoot = new(); + private static string? _logFilePath; + private static long _maxFileSizeBytes = 5L * 1024 * 1024; + private static AppLogLevel _minimumLevel = AppLogLevel.Info; + private static readonly Queue RecentEntries = new(); + + public static void Initialize(LoggingSettings settings) + { + lock (SyncRoot) + { + string logDirectory = ProjectSettings.GlobalizePath("user://logs"); + Directory.CreateDirectory(logDirectory); + + _maxFileSizeBytes = settings.MaxFileSizeMb * 1024L * 1024L; +#if DEBUG + _minimumLevel = AppLogLevel.Debug; +#else + _minimumLevel = ParseLevel(settings.MinimumLevel); +#endif + + _logFilePath = Path.Combine(logDirectory, "exchanger.log"); + RotateIfRequired(); + LogMaintenance.Prune( + logDirectory, + settings.RetentionDays, + _maxFileSizeBytes * 10, + _logFilePath, + Path.Combine(logDirectory, "operations.jsonl"), + Path.Combine(logDirectory, "settings-audit.jsonl")); + WriteUnsafe(AppLogLevel.Info, "Application", "Журнал приложения инициализирован."); +#if DEBUG + WriteUnsafe( + AppLogLevel.Debug, + "Application", + "Расширенная безопасная диагностика DEBUG-сборки включена."); +#endif + } + } + + [Conditional("DEBUG")] + public static void Debug(string category, string message) => + Write(AppLogLevel.Debug, category, message); + + public static void Info(string category, string message) => Write(AppLogLevel.Info, category, message); + + public static void Warning(string category, string message) => Write(AppLogLevel.Warning, category, message); + + public static void Error(string category, string message, Exception? exception = null) + { + string details = exception is null ? message : $"{message} | {exception.GetType().Name}: {exception.Message}"; + Write(AppLogLevel.Error, category, details); + } + + public static IReadOnlyList GetRecentSafeEntries(int maximumCount = 5) + { + lock (SyncRoot) + { + return RecentEntries.TakeLast(Math.Clamp(maximumCount, 0, RecentEntryCapacity)).ToArray(); + } + } + + public static void Shutdown() + { + lock (SyncRoot) + { + if (_logFilePath is null) + { + return; + } + + WriteUnsafe(AppLogLevel.Info, "Application", "Журнал приложения завершён."); + _logFilePath = null; + } + } + + private static void Write(AppLogLevel level, string category, string message) + { + lock (SyncRoot) + { + if (level < _minimumLevel) + { + return; + } + + RotateIfRequired(); + WriteUnsafe(level, category, message); + } + } + + private static void WriteUnsafe(AppLogLevel level, string category, string message) + { + DateTimeOffset timestamp = DateTimeOffset.Now; + string line = $"{timestamp:O} [{FormatLevel(level)}] [{category}] {message}"; + Console.WriteLine(line); + + if (level >= AppLogLevel.Warning) + { + RecentEntries.Enqueue(new SafeDiagnosticEntry( + timestamp, + level, + NormalizeCategory(category), + SafeDiagnosticText.Sanitize(message))); + while (RecentEntries.Count > RecentEntryCapacity) + { + RecentEntries.Dequeue(); + } + } + + if (_logFilePath is not null) + { + File.AppendAllText(_logFilePath, line + System.Environment.NewLine); + } + } + + private static void RotateIfRequired() + { + if (_logFilePath is null || !File.Exists(_logFilePath)) + { + return; + } + + var file = new FileInfo(_logFilePath); + if (file.Length < _maxFileSizeBytes) + { + return; + } + + string directory = file.DirectoryName ?? string.Empty; + string archiveName = $"exchanger-{DateTimeOffset.Now:yyyyMMdd-HHmmss-fff}.log"; + File.Move(_logFilePath, Path.Combine(directory, archiveName)); + } + + private static AppLogLevel ParseLevel(string? value) => value?.Trim().ToUpperInvariant() switch + { + "WARNING" => AppLogLevel.Warning, + "ERROR" => AppLogLevel.Error, + _ => AppLogLevel.Info, + }; + + private static string FormatLevel(AppLogLevel level) => level == AppLogLevel.Warning ? "WARN" : level.ToString().ToUpperInvariant(); + + private static string NormalizeCategory(string? category) => string.IsNullOrWhiteSpace(category) + ? "Application" + : category.Trim()[..Math.Min(category.Trim().Length, 48)]; +} + +public enum AppLogLevel +{ + Debug = 0, + Info = 1, + Warning = 2, + Error = 3, +} + +public readonly record struct SafeDiagnosticEntry( + DateTimeOffset Timestamp, + AppLogLevel Level, + string Category, + string Message); + +public static class SafeDiagnosticText +{ + public static string Sanitize(string? value) + { + string text = string.Join(" ", (value ?? string.Empty).Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries)); + if (text.Contains("user://", StringComparison.OrdinalIgnoreCase) + || text.Contains("res://", StringComparison.OrdinalIgnoreCase) + || text.Contains(":\\", StringComparison.Ordinal)) + { + return "Подробности с локальным путём скрыты."; + } + + if (text.Contains("RAW", StringComparison.OrdinalIgnoreCase) + || text.Contains("FRAME", StringComparison.OrdinalIgnoreCase)) + { + return "Содержимое протокольного сообщения скрыто."; + } + + return text.Length <= 180 ? text : text[..180] + "…"; + } +} diff --git a/src/core/Logging/AppLogger.cs.uid b/src/core/Logging/AppLogger.cs.uid new file mode 100644 index 0000000..8d0072e --- /dev/null +++ b/src/core/Logging/AppLogger.cs.uid @@ -0,0 +1 @@ +uid://cwhn6bbe3ru71 diff --git a/src/core/Logging/ConfigurationAuditJournal.cs b/src/core/Logging/ConfigurationAuditJournal.cs new file mode 100644 index 0000000..1e92d9e --- /dev/null +++ b/src/core/Logging/ConfigurationAuditJournal.cs @@ -0,0 +1,66 @@ +using Exchanger.Core.Configuration; +using Godot; +using System; +using System.IO; + +namespace Exchanger.Core.Logging; + +/// Godot-композиция безопасного журнала изменения конфигурации. +public static class ConfigurationAuditJournal +{ + private static readonly object SyncRoot = new(); + private static ConfigurationAuditStore? _store; + + public static void Initialize(LoggingSettings settings) + { + lock (SyncRoot) + { + string directory = ProjectSettings.GlobalizePath("user://logs"); + Directory.CreateDirectory(directory); + string path = Path.Combine(directory, "settings-audit.jsonl"); + RotateIfRequired(path, settings.MaxFileSizeMb); + LogMaintenance.Prune( + directory, + settings.RetentionDays, + settings.MaxFileSizeMb * 10L * 1024L * 1024L, + Path.Combine(directory, "exchanger.log"), + Path.Combine(directory, "operations.jsonl"), + path); + _store = new ConfigurationAuditStore(path); + } + } + + public static void Record(SettingsChangeSummary summary, ServiceAccessLevel level) + { + lock (SyncRoot) + { + string role = level switch + { + ServiceAccessLevel.Engineer => "Engineer", + ServiceAccessLevel.Debug => "Debug", + _ => "Operator", + }; + _store?.Record(summary, role); + } + } + + public static void Shutdown() + { + lock (SyncRoot) + { + _store = null; + } + } + + private static void RotateIfRequired(string path, int maxFileSizeMb) + { + if (!File.Exists(path) || new FileInfo(path).Length < maxFileSizeMb * 1024L * 1024L) + { + return; + } + + string directory = Path.GetDirectoryName(path) ?? string.Empty; + string archive = $"settings-audit-{DateTimeOffset.UtcNow:yyyyMMdd-HHmmss-fff}.jsonl"; + File.Move(path, Path.Combine(directory, archive)); + } +} diff --git a/src/core/Logging/ConfigurationAuditJournal.cs.uid b/src/core/Logging/ConfigurationAuditJournal.cs.uid new file mode 100644 index 0000000..00ded43 --- /dev/null +++ b/src/core/Logging/ConfigurationAuditJournal.cs.uid @@ -0,0 +1 @@ +uid://dkt05jh3mjube diff --git a/src/core/Logging/ConfigurationAuditStore.cs b/src/core/Logging/ConfigurationAuditStore.cs new file mode 100644 index 0000000..f0184ba --- /dev/null +++ b/src/core/Logging/ConfigurationAuditStore.cs @@ -0,0 +1,49 @@ +using Exchanger.Core.Configuration; +using System; +using System.IO; +using System.Text.Encodings.Web; +using System.Text.Json; + +namespace Exchanger.Core.Logging; + +/// JSONL-аудит хранит только факт изменения секций, без старых и новых значений. +public sealed class ConfigurationAuditStore +{ + private static readonly JsonSerializerOptions JsonOptions = new() + { + Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, + }; + + private readonly string _path; + + public ConfigurationAuditStore(string path) + { + _path = Path.GetFullPath(path ?? throw new ArgumentNullException(nameof(path))); + } + + public void Record(SettingsChangeSummary summary, string role, DateTimeOffset? timestamp = null) + { + ArgumentNullException.ThrowIfNull(summary); + if (!summary.HasChanges) + { + return; + } + + Directory.CreateDirectory(Path.GetDirectoryName(_path) ?? string.Empty); + var entry = new + { + Timestamp = timestamp ?? DateTimeOffset.UtcNow, + Role = NormalizeRole(role), + Sections = summary.ChangedSections, + summary.RestartRequired, + }; + File.AppendAllText(_path, JsonSerializer.Serialize(entry, JsonOptions) + Environment.NewLine); + } + + private static string NormalizeRole(string role) => role switch + { + "Engineer" => "Engineer", + "Debug" => "Debug", + _ => "Operator", + }; +} diff --git a/src/core/Logging/ConfigurationAuditStore.cs.uid b/src/core/Logging/ConfigurationAuditStore.cs.uid new file mode 100644 index 0000000..c4438b8 --- /dev/null +++ b/src/core/Logging/ConfigurationAuditStore.cs.uid @@ -0,0 +1 @@ +uid://bdyi0g5tpn25b diff --git a/src/core/Logging/LogMaintenance.cs b/src/core/Logging/LogMaintenance.cs new file mode 100644 index 0000000..af35619 --- /dev/null +++ b/src/core/Logging/LogMaintenance.cs @@ -0,0 +1,92 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; + +namespace Exchanger.Core.Logging; + +public readonly record struct LogMaintenanceResult(int ExpiredDeleted, int QuotaDeleted, long RemainingBytes); + +/// Ограничивает общий объём только известных журналов Exchanger. +public static class LogMaintenance +{ + private static readonly string[] Patterns = ["exchanger*.log", "operations*.jsonl", "settings-audit*.jsonl"]; + + public static LogMaintenanceResult Prune( + string directory, + int retentionDays, + long maximumTotalBytes, + params string[] protectedPaths) + { + if (!Directory.Exists(directory)) + { + return new LogMaintenanceResult(0, 0, 0); + } + + string[] protectedFullPaths = (protectedPaths ?? []) + .Where(path => !string.IsNullOrWhiteSpace(path)) + .Select(Path.GetFullPath) + .ToArray(); + var files = Patterns + .SelectMany(pattern => Directory.EnumerateFiles(directory, pattern, SearchOption.TopDirectoryOnly)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .Select(path => new FileInfo(path)) + .ToList(); + DateTime threshold = DateTime.UtcNow.AddDays(-Math.Clamp(retentionDays, 1, 365)); + int expiredDeleted = 0; + int quotaDeleted = 0; + + foreach (FileInfo file in files.Where(file => file.LastWriteTimeUtc < threshold).ToArray()) + { + if (IsProtected(file.FullName, protectedFullPaths) || !TryDelete(file.FullName)) + { + continue; + } + + files.Remove(file); + expiredDeleted++; + } + + long total = files.Where(file => file.Exists).Sum(file => file.Length); + foreach (FileInfo file in files + .Where(file => !IsProtected(file.FullName, protectedFullPaths)) + .OrderBy(file => file.LastWriteTimeUtc)) + { + if (total <= Math.Max(1, maximumTotalBytes)) + { + break; + } + + long length = file.Exists ? file.Length : 0; + if (!TryDelete(file.FullName)) + { + continue; + } + + total = Math.Max(0, total - length); + quotaDeleted++; + } + + return new LogMaintenanceResult(expiredDeleted, quotaDeleted, total); + } + + private static bool IsProtected(string path, IEnumerable protectedPaths) => + protectedPaths.Contains(Path.GetFullPath(path), StringComparer.OrdinalIgnoreCase); + + private static bool TryDelete(string path) + { + try + { + File.Delete(path); + return true; + } + catch (IOException) + { + return false; + } + catch (UnauthorizedAccessException) + { + return false; + } + } +} diff --git a/src/core/Logging/LogMaintenance.cs.uid b/src/core/Logging/LogMaintenance.cs.uid new file mode 100644 index 0000000..1f5a09d --- /dev/null +++ b/src/core/Logging/LogMaintenance.cs.uid @@ -0,0 +1 @@ +uid://bxphkacqpuxss diff --git a/src/core/Logging/OperationJournal.cs b/src/core/Logging/OperationJournal.cs new file mode 100644 index 0000000..d50cdbd --- /dev/null +++ b/src/core/Logging/OperationJournal.cs @@ -0,0 +1,82 @@ +using Exchanger.Core.Configuration; +using Exchanger.Core.Session; +using Godot; +using System; +using System.Collections.Generic; +using System.IO; + +namespace Exchanger.Core.Logging; + +/// +/// Godot-композиция чистого OperationJournalStore. +/// +public static class OperationJournal +{ + private static readonly object SyncRoot = new(); + private static OperationJournalStore? _store; + + public static void Initialize(LoggingSettings settings) + { + lock (SyncRoot) + { + string directory = ProjectSettings.GlobalizePath("user://logs"); + Directory.CreateDirectory(directory); + string path = Path.Combine(directory, "operations.jsonl"); + _store = new OperationJournalStore(path); + IReadOnlyList unfinished = _store.RecoverUnfinishedOperations(); + foreach (OperationJournalEntry entry in unfinished) + { + AppLogger.Warning( + "Recovery", + $"operation_id={entry.OperationId} outcome=UnknownAfterRestart action=ManualStatusCheck"); + } + + // Сначала закрываем незавершённые операции, затем архивируем файл: + // иначе Started на границе ротации мог бы остаться без безопасного итога. + RotateIfRequired(path, settings.MaxFileSizeMb); + LogMaintenance.Prune( + directory, + settings.RetentionDays, + settings.MaxFileSizeMb * 10L * 1024L * 1024L, + Path.Combine(directory, "exchanger.log"), + path, + Path.Combine(directory, "settings-audit.jsonl")); + } + } + + public static void RecordStarted(SessionOperationSnapshot snapshot) + { + lock (SyncRoot) + { + _store?.RecordStarted(snapshot); + } + } + + public static void RecordFinished(SessionOperationSnapshot snapshot) + { + lock (SyncRoot) + { + _store?.RecordFinished(snapshot); + } + } + + public static void Shutdown() + { + lock (SyncRoot) + { + _store = null; + } + } + + private static void RotateIfRequired(string path, int maxFileSizeMb) + { + if (!File.Exists(path) || new FileInfo(path).Length < maxFileSizeMb * 1024L * 1024L) + { + return; + } + + string directory = Path.GetDirectoryName(path) ?? string.Empty; + string archive = $"operations-{DateTimeOffset.UtcNow:yyyyMMdd-HHmmss-fff}.jsonl"; + File.Move(path, Path.Combine(directory, archive)); + } +} diff --git a/src/core/Logging/OperationJournal.cs.uid b/src/core/Logging/OperationJournal.cs.uid new file mode 100644 index 0000000..508341f --- /dev/null +++ b/src/core/Logging/OperationJournal.cs.uid @@ -0,0 +1 @@ +uid://dk1o0iqogj64c diff --git a/src/core/Logging/OperationJournalStore.cs b/src/core/Logging/OperationJournalStore.cs new file mode 100644 index 0000000..fbed956 --- /dev/null +++ b/src/core/Logging/OperationJournalStore.cs @@ -0,0 +1,166 @@ +using Exchanger.Core.Session; +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Serialization; + +namespace Exchanger.Core.Logging; + +public enum OperationJournalEventType +{ + Started, + Finished, +} + +public sealed record OperationJournalEntry +{ + public DateTimeOffset TimestampUtc { get; init; } + + public OperationJournalEventType EventType { get; init; } + + public string OperationId { get; init; } = string.Empty; + + public PaymentMethod PaymentMethod { get; init; } + + public int AmountRubles { get; init; } + + public int BaseTokens { get; init; } + + public int BonusTokens { get; init; } + + public OperationOutcome Outcome { get; init; } + + public SessionErrorCode ErrorCode { get; init; } +} + +/// +/// Чистое JSONL-хранилище жизненного цикла операций. Не содержит карточных +/// реквизитов, сырых ответов оборудования или персональных данных. +/// +public sealed class OperationJournalStore +{ + private static readonly JsonSerializerOptions JsonOptions = new() + { + Converters = { new JsonStringEnumConverter() }, + }; + + private readonly object _syncRoot = new(); + private readonly string _path; + private readonly Func _utcNow; + + public OperationJournalStore(string path, Func? utcNow = null) + { + _path = string.IsNullOrWhiteSpace(path) + ? throw new ArgumentException("Путь журнала операций не задан.", nameof(path)) + : path; + _utcNow = utcNow ?? (() => DateTimeOffset.UtcNow); + } + + public void RecordStarted(SessionOperationSnapshot snapshot) => Append(snapshot, OperationJournalEventType.Started); + + public void RecordFinished(SessionOperationSnapshot snapshot) => Append(snapshot, OperationJournalEventType.Finished); + + public IReadOnlyList FindUnfinishedOperations() + { + lock (_syncRoot) + { + return FindUnfinishedUnsafe(); + } + } + + public IReadOnlyList RecoverUnfinishedOperations() + { + lock (_syncRoot) + { + IReadOnlyList unfinished = FindUnfinishedUnsafe(); + foreach (OperationJournalEntry entry in unfinished) + { + var snapshot = new SessionOperationSnapshot( + entry.OperationId, + entry.PaymentMethod, + entry.AmountRubles, + entry.BaseTokens, + entry.BonusTokens, + OperationOutcome.UnknownAfterRestart, + SessionErrorCode.None); + AppendUnsafe(snapshot, OperationJournalEventType.Finished); + } + + return unfinished; + } + } + + private void Append(SessionOperationSnapshot snapshot, OperationJournalEventType eventType) + { + if (string.IsNullOrWhiteSpace(snapshot.OperationId)) + { + throw new ArgumentException("Нельзя записать операцию без идентификатора.", nameof(snapshot)); + } + + lock (_syncRoot) + { + AppendUnsafe(snapshot, eventType); + } + } + + private void AppendUnsafe(SessionOperationSnapshot snapshot, OperationJournalEventType eventType) + { + string? directory = Path.GetDirectoryName(_path); + if (!string.IsNullOrWhiteSpace(directory)) + { + Directory.CreateDirectory(directory); + } + + var entry = new OperationJournalEntry + { + TimestampUtc = _utcNow().ToUniversalTime(), + EventType = eventType, + OperationId = snapshot.OperationId, + PaymentMethod = snapshot.PaymentMethod, + AmountRubles = snapshot.AmountRubles, + BaseTokens = snapshot.BaseTokens, + BonusTokens = snapshot.BonusTokens, + Outcome = snapshot.Outcome, + ErrorCode = snapshot.ErrorCode, + }; + File.AppendAllText(_path, JsonSerializer.Serialize(entry, JsonOptions) + Environment.NewLine); + } + + private IReadOnlyList FindUnfinishedUnsafe() + { + if (!File.Exists(_path)) + { + return Array.Empty(); + } + + var open = new Dictionary(StringComparer.Ordinal); + foreach (string line in File.ReadLines(_path)) + { + try + { + OperationJournalEntry? entry = JsonSerializer.Deserialize(line, JsonOptions); + if (entry is null || string.IsNullOrWhiteSpace(entry.OperationId)) + { + continue; + } + + if (entry.EventType == OperationJournalEventType.Started) + { + open[entry.OperationId] = entry; + } + else + { + open.Remove(entry.OperationId); + } + } + catch (JsonException) + { + // Повреждённая строка не мешает восстановить остальные записи. + } + } + + return open.Values.OrderBy(entry => entry.TimestampUtc).ToArray(); + } +} diff --git a/src/core/Logging/OperationJournalStore.cs.uid b/src/core/Logging/OperationJournalStore.cs.uid new file mode 100644 index 0000000..d72b5ec --- /dev/null +++ b/src/core/Logging/OperationJournalStore.cs.uid @@ -0,0 +1 @@ +uid://dr7mq2731srjr diff --git a/src/core/Navigation/ScreenId.cs b/src/core/Navigation/ScreenId.cs new file mode 100644 index 0000000..2ddbbe1 --- /dev/null +++ b/src/core/Navigation/ScreenId.cs @@ -0,0 +1,14 @@ +namespace Exchanger.Core.Navigation; + +public enum ScreenId +{ + Home, + CashPayment, + CardAmount, + CardCustomAmount, + CardTerminal, + Success, + Error, + ServiceAccess, + Settings, +} diff --git a/src/core/Navigation/ScreenId.cs.uid b/src/core/Navigation/ScreenId.cs.uid new file mode 100644 index 0000000..4f477b7 --- /dev/null +++ b/src/core/Navigation/ScreenId.cs.uid @@ -0,0 +1 @@ +uid://bof3l1w0tctux diff --git a/src/core/Navigation/ScreenManager.cs b/src/core/Navigation/ScreenManager.cs new file mode 100644 index 0000000..6beff2b --- /dev/null +++ b/src/core/Navigation/ScreenManager.cs @@ -0,0 +1,198 @@ +using Exchanger.Core.Logging; +using Exchanger.Core.Theming; +using Godot; +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Exchanger.Core.Navigation; + +/// +/// Владеет экземплярами экранов и выполняет защищённые UI-переходы. +/// Бизнес-логика оплаты здесь отсутствует. +/// +public partial class ScreenManager : Node +{ + [Signal] + public delegate void ScreenChangedEventHandler(string screenId); + + private const float FadeSeconds = 0.16f; + + private readonly Dictionary _screens = new(); + private Control? _currentScreen; + private Control? _inputBlocker; + private bool _transitionInProgress; + + public ScreenId? CurrentScreenId { get; private set; } + + public bool TransitionInProgress => _transitionInProgress; + + public void Initialize( + Control host, + IReadOnlyDictionary registry, + IReadOnlyDictionary? themeScenes = null, + IReadOnlyDictionary? themeBindingContracts = null) + { + ArgumentNullException.ThrowIfNull(host); + ArgumentNullException.ThrowIfNull(registry); + + foreach (Node child in host.GetChildren()) + { + host.RemoveChild(child); + child.QueueFree(); + } + + _screens.Clear(); + _currentScreen = null; + _inputBlocker = null; + CurrentScreenId = null; + _transitionInProgress = false; + + foreach ((ScreenId id, PackedScene packedScene) in registry) + { + Control screen = packedScene.Instantiate(); + if (themeScenes is not null + && themeScenes.TryGetValue(id, out PackedScene? themePackedScene)) + { + if (screen is not ThemeBindableScreen bindableScreen) + { + throw new InvalidOperationException( + $"Контроллер экрана {id} не поддерживает полносценовые темы."); + } + + Control themeView = themePackedScene.Instantiate(); + if (themeBindingContracts is null + || !themeBindingContracts.TryGetValue(id, out ThemeScreenBindingContract? bindingContract)) + { + themeView.Free(); + bindableScreen.UseBuiltInFallbackVisuals(); + AppLogger.Warning( + "Theme", + $"Для экрана {id} нет каталога биндингов; используется встроенный экран."); + } + else if (!bindableScreen.TryInstallThemeView( + themeView, + ThemeSceneContract.Screens.First(descriptor => descriptor.ScreenId == id), + bindingContract, + out int fallbackBindingCount, + out string fallbackFailure)) + { + themeView.Free(); + AppLogger.Warning( + "Theme", + $"Экран {id} не удалось дополнить встроенными элементами ({fallbackFailure}); " + + "используется встроенный экран целиком."); + } + else if (fallbackBindingCount > 0) + { + AppLogger.Info( + "Theme", + $"Экран {id}: восстановлена совместимость биндингов — {fallbackBindingCount}."); + } + } + + screen.Name = id.ToString(); + screen.SetAnchorsAndOffsetsPreset(Control.LayoutPreset.FullRect); + screen.Visible = false; + screen.ProcessMode = ProcessModeEnum.Disabled; + screen.MouseFilter = Control.MouseFilterEnum.Stop; + host.AddChild(screen); + if (screen is ThemeBindableScreen themedScreen && themedScreen.UsesExternalThemeScene) + { + ThemeManager themeManager = GetNode("/root/ThemeManager"); + themedScreen.BindThemeRuntime(themeManager); + } + _screens.Add(id, screen); + } + + _inputBlocker = new Control + { + Name = "TransitionInputBlocker", + MouseFilter = Control.MouseFilterEnum.Stop, + FocusMode = Control.FocusModeEnum.None, + Visible = false, + }; + _inputBlocker.SetAnchorsAndOffsetsPreset(Control.LayoutPreset.FullRect); + host.AddChild(_inputBlocker); + } + + public T GetScreen(ScreenId id) where T : Control + { + if (!_screens.TryGetValue(id, out Control? screen)) + { + throw new InvalidOperationException($"Экран {id} не зарегистрирован."); + } + + if (screen is not T typedScreen) + { + throw new InvalidOperationException($"Экран {id} имеет тип {screen.GetType().Name}, ожидался {typeof(T).Name}."); + } + + return typedScreen; + } + + public bool Show(ScreenId id, bool animate = true) + { + if (_transitionInProgress || CurrentScreenId == id) + { + return false; + } + + if (!_screens.TryGetValue(id, out Control? nextScreen)) + { + AppLogger.Error("Navigation", $"Попытка открыть незарегистрированный экран {id}."); + return false; + } + + if (_currentScreen is not null) + { + _currentScreen.Visible = false; + _currentScreen.ProcessMode = ProcessModeEnum.Disabled; + _currentScreen.Modulate = Colors.White; + } + + _currentScreen = nextScreen; + CurrentScreenId = id; + nextScreen.ProcessMode = ProcessModeEnum.Inherit; + nextScreen.Visible = true; + nextScreen.MoveToFront(); + + if (!animate || !IsInsideTree()) + { + nextScreen.Modulate = Colors.White; + EmitSignal(SignalName.ScreenChanged, id.ToString()); + return true; + } + + _transitionInProgress = true; + if (_inputBlocker is not null) + { + _inputBlocker.Visible = true; + _inputBlocker.MoveToFront(); + } + + nextScreen.Modulate = new Color(1f, 1f, 1f, 0f); + Tween tween = CreateTween(); + tween.SetPauseMode(Tween.TweenPauseMode.Process); + tween.TweenProperty(nextScreen, "modulate:a", 1f, FadeSeconds) + .SetTrans(Tween.TransitionType.Quad) + .SetEase(Tween.EaseType.Out); + tween.Finished += () => + { + if (GodotObject.IsInstanceValid(nextScreen)) + { + nextScreen.Modulate = Colors.White; + } + + _transitionInProgress = false; + if (GodotObject.IsInstanceValid(_inputBlocker)) + { + _inputBlocker.Visible = false; + } + }; + + EmitSignal(SignalName.ScreenChanged, id.ToString()); + AppLogger.Info("Navigation", $"Открыт экран {id}."); + return true; + } +} diff --git a/src/core/Navigation/ScreenManager.cs.uid b/src/core/Navigation/ScreenManager.cs.uid new file mode 100644 index 0000000..beabaf4 --- /dev/null +++ b/src/core/Navigation/ScreenManager.cs.uid @@ -0,0 +1 @@ +uid://0pmnvyj3qjiw diff --git a/src/core/Navigation/ScreenRegistry.cs b/src/core/Navigation/ScreenRegistry.cs new file mode 100644 index 0000000..5d39bcd --- /dev/null +++ b/src/core/Navigation/ScreenRegistry.cs @@ -0,0 +1,42 @@ +using Godot; +using System; +using System.Collections.Generic; + +namespace Exchanger.Core.Navigation; + +/// +/// Единственная точка сопоставления логических экранов и сцен. +/// +public static class ScreenRegistry +{ + private static readonly IReadOnlyDictionary ScenePaths = + new Dictionary + { + [ScreenId.Home] = "res://src/scenes/HomeScreen/HomeScreen.tscn", + [ScreenId.CashPayment] = "res://src/scenes/CashPaymentScreen/CashPaymentScreen.tscn", + [ScreenId.CardAmount] = "res://src/scenes/CardAmountScreen/CardAmountScreen.tscn", + [ScreenId.CardCustomAmount] = "res://src/scenes/CardCustomAmountScreen/CardCustomAmountScreen.tscn", + [ScreenId.CardTerminal] = "res://src/scenes/CardTerminalScreen/CardTerminalScreen.tscn", + [ScreenId.Success] = "res://src/scenes/SuccessScreen/SuccessScreen.tscn", + [ScreenId.Error] = "res://src/scenes/ErrorScreen/ErrorScreen.tscn", + [ScreenId.ServiceAccess] = "res://src/scenes/ServiceAccessScreen/ServiceAccessScreen.tscn", + [ScreenId.Settings] = "res://src/scenes/SettingsScreen/SettingsScreen.tscn", + }; + + public static IReadOnlyDictionary LoadDefault() + { + var result = new Dictionary(); + foreach ((ScreenId id, string path) in ScenePaths) + { + PackedScene? scene = ResourceLoader.Load(path); + if (scene is null) + { + throw new InvalidOperationException($"Не удалось загрузить экран {id}: {path}"); + } + + result.Add(id, scene); + } + + return result; + } +} diff --git a/src/core/Navigation/ScreenRegistry.cs.uid b/src/core/Navigation/ScreenRegistry.cs.uid new file mode 100644 index 0000000..3e1aa6f --- /dev/null +++ b/src/core/Navigation/ScreenRegistry.cs.uid @@ -0,0 +1 @@ +uid://creeyiwwqpaj1 diff --git a/src/core/Session/GodotMonotonicClock.cs b/src/core/Session/GodotMonotonicClock.cs new file mode 100644 index 0000000..c729b84 --- /dev/null +++ b/src/core/Session/GodotMonotonicClock.cs @@ -0,0 +1,8 @@ +using Godot; + +namespace Exchanger.Core.Session; + +internal sealed class GodotMonotonicClock : IMonotonicClock +{ + public ulong NowMilliseconds => Time.GetTicksMsec(); +} diff --git a/src/core/Session/GodotMonotonicClock.cs.uid b/src/core/Session/GodotMonotonicClock.cs.uid new file mode 100644 index 0000000..9f522d3 --- /dev/null +++ b/src/core/Session/GodotMonotonicClock.cs.uid @@ -0,0 +1 @@ +uid://daxl416pssjbf diff --git a/src/core/Session/IMonotonicClock.cs b/src/core/Session/IMonotonicClock.cs new file mode 100644 index 0000000..0b85295 --- /dev/null +++ b/src/core/Session/IMonotonicClock.cs @@ -0,0 +1,10 @@ +namespace Exchanger.Core.Session; + +/// +/// Монотонный источник времени. Абстракция позволяет тестировать таймауты +/// сессии без ожидания реальных секунд. +/// +public interface IMonotonicClock +{ + ulong NowMilliseconds { get; } +} diff --git a/src/core/Session/IMonotonicClock.cs.uid b/src/core/Session/IMonotonicClock.cs.uid new file mode 100644 index 0000000..86764c6 --- /dev/null +++ b/src/core/Session/IMonotonicClock.cs.uid @@ -0,0 +1 @@ +uid://dfwa5sqf7us7c diff --git a/src/core/Session/ISessionIdGenerator.cs b/src/core/Session/ISessionIdGenerator.cs new file mode 100644 index 0000000..f46042e --- /dev/null +++ b/src/core/Session/ISessionIdGenerator.cs @@ -0,0 +1,13 @@ +using System; + +namespace Exchanger.Core.Session; + +public interface ISessionIdGenerator +{ + string CreateId(); +} + +internal sealed class GuidSessionIdGenerator : ISessionIdGenerator +{ + public string CreateId() => Guid.NewGuid().ToString("N"); +} diff --git a/src/core/Session/ISessionIdGenerator.cs.uid b/src/core/Session/ISessionIdGenerator.cs.uid new file mode 100644 index 0000000..36e8ebc --- /dev/null +++ b/src/core/Session/ISessionIdGenerator.cs.uid @@ -0,0 +1 @@ +uid://cxfhl3k2ut1rl diff --git a/src/core/Session/PaymentMethod.cs b/src/core/Session/PaymentMethod.cs new file mode 100644 index 0000000..0e46328 --- /dev/null +++ b/src/core/Session/PaymentMethod.cs @@ -0,0 +1,8 @@ +namespace Exchanger.Core.Session; + +public enum PaymentMethod +{ + None, + Cash, + Card, +} diff --git a/src/core/Session/PaymentMethod.cs.uid b/src/core/Session/PaymentMethod.cs.uid new file mode 100644 index 0000000..205dc12 --- /dev/null +++ b/src/core/Session/PaymentMethod.cs.uid @@ -0,0 +1 @@ +uid://cxjp88e8ou62w diff --git a/src/core/Session/PricingPolicy.cs b/src/core/Session/PricingPolicy.cs new file mode 100644 index 0000000..0d65c67 --- /dev/null +++ b/src/core/Session/PricingPolicy.cs @@ -0,0 +1,51 @@ +using Exchanger.Core.Configuration; +using System; +using System.Linq; + +namespace Exchanger.Core.Session; + +public readonly record struct TokenCalculation(int BaseTokens, int BonusTokens) +{ + public int TotalTokens => BaseTokens + BonusTokens; +} + +/// +/// Чистые правила суммы и расчёта жетонов, не зависящие от Godot. +/// +public static class PricingPolicy +{ + public static bool IsAmountValid(PricingSettings pricing, int amountRubles) + { + ArgumentNullException.ThrowIfNull(pricing); + int step = Math.Max(1, pricing.CustomAmountStepRubles); + return amountRubles >= pricing.TokenPriceRubles + && amountRubles <= pricing.MaxCardAmountRubles + && amountRubles % step == 0; + } + + public static TokenCalculation Calculate(PricingSettings pricing, int amountRubles) + { + ArgumentNullException.ThrowIfNull(pricing); + int baseTokens = amountRubles / Math.Max(1, pricing.TokenPriceRubles); + int bonusTokens = (pricing.BonusRules ?? Array.Empty()) + .Where(rule => rule is not null && amountRubles >= rule.MinimumAmountRubles) + .Select(rule => rule.BonusTokens) + .DefaultIfEmpty(0) + .Max(); + return new TokenCalculation(baseTokens, bonusTokens); + } + + public static bool IsWithinTokenLimit( + PricingSettings pricing, + int amountRubles, + int? maximumAvailableTokens) + { + if (maximumAvailableTokens is null) + { + return true; + } + + return Calculate(pricing, amountRubles).TotalTokens + <= Math.Max(0, maximumAvailableTokens.Value); + } +} diff --git a/src/core/Session/PricingPolicy.cs.uid b/src/core/Session/PricingPolicy.cs.uid new file mode 100644 index 0000000..7c1bc21 --- /dev/null +++ b/src/core/Session/PricingPolicy.cs.uid @@ -0,0 +1 @@ +uid://dcgcbn7e8rjwv diff --git a/src/core/Session/SessionController.cs b/src/core/Session/SessionController.cs new file mode 100644 index 0000000..0cff8e9 --- /dev/null +++ b/src/core/Session/SessionController.cs @@ -0,0 +1,146 @@ +using Exchanger.Core.Configuration; +using Exchanger.Core.Logging; +using Exchanger.Hardware.Abstractions; +using Godot; +using System; + +namespace Exchanger.Core.Session; + +/// +/// Godot-адаптер чистого SessionFlow. Сохраняет публичный API сцены, +/// а обновление таймаутов привязывает к процессу движка. +/// +public partial class SessionController : Node +{ + private SessionFlow? _flow; + + public SessionState State => _flow?.State ?? SessionState.Home; + + public PaymentMethod PaymentMethod => _flow?.PaymentMethod ?? PaymentMethod.None; + + public string CurrentOperationId => _flow?.CurrentOperationId ?? string.Empty; + + public int SelectedAmountRubles => _flow?.SelectedAmountRubles ?? 0; + + public int CashBalanceRubles => _flow?.CashBalanceRubles ?? 0; + + public int BaseTokens => _flow?.BaseTokens ?? 0; + + public int BonusTokens => _flow?.BonusTokens ?? 0; + + public int TotalTokens => _flow?.TotalTokens ?? 0; + + public MachineStockLevel StockLevel => _flow?.StockLevel ?? MachineStockLevel.Unknown; + + public SessionErrorCode ErrorCode => _flow?.ErrorCode ?? SessionErrorCode.None; + + public SessionErrorAction ErrorAction => _flow?.ErrorAction ?? SessionErrorAction.ReturnHome; + + public string ErrorTitle => _flow?.ErrorTitle ?? string.Empty; + + public string ErrorMessage => _flow?.ErrorMessage ?? string.Empty; + + public event Action? StateChanged; + + public event Action? CashBalanceChanged; + + public event Action? StockChanged; + + public event Action? CountdownChanged; + + public void Configure( + AppSettings settings, + IMachineController machine, + int? maximumAvailableTokens = null) + { + DetachFlow(); + _flow = new SessionFlow( + settings, + machine, + new GodotMonotonicClock(), + maximumAvailableTokens: maximumAvailableTokens); + _flow.StateChanged += OnStateChanged; + _flow.CashBalanceChanged += OnCashBalanceChanged; + _flow.StockChanged += OnStockChanged; + _flow.CountdownChanged += OnCountdownChanged; + _flow.ActionRejected += OnActionRejected; + _flow.OperationStarted += OnOperationStarted; + _flow.OperationFinished += OnOperationFinished; + SetProcess(true); + } + + public override void _Process(double delta) => _flow?.Update(); + + public override void _ExitTree() => DetachFlow(); + + public void Shutdown() => DetachFlow(); + + public bool BeginCash() => _flow?.BeginCash() ?? false; + + public bool BeginCard() => _flow?.BeginCard() ?? false; + + public bool OpenCustomCardAmount() => _flow?.OpenCustomCardAmount() ?? false; + + public bool ReturnToCardAmounts() => _flow?.ReturnToCardAmounts() ?? false; + + public bool SelectCardAmount(int amountRubles) => _flow?.SelectCardAmount(amountRubles) ?? false; + + public bool ConfirmCashDispense() => _flow?.ConfirmCashDispense() ?? false; + + public void NotifyUserActivity() => _flow?.NotifyUserActivity(); + + public void Cancel() => _flow?.Cancel(); + + public void ReturnHome() => _flow?.ReturnHome(); + + public bool IsAmountValid(int amountRubles) => _flow?.IsAmountValid(amountRubles) ?? false; + + public void SetMaximumAvailableTokens(int? maximumAvailableTokens) => + _flow?.SetMaximumAvailableTokens(maximumAvailableTokens); + + private void OnStateChanged(SessionState state) + { + AppLogger.Info("Session", $"Состояние сессии: {state}."); + StateChanged?.Invoke(state); + } + + private void OnCashBalanceChanged(int balance) => CashBalanceChanged?.Invoke(balance); + + private void OnStockChanged(MachineStockLevel stockLevel) => StockChanged?.Invoke(stockLevel); + + private void OnCountdownChanged(int seconds) => CountdownChanged?.Invoke(seconds); + + private static void OnActionRejected(string message) => AppLogger.Warning("Session", message); + + private static void OnOperationStarted(SessionOperationSnapshot snapshot) + { + OperationJournal.RecordStarted(snapshot); + AppLogger.Info("Operation", $"event=start operation_id={snapshot.OperationId} payment={snapshot.PaymentMethod}"); + } + + private static void OnOperationFinished(SessionOperationSnapshot snapshot) + { + OperationJournal.RecordFinished(snapshot); + AppLogger.Info( + "Operation", + $"event=finish operation_id={snapshot.OperationId} payment={snapshot.PaymentMethod} amount={snapshot.AmountRubles} tokens={snapshot.BaseTokens + snapshot.BonusTokens} outcome={snapshot.Outcome} error={snapshot.ErrorCode}"); + } + + private void DetachFlow() + { + if (_flow is null) + { + return; + } + + _flow.Dispose(); + _flow.StateChanged -= OnStateChanged; + _flow.CashBalanceChanged -= OnCashBalanceChanged; + _flow.StockChanged -= OnStockChanged; + _flow.CountdownChanged -= OnCountdownChanged; + _flow.ActionRejected -= OnActionRejected; + _flow.OperationStarted -= OnOperationStarted; + _flow.OperationFinished -= OnOperationFinished; + _flow = null; + } +} diff --git a/src/core/Session/SessionController.cs.uid b/src/core/Session/SessionController.cs.uid new file mode 100644 index 0000000..316e044 --- /dev/null +++ b/src/core/Session/SessionController.cs.uid @@ -0,0 +1 @@ +uid://dwvtpapqjcjth diff --git a/src/core/Session/SessionError.cs b/src/core/Session/SessionError.cs new file mode 100644 index 0000000..92ab92b --- /dev/null +++ b/src/core/Session/SessionError.cs @@ -0,0 +1,44 @@ +namespace Exchanger.Core.Session; + +public enum SessionErrorCode +{ + None, + InvalidTokenCalculation, + InsufficientTokenInventory, + StockStatusUnknown, + PaymentDeclined, + PaymentTimeout, + DispenseFailed, + PartialDispense, + ConnectionLost, + DispenseStatusUnknown, +} + +public enum SessionErrorAction +{ + ReturnHome, + TryAnotherPaymentMethod, + ContactSupport, +} + +public readonly record struct SessionErrorDetails( + SessionErrorCode Code, + string Title, + string UserMessage, + SessionErrorAction RecommendedAction); + +public static class SessionErrorCatalog +{ + public static SessionErrorDetails Get(SessionErrorCode code) => code switch + { + SessionErrorCode.InvalidTokenCalculation => new(code, "ОШИБКА ВЫДАЧИ", "Не удалось рассчитать количество жетонов.", SessionErrorAction.ReturnHome), + SessionErrorCode.InsufficientTokenInventory => new(code, "НЕДОСТАТОЧНО ЖЕТОНОВ", "В автомате недостаточно жетонов для выбранной суммы. Выберите меньшую сумму.", SessionErrorAction.ReturnHome), + SessionErrorCode.StockStatusUnknown => new(code, "НЕТ ДАННЫХ О ЖЕТОНАХ", "Автомат не подтвердил состояние запаса. Обратитесь в техподдержку.", SessionErrorAction.ContactSupport), + SessionErrorCode.PaymentDeclined => new(code, "ОПЛАТА НЕ ПРОШЛА", "Банк отклонил операцию. Попробуйте другой способ оплаты.", SessionErrorAction.TryAnotherPaymentMethod), + SessionErrorCode.PaymentTimeout => new(code, "ВРЕМЯ ОПЛАТЫ ИСТЕКЛО", "Карта не была подтверждена вовремя.", SessionErrorAction.TryAnotherPaymentMethod), + SessionErrorCode.PartialDispense => new(code, "ВЫДАНЫ НЕ ВСЕ ЖЕТОНЫ", "Обратитесь в техподдержку и сообщите время операции.", SessionErrorAction.ContactSupport), + SessionErrorCode.ConnectionLost => new(code, "НЕТ СВЯЗИ С АВТОМАТОМ", "Операция остановлена. Попробуйте позже или обратитесь в техподдержку.", SessionErrorAction.ContactSupport), + SessionErrorCode.DispenseStatusUnknown => new(code, "СТАТУС ВЫДАЧИ НЕИЗВЕСТЕН", "Не повторяйте оплату. Обратитесь в техподдержку и сообщите время операции.", SessionErrorAction.ContactSupport), + _ => new(SessionErrorCode.DispenseFailed, "ОШИБКА ВЫДАЧИ", "Контроллер не подтвердил полную выдачу жетонов.", SessionErrorAction.ContactSupport), + }; +} diff --git a/src/core/Session/SessionError.cs.uid b/src/core/Session/SessionError.cs.uid new file mode 100644 index 0000000..a552b6d --- /dev/null +++ b/src/core/Session/SessionError.cs.uid @@ -0,0 +1 @@ +uid://dmq3ufatxah1d diff --git a/src/core/Session/SessionFlow.cs b/src/core/Session/SessionFlow.cs new file mode 100644 index 0000000..6d15b96 --- /dev/null +++ b/src/core/Session/SessionFlow.cs @@ -0,0 +1,581 @@ +using Exchanger.Core.Configuration; +using Exchanger.Hardware.Abstractions; +using System; + +namespace Exchanger.Core.Session; + +/// +/// Чистое, не зависящее от Godot ядро пользовательской операции. +/// Внутренний OperationId предназначен только для локальной диагностики и +/// не является идентификатором будущего протокола контроллера. +/// +public sealed class SessionFlow : IDisposable +{ + private readonly AppSettings _settings; + private readonly IMachineController _machine; + private readonly IMonotonicClock _clock; + private readonly ISessionIdGenerator _idGenerator; + private int? _maximumAvailableTokens; + private ulong _deadlineMs; + private int _lastCountdown = -1; + private bool _operationFinished; + private bool _disposed; + + public SessionFlow( + AppSettings settings, + IMachineController machine, + IMonotonicClock clock, + ISessionIdGenerator? idGenerator = null, + int? maximumAvailableTokens = null) + { + _settings = settings ?? throw new ArgumentNullException(nameof(settings)); + _machine = machine ?? throw new ArgumentNullException(nameof(machine)); + _clock = clock ?? throw new ArgumentNullException(nameof(clock)); + _idGenerator = idGenerator ?? new GuidSessionIdGenerator(); + SetMaximumAvailableTokens(maximumAvailableTokens); + + _machine.StockChanged += OnStockChanged; + _machine.CashBalanceChanged += OnCashBalanceChanged; + _machine.CardPaymentFinished += OnCardPaymentFinished; + _machine.DispenseFinished += OnDispenseFinished; + _machine.FaultOccurred += OnMachineFault; + StockLevel = machine.StockLevel; + } + + public SessionState State { get; private set; } = SessionState.Home; + + public PaymentMethod PaymentMethod { get; private set; } = PaymentMethod.None; + + public string CurrentOperationId { get; private set; } = string.Empty; + + public int SelectedAmountRubles { get; private set; } + + public int CashBalanceRubles { get; private set; } + + public int BaseTokens { get; private set; } + + public int BonusTokens { get; private set; } + + public int TotalTokens => BaseTokens + BonusTokens; + + public MachineStockLevel StockLevel { get; private set; } + + public SessionErrorCode ErrorCode { get; private set; } + + public SessionErrorAction ErrorAction { get; private set; } = SessionErrorAction.ReturnHome; + + public string ErrorTitle { get; private set; } = string.Empty; + + public string ErrorMessage { get; private set; } = string.Empty; + + public event Action? StateChanged; + + public event Action? CashBalanceChanged; + + public event Action? StockChanged; + + public event Action? CountdownChanged; + + public event Action? ActionRejected; + + public event Action? OperationStarted; + + public event Action? OperationFinished; + + public void Update() + { + if (_disposed || _deadlineMs == 0) + { + return; + } + + ulong now = _clock.NowMilliseconds; + int remaining = now >= _deadlineMs + ? 0 + : (int)Math.Ceiling((_deadlineMs - now) / 1000d); + + if (remaining != _lastCountdown) + { + _lastCountdown = remaining; + CountdownChanged?.Invoke(remaining); + } + + if (now >= _deadlineMs) + { + _deadlineMs = 0; + HandleTimeout(); + } + } + + public bool BeginCash() + { + if (!RequireState(SessionState.Home)) + { + return false; + } + + if (!_settings.Payments.CashEnabled) + { + return RejectAction("Оплата наличными отключена в настройках."); + } + + if (!CanStartPayment()) + { + return false; + } + + BeginOperation(PaymentMethod.Cash); + SetState(SessionState.CashAccepting); + SetDeadline(_settings.Timeouts.CashPaymentSeconds); + _machine.BeginCashAcceptance(); + return true; + } + + public bool BeginCard() + { + if (!RequireState(SessionState.Home)) + { + return false; + } + + if (!_settings.Payments.CardEnabled) + { + return RejectAction("Оплата картой отключена в настройках."); + } + + if (!CanStartPayment()) + { + return false; + } + + BeginOperation(PaymentMethod.Card); + SetState(SessionState.CardAmountSelection); + SetDeadline(_settings.Timeouts.SessionIdleSeconds); + return true; + } + + public bool OpenCustomCardAmount() + { + if (!RequireState(SessionState.CardAmountSelection)) + { + return false; + } + + SetState(SessionState.CardCustomAmount); + SetDeadline(_settings.Timeouts.SessionIdleSeconds); + return true; + } + + public bool ReturnToCardAmounts() + { + if (State == SessionState.CardTerminalWait) + { + _machine.CancelActiveOperation(); + } + else if (State != SessionState.CardCustomAmount) + { + return RejectAction( + $"Возврат к выбору суммы недоступен в состоянии {State}."); + } + + SetState(SessionState.CardAmountSelection); + SetDeadline(_settings.Timeouts.SessionIdleSeconds); + return true; + } + + public bool SelectCardAmount(int amountRubles) + { + if (State is not SessionState.CardAmountSelection and not SessionState.CardCustomAmount) + { + return RejectAction($"Выбор суммы недоступен в состоянии {State}."); + } + + if (!IsAmountValid(amountRubles)) + { + return RejectAction($"Сумма {amountRubles} ₽ не соответствует ограничениям конфигурации."); + } + + SelectedAmountRubles = amountRubles; + CalculateTokens(amountRubles); + if (!EnsureTokenInventoryLimit()) + { + return false; + } + + if (!EnsureStockBeforePayment()) + { + return false; + } + + SetState(SessionState.CardTerminalWait); + SetDeadline(_settings.Timeouts.CashlessPaymentSeconds); + _machine.BeginCardPayment(amountRubles); + return true; + } + + public bool ConfirmCashDispense() + { + if (!RequireState(SessionState.CashAccepting)) + { + return false; + } + + if (CashBalanceRubles < _settings.Pricing.TokenPriceRubles) + { + return RejectAction("Недостаточный наличный баланс для одного жетона."); + } + + SelectedAmountRubles = CashBalanceRubles; + CalculateTokens(SelectedAmountRubles); + if (!EnsureTokenInventoryLimit()) + { + _machine.EndCashAcceptance(); + return false; + } + + _machine.EndCashAcceptance(); + BeginDispense(); + return State == SessionState.Dispensing; + } + + public void NotifyUserActivity() + { + switch (State) + { + case SessionState.CashAccepting: + SetDeadline(_settings.Timeouts.CashPaymentSeconds); + break; + case SessionState.CardAmountSelection: + case SessionState.CardCustomAmount: + SetDeadline(_settings.Timeouts.SessionIdleSeconds); + break; + } + } + + public void Cancel() => CancelInternal(OperationOutcome.Cancelled); + + public void ReturnHome() + { + if (State == SessionState.Dispensing) + { + return; + } + + ResetToHome(); + } + + public bool IsAmountValid(int amountRubles) => PricingPolicy.IsAmountValid(_settings.Pricing, amountRubles); + + public void SetMaximumAvailableTokens(int? maximumAvailableTokens) => + _maximumAvailableTokens = maximumAvailableTokens is null + ? null + : Math.Max(0, maximumAvailableTokens.Value); + + public void Dispose() + { + if (_disposed) + { + return; + } + + CompleteOperation(OperationOutcome.Interrupted); + _machine.StockChanged -= OnStockChanged; + _machine.CashBalanceChanged -= OnCashBalanceChanged; + _machine.CardPaymentFinished -= OnCardPaymentFinished; + _machine.DispenseFinished -= OnDispenseFinished; + _machine.FaultOccurred -= OnMachineFault; + _disposed = true; + } + + private void BeginOperation(PaymentMethod paymentMethod) + { + ResetOperationData(); + PaymentMethod = paymentMethod; + CurrentOperationId = _idGenerator.CreateId(); + if (string.IsNullOrWhiteSpace(CurrentOperationId)) + { + throw new InvalidOperationException("Генератор вернул пустой идентификатор операции."); + } + + _operationFinished = false; + OperationStarted?.Invoke(CreateSnapshot(OperationOutcome.InProgress)); + } + + private bool EnsureStockBeforePayment() + { + if (StockLevel == MachineStockLevel.Unknown) + { + SetError(SessionErrorCode.StockStatusUnknown); + return false; + } + + return true; + } + + private bool CanStartPayment() + { + return StockLevel switch + { + MachineStockLevel.Unknown => RejectAction("Состояние запаса жетонов ещё не подтверждено."), + _ => true, + }; + } + + private void BeginDispense() + { + if (TotalTokens <= 0) + { + SetError(SessionErrorCode.InvalidTokenCalculation); + return; + } + + if (!EnsureStockBeforePayment()) + { + return; + } + + if (!EnsureTokenInventoryLimit()) + { + return; + } + + SetState(SessionState.Dispensing); + ClearDeadline(); + _machine.DispenseTokens(TotalTokens); + } + + private void CalculateTokens(int amountRubles) + { + TokenCalculation result = PricingPolicy.Calculate(_settings.Pricing, amountRubles); + BaseTokens = result.BaseTokens; + BonusTokens = result.BonusTokens; + } + + private bool EnsureTokenInventoryLimit() + { + if (_maximumAvailableTokens is null || TotalTokens <= _maximumAvailableTokens.Value) + { + return true; + } + + SetError(SessionErrorCode.InsufficientTokenInventory); + return false; + } + + private void OnStockChanged(MachineStockLevel stockLevel) + { + StockLevel = stockLevel; + StockChanged?.Invoke(StockLevel); + } + + private void OnCashBalanceChanged(int balanceRubles) + { + if (State != SessionState.CashAccepting) + { + return; + } + + CashBalanceRubles = Math.Max(0, balanceRubles); + CashBalanceChanged?.Invoke(CashBalanceRubles); + SetDeadline(_settings.Timeouts.CashPaymentSeconds); + } + + private void OnCardPaymentFinished(MachineCardResult result) + { + if (State != SessionState.CardTerminalWait) + { + return; + } + + switch (result) + { + case MachineCardResult.Approved: + BeginDispense(); + break; + case MachineCardResult.Declined: + SetError(SessionErrorCode.PaymentDeclined, SessionState.PaymentDeclined); + break; + case MachineCardResult.Cancelled: + CancelInternal(OperationOutcome.Cancelled); + break; + case MachineCardResult.Timeout: + SetError(SessionErrorCode.PaymentTimeout, SessionState.PaymentDeclined); + break; + } + } + + private void OnDispenseFinished(bool success, int dispensedTokens, string? error) + { + if (State != SessionState.Dispensing) + { + return; + } + + if (!success || dispensedTokens != TotalTokens) + { + SessionErrorCode code = dispensedTokens > 0 + ? SessionErrorCode.PartialDispense + : SessionErrorCode.DispenseFailed; + SetError(code); + return; + } + + SetState(SessionState.Completed); + CompleteOperation(OperationOutcome.Completed); + SetDeadline(_settings.Timeouts.SuccessSeconds); + } + + private void OnMachineFault(MachineFault fault) + { + if (State == SessionState.Home) + { + return; + } + + bool dispenseWasInProgress = State == SessionState.Dispensing; + _machine.CancelActiveOperation(); + _machine.EndCashAcceptance(); + SetError(dispenseWasInProgress + ? SessionErrorCode.DispenseStatusUnknown + : SessionErrorCode.ConnectionLost); + } + + private void HandleTimeout() + { + switch (State) + { + case SessionState.CardTerminalWait: + _machine.CancelActiveOperation(); + SetError(SessionErrorCode.PaymentTimeout, SessionState.PaymentDeclined); + break; + case SessionState.Completed: + case SessionState.PaymentDeclined: + case SessionState.Error: + ResetToHome(); + break; + case SessionState.CashAccepting: + case SessionState.CardAmountSelection: + case SessionState.CardCustomAmount: + CancelInternal(OperationOutcome.IdleTimeout); + break; + } + } + + private void SetError(SessionErrorCode code, SessionState state = SessionState.Error) + { + SessionErrorDetails details = SessionErrorCatalog.Get(code); + ErrorCode = details.Code; + ErrorAction = details.RecommendedAction; + ErrorTitle = details.Title; + ErrorMessage = details.UserMessage; + SetState(state); + CompleteOperation(ToOutcome(code)); + SetDeadline(_settings.Timeouts.SessionIdleSeconds); + } + + private void CancelInternal(OperationOutcome outcome) + { + if (State == SessionState.Home || State == SessionState.Dispensing) + { + return; + } + + _machine.CancelActiveOperation(); + _machine.EndCashAcceptance(); + CompleteOperation(outcome); + SetState(SessionState.Cancelled); + ResetToHome(); + } + + private void ResetToHome() + { + CompleteOperation(OperationOutcome.Cancelled); + _machine.CancelActiveOperation(); + _machine.EndCashAcceptance(); + ResetOperationData(); + PaymentMethod = PaymentMethod.None; + ClearDeadline(); + SetState(SessionState.Home); + } + + private void ResetOperationData() + { + CurrentOperationId = string.Empty; + SelectedAmountRubles = 0; + CashBalanceRubles = 0; + BaseTokens = 0; + BonusTokens = 0; + ErrorCode = SessionErrorCode.None; + ErrorAction = SessionErrorAction.ReturnHome; + ErrorTitle = string.Empty; + ErrorMessage = string.Empty; + _operationFinished = false; + } + + private void CompleteOperation(OperationOutcome outcome) + { + if (_operationFinished || string.IsNullOrWhiteSpace(CurrentOperationId)) + { + return; + } + + _operationFinished = true; + OperationFinished?.Invoke(CreateSnapshot(outcome)); + } + + private SessionOperationSnapshot CreateSnapshot(OperationOutcome outcome) => new( + CurrentOperationId, + PaymentMethod, + SelectedAmountRubles, + BaseTokens, + BonusTokens, + outcome, + ErrorCode); + + private static OperationOutcome ToOutcome(SessionErrorCode code) => code switch + { + SessionErrorCode.StockStatusUnknown => OperationOutcome.StockStatusUnknown, + SessionErrorCode.InsufficientTokenInventory => OperationOutcome.InsufficientTokenInventory, + SessionErrorCode.PaymentDeclined => OperationOutcome.PaymentDeclined, + SessionErrorCode.PaymentTimeout => OperationOutcome.PaymentTimeout, + SessionErrorCode.PartialDispense => OperationOutcome.PartialDispense, + SessionErrorCode.ConnectionLost => OperationOutcome.ConnectionLost, + SessionErrorCode.DispenseStatusUnknown => OperationOutcome.DispenseStatusUnknown, + _ => OperationOutcome.DispenseFailed, + }; + + private void SetState(SessionState state) + { + if (State == state) + { + return; + } + + State = state; + StateChanged?.Invoke(state); + } + + private bool RequireState(SessionState expected) + { + return State == expected || RejectAction($"Ожидалось состояние {expected}, текущее — {State}."); + } + + private bool RejectAction(string message) + { + ActionRejected?.Invoke(message); + return false; + } + + private void SetDeadline(int seconds) + { + _deadlineMs = _clock.NowMilliseconds + (ulong)Math.Max(1, seconds) * 1000UL; + _lastCountdown = -1; + } + + private void ClearDeadline() + { + _deadlineMs = 0; + _lastCountdown = -1; + CountdownChanged?.Invoke(0); + } +} diff --git a/src/core/Session/SessionFlow.cs.uid b/src/core/Session/SessionFlow.cs.uid new file mode 100644 index 0000000..35c9fca --- /dev/null +++ b/src/core/Session/SessionFlow.cs.uid @@ -0,0 +1 @@ +uid://bj1kfrp7agjvc diff --git a/src/core/Session/SessionOperation.cs b/src/core/Session/SessionOperation.cs new file mode 100644 index 0000000..c269242 --- /dev/null +++ b/src/core/Session/SessionOperation.cs @@ -0,0 +1,28 @@ +namespace Exchanger.Core.Session; + +public enum OperationOutcome +{ + InProgress, + Completed, + Cancelled, + IdleTimeout, + PaymentDeclined, + PaymentTimeout, + InsufficientTokenInventory, + StockStatusUnknown, + DispenseFailed, + PartialDispense, + ConnectionLost, + DispenseStatusUnknown, + Interrupted, + UnknownAfterRestart, +} + +public readonly record struct SessionOperationSnapshot( + string OperationId, + PaymentMethod PaymentMethod, + int AmountRubles, + int BaseTokens, + int BonusTokens, + OperationOutcome Outcome, + SessionErrorCode ErrorCode); diff --git a/src/core/Session/SessionOperation.cs.uid b/src/core/Session/SessionOperation.cs.uid new file mode 100644 index 0000000..de0d7d0 --- /dev/null +++ b/src/core/Session/SessionOperation.cs.uid @@ -0,0 +1 @@ +uid://bngu82fb7whvt diff --git a/src/core/Session/SessionState.cs b/src/core/Session/SessionState.cs new file mode 100644 index 0000000..cd0e978 --- /dev/null +++ b/src/core/Session/SessionState.cs @@ -0,0 +1,15 @@ +namespace Exchanger.Core.Session; + +public enum SessionState +{ + Home, + CashAccepting, + CardAmountSelection, + CardCustomAmount, + CardTerminalWait, + Dispensing, + Completed, + PaymentDeclined, + Error, + Cancelled, +} diff --git a/src/core/Session/SessionState.cs.uid b/src/core/Session/SessionState.cs.uid new file mode 100644 index 0000000..2a384f4 --- /dev/null +++ b/src/core/Session/SessionState.cs.uid @@ -0,0 +1 @@ +uid://dn6wh7pyaqiks diff --git a/src/core/Session/TokenCountFormatter.cs b/src/core/Session/TokenCountFormatter.cs new file mode 100644 index 0000000..d404c6e --- /dev/null +++ b/src/core/Session/TokenCountFormatter.cs @@ -0,0 +1,29 @@ +using System; + +namespace Exchanger.Core.Session; + +public static class TokenCountFormatter +{ + public static string Format(int count) + { + int safeCount = Math.Max(0, count); + int lastTwoDigits = safeCount % 100; + int lastDigit = safeCount % 10; + string noun = lastTwoDigits is >= 11 and <= 14 + ? "жетонов" + : lastDigit switch + { + 1 => "жетон", + 2 or 3 or 4 => "жетона", + _ => "жетонов", + }; + + return $"{safeCount} {noun}"; + } + + public static string FormatUpper(int count) => Format(count).ToUpperInvariant(); + + public static string FormatGiftUpper(int count) => count > 0 + ? $"+ {FormatUpper(count)}\nВ ПОДАРОК" + : "БЕЗ БОНУСА"; +} diff --git a/src/core/Session/TokenCountFormatter.cs.uid b/src/core/Session/TokenCountFormatter.cs.uid new file mode 100644 index 0000000..7e50be7 --- /dev/null +++ b/src/core/Session/TokenCountFormatter.cs.uid @@ -0,0 +1 @@ +uid://s3wape7cpcx1 diff --git a/src/core/TechnicalConfiguration/TechnicalSettings.cs b/src/core/TechnicalConfiguration/TechnicalSettings.cs new file mode 100644 index 0000000..e32e70a --- /dev/null +++ b/src/core/TechnicalConfiguration/TechnicalSettings.cs @@ -0,0 +1,373 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text.Json.Serialization; +using Exchanger.Core.Configuration; + +namespace Exchanger.Core.TechnicalConfiguration; + +/// +/// Монтажные параметры автомата. Они загружаются только из отдельного TOML-файла +/// и намеренно не входят в интерфейс настроек владельца. +/// +public sealed class TechnicalSettings +{ + public const int CurrentVersion = 1; + + public required int Version { get; init; } + + public required ControllerTechnicalSettings Controller { get; init; } + + public required HopperTechnicalSettings Hopper1 { get; init; } + + public required HopperTechnicalSettings Hopper2 { get; init; } + + public required ServiceTechnicalSettings Service { get; init; } + + public required PollingTechnicalSettings Polling { get; init; } + + public ThemeTechnicalSettings? Theme { get; init; } + + public void ApplyTo(HardwareSettings hardware) + { + ArgumentNullException.ThrowIfNull(hardware); + + hardware.UseMock = Controller.UseMock; + hardware.PortName = Controller.Port; + hardware.BaudRate = Controller.BaudRate; + hardware.ReconnectIntervalSeconds = Controller.ReconnectIntervalSeconds; + hardware.HandshakeTimeoutMilliseconds = Controller.HandshakeTimeoutMilliseconds; + hardware.FrameTimeoutMilliseconds = Controller.FrameTimeoutMilliseconds; + hardware.MaximumFrameLength = Controller.MaximumFrameLength; + hardware.CashlessKeepAliveSeconds = Controller.CashlessKeepAliveSeconds; + + hardware.ServiceButtonInputIndex = Service.ButtonInput; + hardware.ServiceButtonActiveHigh = Service.ButtonActiveHigh; + hardware.StockSensorInputIndex = Hopper1.Enabled ? Hopper1.StockSensorInput : -1; + hardware.StockLowWhenInputHigh = Hopper1.StockLowActiveHigh; + hardware.Hopper1DispenseSensorInputIndex = Hopper1.Enabled ? Hopper1.DispenseSensorInput : -1; + hardware.Hopper1DispenseSensorActiveHigh = Hopper1.DispensePulseActiveHigh; + hardware.Hopper2StockSensorInputIndex = Hopper2.Enabled ? Hopper2.StockSensorInput : -1; + hardware.Hopper2StockLowWhenInputHigh = Hopper2.StockLowActiveHigh; + hardware.Hopper2DispenseSensorInputIndex = Hopper2.Enabled ? Hopper2.DispenseSensorInput : -1; + hardware.Hopper2DispenseSensorActiveHigh = Hopper2.DispensePulseActiveHigh; + hardware.InputPollMilliseconds = Polling.InputPollMilliseconds; + hardware.StockPollSeconds = Polling.StockPollSeconds; + hardware.DispenseMode = ResolveDispenseMode(Hopper1.Enabled, Hopper2.Enabled); + } + + public void ApplyTo(ThemeSettings themes) + { + ArgumentNullException.ThrowIfNull(themes); + if (Theme is null) + { + return; + } + + themes.ExternalDlcEnabled = Theme.Enabled; + themes.ExternalDlcPath = Theme.BuildPackagePath(); + } + + public static string ResolveDispenseMode(bool hopper1Enabled, bool hopper2Enabled) => + (hopper1Enabled, hopper2Enabled) switch + { + (true, true) => "DualHopperAuto", + (true, false) => "Hopper1Auto", + (false, true) => "Hopper2Auto", + _ => "Unsupported", + }; + + public static (bool Hopper1Enabled, bool Hopper2Enabled) ResolveConfiguredHoppers( + string? dispenseMode) => + dispenseMode?.Trim() switch + { + string mode when mode.Equals("DualHopperAuto", StringComparison.OrdinalIgnoreCase) => (true, true), + string mode when mode.Equals("Hopper1Auto", StringComparison.OrdinalIgnoreCase) => (true, false), + string mode when mode.Equals("Hopper2Auto", StringComparison.OrdinalIgnoreCase) => (false, true), + _ => (false, false), + }; + + public IReadOnlyList Validate() => + Validate(SerialPortNameValidator.CurrentPlatform); + + public IReadOnlyList Validate(SerialPortPlatform serialPortPlatform) + { + var issues = new List(); + + if (Version != CurrentVersion) + { + issues.Add($"Поддерживается version = {CurrentVersion}, получено: {Version}."); + } + + if (!Controller.UseMock + && !SerialPortNameValidator.IsValid(Controller.Port, serialPortPlatform)) + { + issues.Add( + $"controller.port: {SerialPortNameValidator.GetExpectedFormatMessage(serialPortPlatform)}"); + } + + if (!HardwareSettingsValidator.AllowedBaudRates.Contains(Controller.BaudRate)) + { + issues.Add("controller.baud_rate содержит неподдерживаемую скорость порта."); + } + + ValidateRange(issues, "controller.reconnect_interval_seconds", Controller.ReconnectIntervalSeconds, 1, 60); + ValidateRange(issues, "controller.handshake_timeout_ms", Controller.HandshakeTimeoutMilliseconds, 1000, 60000); + ValidateRange(issues, "controller.frame_timeout_ms", Controller.FrameTimeoutMilliseconds, 10, 5000); + ValidateRange(issues, "controller.max_frame_length", Controller.MaximumFrameLength, 2, 65536); + ValidateRange(issues, "controller.cashless_keep_alive_seconds", Controller.CashlessKeepAliveSeconds, 30, 170); + ValidateInput(issues, "hopper_1.stock_sensor_input", Hopper1.StockSensorInput); + ValidateInput(issues, "hopper_1.dispense_sensor_input", Hopper1.DispenseSensorInput); + ValidateInput(issues, "hopper_2.stock_sensor_input", Hopper2.StockSensorInput); + ValidateInput(issues, "hopper_2.dispense_sensor_input", Hopper2.DispenseSensorInput); + ValidateInput(issues, "service.button_input", Service.ButtonInput); + ValidateRange(issues, "polling.input_poll_ms", Polling.InputPollMilliseconds, 50, 1000); + ValidateRange(issues, "polling.stock_poll_seconds", Polling.StockPollSeconds, 1, 60); + if (Theme is not null) + { + ValidateTheme(issues, Theme); + } + + var assignedInputs = new Dictionary(); + AddUniqueInput(issues, assignedInputs, Service.ButtonInput, "service.button_input"); + if (Hopper1.Enabled) + { + AddUniqueInput(issues, assignedInputs, Hopper1.StockSensorInput, "hopper_1.stock_sensor_input"); + AddUniqueInput(issues, assignedInputs, Hopper1.DispenseSensorInput, "hopper_1.dispense_sensor_input"); + } + + if (Hopper2.Enabled) + { + AddUniqueInput(issues, assignedInputs, Hopper2.StockSensorInput, "hopper_2.stock_sensor_input"); + AddUniqueInput(issues, assignedInputs, Hopper2.DispenseSensorInput, "hopper_2.dispense_sensor_input"); + } + + return issues; + } + + private static void ValidateTheme(List issues, ThemeTechnicalSettings theme) + { + string directory = theme.Directory.Trim(); + if (directory.Length == 0 + || directory.Length > ThemeSettingsValidator.MaximumDlcPathLength + || directory.Any(char.IsControl)) + { + issues.Add("theme.directory содержит недопустимый или слишком длинный путь."); + } + else + { + bool userPath = directory.StartsWith("user://", StringComparison.OrdinalIgnoreCase); + if (directory.StartsWith("res://", StringComparison.OrdinalIgnoreCase) + || (!userPath && !Path.IsPathFullyQualified(directory))) + { + issues.Add("theme.directory должен быть путём user:// или абсолютным локальным путём."); + } + + string normalized = directory.Replace('\\', '/'); + if (normalized.Split('/', StringSplitOptions.RemoveEmptyEntries).Any(segment => segment == "..")) + { + issues.Add("Переходы «..» в theme.directory запрещены."); + } + } + + string fileName = theme.FileName.Trim(); + if (fileName.Length == 0 + || fileName.Length > 128 + || fileName.Any(char.IsControl) + || fileName is "." or ".." + || fileName.IndexOfAny(Path.GetInvalidFileNameChars()) >= 0 + || fileName.IndexOfAny(new[] { '/', '\\', ':' }) >= 0) + { + issues.Add("theme.file_name содержит недопустимое имя файла."); + } + else if (Path.HasExtension(fileName)) + { + issues.Add("theme.file_name задаётся без расширения .pck."); + } + + if (directory.Length > 0 + && fileName.Length > 0 + && theme.BuildPackagePath().Length > ThemeSettingsValidator.MaximumDlcPathLength) + { + issues.Add($"Полный путь theme.directory + theme.file_name не должен превышать {ThemeSettingsValidator.MaximumDlcPathLength} символов."); + } + } + + private static void ValidateRange(List issues, string name, int value, int minimum, int maximum) + { + if (value < minimum || value > maximum) + { + issues.Add($"{name} должен находиться в диапазоне {minimum}…{maximum}."); + } + } + + private static void ValidateInput(List issues, string name, int value) + { + if (value is < -1 or > 25) + { + issues.Add($"{name} должен находиться в диапазоне -1…25."); + } + } + + private static void AddUniqueInput( + List issues, + IDictionary assignedInputs, + int input, + string name) + { + if (input < 0) + { + return; + } + + if (assignedInputs.TryGetValue(input, out string? existing)) + { + issues.Add($"IN{input} одновременно назначен параметрам {existing} и {name}."); + return; + } + + assignedInputs.Add(input, name); + } +} + +public sealed record ControllerTechnicalSettings( + bool UseMock, + string Port, + int BaudRate, + int ReconnectIntervalSeconds, + int HandshakeTimeoutMilliseconds, + int FrameTimeoutMilliseconds, + int MaximumFrameLength, + int CashlessKeepAliveSeconds); + +public sealed record HopperTechnicalSettings( + bool Enabled, + int StockSensorInput, + bool StockLowActiveHigh, + int DispenseSensorInput, + bool DispensePulseActiveHigh); + +public sealed record ServiceTechnicalSettings(bool ButtonActiveHigh, int ButtonInput); + +public sealed record PollingTechnicalSettings(int InputPollMilliseconds, int StockPollSeconds); + +public sealed record ThemeTechnicalSettings(bool Enabled, string Directory, string FileName) +{ + public string BuildPackagePath() + { + string directory = Directory.Trim(); + string packageFileName = $"{FileName.Trim()}.pck"; + if (directory.StartsWith("user://", StringComparison.OrdinalIgnoreCase)) + { + if (!directory.Equals("user://", StringComparison.OrdinalIgnoreCase)) + { + directory = directory.TrimEnd('/', '\\'); + } + + string separator = directory.EndsWith('/') ? string.Empty : "/"; + return $"{directory}{separator}{packageFileName}"; + } + + return Path.Combine(directory, packageFileName); + } +} + +internal sealed class TechnicalSettingsDocument +{ + [JsonPropertyName("version")] + public int? Version { get; set; } + + [JsonPropertyName("controller")] + public ControllerTechnicalSettingsDocument? Controller { get; set; } + + [JsonPropertyName("hopper_1")] + public HopperTechnicalSettingsDocument? Hopper1 { get; set; } + + [JsonPropertyName("hopper_2")] + public HopperTechnicalSettingsDocument? Hopper2 { get; set; } + + [JsonPropertyName("service")] + public ServiceTechnicalSettingsDocument? Service { get; set; } + + [JsonPropertyName("polling")] + public PollingTechnicalSettingsDocument? Polling { get; set; } + + [JsonPropertyName("theme")] + public ThemeTechnicalSettingsDocument? Theme { get; set; } +} + +internal sealed class ThemeTechnicalSettingsDocument +{ + [JsonPropertyName("enabled")] + public bool? Enabled { get; set; } + + [JsonPropertyName("directory")] + public string? Directory { get; set; } + + [JsonPropertyName("file_name")] + public string? FileName { get; set; } +} + +internal sealed class ControllerTechnicalSettingsDocument +{ + [JsonPropertyName("use_mock")] + public bool? UseMock { get; set; } + + [JsonPropertyName("port")] + public string? Port { get; set; } + + [JsonPropertyName("baud_rate")] + public int? BaudRate { get; set; } + + [JsonPropertyName("reconnect_interval_seconds")] + public int? ReconnectIntervalSeconds { get; set; } + + [JsonPropertyName("handshake_timeout_ms")] + public int? HandshakeTimeoutMilliseconds { get; set; } + + [JsonPropertyName("frame_timeout_ms")] + public int? FrameTimeoutMilliseconds { get; set; } + + [JsonPropertyName("max_frame_length")] + public int? MaximumFrameLength { get; set; } + + [JsonPropertyName("cashless_keep_alive_seconds")] + public int? CashlessKeepAliveSeconds { get; set; } +} + +internal sealed class HopperTechnicalSettingsDocument +{ + [JsonPropertyName("enabled")] + public bool? Enabled { get; set; } + + [JsonPropertyName("stock_sensor_input")] + public int? StockSensorInput { get; set; } + + [JsonPropertyName("stock_low_active_high")] + public bool? StockLowActiveHigh { get; set; } + + [JsonPropertyName("dispense_sensor_input")] + public int? DispenseSensorInput { get; set; } + + [JsonPropertyName("dispense_pulse_active_high")] + public bool? DispensePulseActiveHigh { get; set; } +} + +internal sealed class ServiceTechnicalSettingsDocument +{ + [JsonPropertyName("button_input")] + public int? ButtonInput { get; set; } + + [JsonPropertyName("button_active_high")] + public bool? ButtonActiveHigh { get; set; } +} + +internal sealed class PollingTechnicalSettingsDocument +{ + [JsonPropertyName("input_poll_ms")] + public int? InputPollMilliseconds { get; set; } + + [JsonPropertyName("stock_poll_seconds")] + public int? StockPollSeconds { get; set; } +} diff --git a/src/core/TechnicalConfiguration/TechnicalSettings.cs.uid b/src/core/TechnicalConfiguration/TechnicalSettings.cs.uid new file mode 100644 index 0000000..d008b97 --- /dev/null +++ b/src/core/TechnicalConfiguration/TechnicalSettings.cs.uid @@ -0,0 +1 @@ +uid://c5e1gn885lsah diff --git a/src/core/TechnicalConfiguration/TechnicalSettingsService.cs b/src/core/TechnicalConfiguration/TechnicalSettingsService.cs new file mode 100644 index 0000000..0efca55 --- /dev/null +++ b/src/core/TechnicalConfiguration/TechnicalSettingsService.cs @@ -0,0 +1,278 @@ +using System; +using System.Collections.Generic; +using System.IO; +using Tomlyn; + +namespace Exchanger.Core.TechnicalConfiguration; + +/// +/// Создаёт пользовательскую копию технического TOML и загружает её целиком. +/// Повреждённый пользовательский файл не применяется частично: используется +/// безопасный встроенный профиль, а исходный файл остаётся для диагностики. +/// +public sealed class TechnicalSettingsService +{ + private readonly string _defaultPath; + private readonly string _userPath; + private readonly Action? _warningSink; + + public TechnicalSettingsService(string defaultPath, string userPath, Action? warningSink = null) + { + _defaultPath = string.IsNullOrWhiteSpace(defaultPath) + ? throw new ArgumentException("Не указан путь к встроенной технической конфигурации.", nameof(defaultPath)) + : defaultPath; + _userPath = string.IsNullOrWhiteSpace(userPath) + ? throw new ArgumentException("Не указан путь к пользовательской технической конфигурации.", nameof(userPath)) + : userPath; + _warningSink = warningSink; + } + + public string UserPath => _userPath; + + public TechnicalSettings Load() + { + EnsureUserCopy(); + + if (File.Exists(_userPath)) + { + if (TryLoadFile(_userPath, out TechnicalSettings? userSettings, out string userError)) + { + return userSettings!; + } + + _warningSink?.Invoke( + $"Техническая конфигурация не применена: {userError} Используется встроенный безопасный профиль."); + } + + if (TryLoadFile(_defaultPath, out TechnicalSettings? defaultSettings, out string defaultError)) + { + return defaultSettings!; + } + + throw new InvalidDataException($"Встроенная техническая конфигурация повреждена: {defaultError}"); + } + + public static bool TryParse( + string content, + out TechnicalSettings? settings, + out IReadOnlyList issues) + { + ArgumentNullException.ThrowIfNull(content); + settings = null; + var resultIssues = new List(); + + TechnicalSettingsDocument? document; + try + { + document = TomlSerializer.Deserialize(content); + } + catch (Exception exception) + { + resultIssues.Add($"TOML не разобран: {exception.Message}"); + issues = resultIssues; + return false; + } + + if (document is null) + { + resultIssues.Add("TOML не содержит конфигурацию."); + issues = resultIssues; + return false; + } + + TechnicalSettings? parsed = Build(document, resultIssues); + if (parsed is not null) + { + resultIssues.AddRange(parsed.Validate()); + } + + if (resultIssues.Count > 0) + { + issues = resultIssues; + return false; + } + + settings = parsed; + issues = resultIssues; + return true; + } + + private void EnsureUserCopy() + { + if (File.Exists(_userPath)) + { + return; + } + + try + { + string? directory = Path.GetDirectoryName(_userPath); + if (!string.IsNullOrWhiteSpace(directory)) + { + Directory.CreateDirectory(directory); + } + + File.Copy(_defaultPath, _userPath, overwrite: false); + } + catch (IOException) when (File.Exists(_userPath)) + { + // Другой экземпляр успел создать тот же файл. + } + catch (Exception exception) when (exception is IOException or UnauthorizedAccessException) + { + _warningSink?.Invoke( + "Не удалось создать пользовательскую техническую конфигурацию: нет доступа к каталогу."); + } + } + + private static bool TryLoadFile( + string path, + out TechnicalSettings? settings, + out string error) + { + try + { + string content = File.ReadAllText(path); + if (TryParse(content, out settings, out IReadOnlyList issues)) + { + error = string.Empty; + return true; + } + + error = string.Join(" ", issues); + return false; + } + catch (Exception exception) when (exception is IOException or UnauthorizedAccessException) + { + settings = null; + error = "файл недоступен для чтения."; + return false; + } + } + + private static TechnicalSettings? Build(TechnicalSettingsDocument document, List issues) + { + ControllerTechnicalSettingsDocument? controller = RequireSection(document.Controller, "[controller]", issues); + HopperTechnicalSettingsDocument? hopper1 = RequireSection(document.Hopper1, "[hopper_1]", issues); + HopperTechnicalSettingsDocument? hopper2 = RequireSection(document.Hopper2, "[hopper_2]", issues); + ServiceTechnicalSettingsDocument? service = RequireSection(document.Service, "[service]", issues); + PollingTechnicalSettingsDocument? polling = RequireSection(document.Polling, "[polling]", issues); + ThemeTechnicalSettings? parsedTheme = document.Theme is null + ? null + : BuildTheme(document.Theme, issues); + + int? version = RequireValue(document.Version, "version", issues); + if (controller is null || hopper1 is null || hopper2 is null || service is null || polling is null) + { + return null; + } + + bool? useMock = RequireValue(controller.UseMock, "controller.use_mock", issues); + string? port = RequireText(controller.Port, "controller.port", issues); + int? baudRate = RequireValue(controller.BaudRate, "controller.baud_rate", issues); + int? reconnect = RequireValue(controller.ReconnectIntervalSeconds, "controller.reconnect_interval_seconds", issues); + int? handshake = RequireValue(controller.HandshakeTimeoutMilliseconds, "controller.handshake_timeout_ms", issues); + int? frameTimeout = RequireValue(controller.FrameTimeoutMilliseconds, "controller.frame_timeout_ms", issues); + int? maxFrameLength = RequireValue(controller.MaximumFrameLength, "controller.max_frame_length", issues); + int? keepAlive = RequireValue(controller.CashlessKeepAliveSeconds, "controller.cashless_keep_alive_seconds", issues); + HopperTechnicalSettings? parsedHopper1 = BuildHopper(hopper1, "hopper_1", issues); + HopperTechnicalSettings? parsedHopper2 = BuildHopper(hopper2, "hopper_2", issues); + int? serviceInput = RequireValue(service.ButtonInput, "service.button_input", issues); + bool? serviceActiveHigh = RequireValue(service.ButtonActiveHigh, "service.button_active_high", issues); + int? inputPoll = RequireValue(polling.InputPollMilliseconds, "polling.input_poll_ms", issues); + int? stockPoll = RequireValue(polling.StockPollSeconds, "polling.stock_poll_seconds", issues); + + if (issues.Count > 0) + { + return null; + } + + return new TechnicalSettings + { + Version = version!.Value, + Controller = new ControllerTechnicalSettings( + useMock!.Value, + port!.Trim(), + baudRate!.Value, + reconnect!.Value, + handshake!.Value, + frameTimeout!.Value, + maxFrameLength!.Value, + keepAlive!.Value), + Hopper1 = parsedHopper1!, + Hopper2 = parsedHopper2!, + Service = new ServiceTechnicalSettings(serviceActiveHigh!.Value, serviceInput!.Value), + Polling = new PollingTechnicalSettings(inputPoll!.Value, stockPoll!.Value), + Theme = parsedTheme, + }; + } + + private static ThemeTechnicalSettings? BuildTheme( + ThemeTechnicalSettingsDocument document, + List issues) + { + bool? enabled = RequireValue(document.Enabled, "theme.enabled", issues); + string? directory = RequireText(document.Directory, "theme.directory", issues); + string? fileName = RequireText(document.FileName, "theme.file_name", issues); + if (enabled is null || directory is null || fileName is null) + { + return null; + } + + return new ThemeTechnicalSettings(enabled.Value, directory.Trim(), fileName.Trim()); + } + + private static HopperTechnicalSettings? BuildHopper( + HopperTechnicalSettingsDocument document, + string prefix, + List issues) + { + bool? enabled = RequireValue(document.Enabled, $"{prefix}.enabled", issues); + int? stockInput = RequireValue(document.StockSensorInput, $"{prefix}.stock_sensor_input", issues); + bool? stockActiveHigh = RequireValue(document.StockLowActiveHigh, $"{prefix}.stock_low_active_high", issues); + int? dispenseInput = RequireValue(document.DispenseSensorInput, $"{prefix}.dispense_sensor_input", issues); + bool? dispenseActiveHigh = RequireValue(document.DispensePulseActiveHigh, $"{prefix}.dispense_pulse_active_high", issues); + if (enabled is null || stockInput is null || stockActiveHigh is null || dispenseInput is null || dispenseActiveHigh is null) + { + return null; + } + + return new HopperTechnicalSettings( + enabled.Value, + stockInput.Value, + stockActiveHigh.Value, + dispenseInput.Value, + dispenseActiveHigh.Value); + } + + private static T? RequireValue(T? value, string name, List issues) where T : struct + { + if (value is null) + { + issues.Add($"Не задан параметр {name}."); + } + + return value; + } + + private static T? RequireSection(T? value, string name, List issues) where T : class + { + if (value is null) + { + issues.Add($"Не задан раздел {name}."); + } + + return value; + } + + private static string? RequireText(string? value, string name, List issues) + { + if (string.IsNullOrWhiteSpace(value)) + { + issues.Add($"Не задан параметр {name}."); + return null; + } + + return value; + } +} diff --git a/src/core/TechnicalConfiguration/TechnicalSettingsService.cs.uid b/src/core/TechnicalConfiguration/TechnicalSettingsService.cs.uid new file mode 100644 index 0000000..c1f0f7f --- /dev/null +++ b/src/core/TechnicalConfiguration/TechnicalSettingsService.cs.uid @@ -0,0 +1 @@ +uid://b5aqral3d32de diff --git a/src/core/ThemeManager/BuiltInFallbackTheme.cs b/src/core/ThemeManager/BuiltInFallbackTheme.cs new file mode 100644 index 0000000..f1f67ff --- /dev/null +++ b/src/core/ThemeManager/BuiltInFallbackTheme.cs @@ -0,0 +1,103 @@ +using Godot; + +namespace Exchanger.Core.Theming; + +/// +/// Минимальная аварийно-устойчивая тема приложения. Это не редактируемый +/// theme-проект: все разрабатываемые визуальные темы живут во внешнем DLC. +/// +public static class BuiltInFallbackTheme +{ + public static VendingThemeDefinition Create() + { + var uiTheme = new Theme + { + DefaultFontSize = 28, + }; + ThemeSemanticTypes.RegisterFallbackBaseTypes(uiTheme); + + StyleBoxFlat buttonNormal = CreateButtonStyle( + new Color("9ee04d"), + new Color("d1ff85"), + topMargin: 18, + bottomMargin: 18); + StyleBoxFlat buttonHover = CreateButtonStyle( + new Color("b8f566"), + new Color("e5ffad"), + topMargin: 18, + bottomMargin: 18, + borderWidth: 3); + StyleBoxFlat buttonPressed = CreateButtonStyle( + new Color("73b833"), + new Color("c2f56b"), + topMargin: 20, + bottomMargin: 16, + borderWidth: 3); + var panel = new StyleBoxFlat + { + BgColor = new Color(0.025f, 0.075f, 0.16f, 0.94f), + BorderColor = new Color(0.62f, 0.88f, 0.3f, 0.82f), + BorderWidthLeft = 2, + BorderWidthTop = 2, + BorderWidthRight = 2, + BorderWidthBottom = 2, + CornerRadiusTopLeft = 32, + CornerRadiusTopRight = 32, + CornerRadiusBottomRight = 32, + CornerRadiusBottomLeft = 32, + ShadowColor = new Color(0, 0.01f, 0.04f, 0.55f), + ShadowSize = 22, + }; + + uiTheme.SetColor("font_color", "Button", new Color(0.005f, 0.03f, 0.08f)); + uiTheme.SetColor("font_hover_color", "Button", new Color(0, 0.015f, 0.05f)); + uiTheme.SetColor("font_pressed_color", "Button", new Color(0.94f, 1, 0.86f)); + uiTheme.SetColor("font_outline_color", "Button", Colors.Transparent); + uiTheme.SetConstant("outline_size", "Button", 0); + uiTheme.SetFontSize("font_size", "Button", 32); + uiTheme.SetStylebox("normal", "Button", buttonNormal); + uiTheme.SetStylebox("hover", "Button", buttonHover); + uiTheme.SetStylebox("pressed", "Button", buttonPressed); + uiTheme.SetStylebox("focus", "Button", buttonHover); + uiTheme.SetColor("font_color", "Label", Colors.White); + uiTheme.SetColor("font_shadow_color", "Label", Colors.Transparent); + uiTheme.SetConstant("shadow_offset_x", "Label", 0); + uiTheme.SetConstant("shadow_offset_y", "Label", 0); + uiTheme.SetFontSize("font_size", "Label", 28); + uiTheme.SetStylebox("panel", "PanelContainer", panel); + + return new VendingThemeDefinition + { + ThemeId = "default", + DisplayName = "Встроенная fallback-тема", + UiTheme = uiTheme, + FallbackColor = new Color(0.012f, 0.035f, 0.105f), + }; + } + + private static StyleBoxFlat CreateButtonStyle( + Color background, + Color border, + float topMargin, + float bottomMargin, + int borderWidth = 2) + { + return new StyleBoxFlat + { + ContentMarginLeft = 30, + ContentMarginTop = topMargin, + ContentMarginRight = 30, + ContentMarginBottom = bottomMargin, + BgColor = background, + BorderColor = border, + BorderWidthLeft = borderWidth, + BorderWidthTop = borderWidth, + BorderWidthRight = borderWidth, + BorderWidthBottom = borderWidth, + CornerRadiusTopLeft = 22, + CornerRadiusTopRight = 22, + CornerRadiusBottomRight = 22, + CornerRadiusBottomLeft = 22, + }; + } +} diff --git a/src/core/ThemeManager/BuiltInFallbackTheme.cs.uid b/src/core/ThemeManager/BuiltInFallbackTheme.cs.uid new file mode 100644 index 0000000..ad3e110 --- /dev/null +++ b/src/core/ThemeManager/BuiltInFallbackTheme.cs.uid @@ -0,0 +1 @@ +uid://cteisoydtp14i diff --git a/src/core/ThemeManager/InteractivePetContract.cs b/src/core/ThemeManager/InteractivePetContract.cs new file mode 100644 index 0000000..a7987eb --- /dev/null +++ b/src/core/ThemeManager/InteractivePetContract.cs @@ -0,0 +1,104 @@ +using Godot; + +namespace Exchanger.Core.Theming; + +public static class InteractivePetContract +{ + public const int NavigationVersion = 1; + + public static readonly StringName SurfaceMetadata = "exchanger_pet_surface"; + public static readonly StringName NavigationRootMetadata = "exchanger_pet_navigation_root"; + public static readonly StringName NavigationVersionMetadata = "exchanger_pet_navigation_version"; + public static readonly StringName DefaultSurfaceMetadata = "exchanger_pet_default_surface_id"; + public static readonly StringName RoamingBoundsMetadata = "exchanger_pet_roaming_bounds"; + public static readonly StringName SurfaceIdMetadata = "exchanger_pet_surface_id"; + public static readonly StringName SurfaceFromXMetadata = "exchanger_pet_surface_from_x"; + public static readonly StringName SurfaceToXMetadata = "exchanger_pet_surface_to_x"; + public static readonly StringName SurfaceYMetadata = "exchanger_pet_surface_y"; + public static readonly StringName SurfaceSitPointsMetadata = "exchanger_pet_surface_sit_points"; + public static readonly StringName SurfaceVisibilityBindingMetadata = + "exchanger_pet_surface_visibility_binding_id"; + public static readonly StringName ClimbEdgeMetadata = "exchanger_pet_climb_edge"; + public static readonly StringName ClimbEdgeIdMetadata = "exchanger_pet_climb_edge_id"; + public static readonly StringName ClimbFromSurfaceMetadata = "exchanger_pet_climb_from_surface_id"; + public static readonly StringName ClimbToSurfaceMetadata = "exchanger_pet_climb_to_surface_id"; + public static readonly StringName ClimbXMetadata = "exchanger_pet_climb_x"; + public static readonly StringName ClimbFromYMetadata = "exchanger_pet_climb_from_y"; + public static readonly StringName ClimbToYMetadata = "exchanger_pet_climb_to_y"; + public static readonly StringName ClimbSideMetadata = "exchanger_pet_climb_side"; + public static readonly StringName AnimationStartedSignal = "pet_animation_started"; + public static readonly StringName AnimationCompletedSignal = "pet_animation_completed"; + public static readonly StringName GetActionAnimationMethod = "get_pet_action_animation"; + public static readonly StringName GetFramesPerSecondMethod = "get_pet_animation_frames_per_second"; + public static readonly StringName GetPreviewSizeMethod = "get_pet_preview_size"; + public static readonly StringName GetRuntimeScaleMethod = "get_pet_runtime_scale"; + public static readonly StringName GetWalkSpeedMethod = "get_pet_walk_speed"; + public static readonly StringName GetClimbSpeedMethod = "get_pet_climb_speed"; + public static readonly StringName GetHitSizeMethod = "get_pet_hit_size"; + public static readonly StringName GetGroundOffsetMethod = "get_pet_ground_offset"; + public static readonly StringName HasCompositeActionMethod = "has_pet_composite_action"; + public static readonly StringName StartCompositeActionMethod = "start_pet_composite_action"; + public static readonly StringName CancelCompositeActionMethod = "cancel_pet_composite_action"; + public static readonly StringName CompositeActionStartedSignal = "pet_composite_action_started"; + public static readonly StringName CompositeActionFinishedSignal = "pet_composite_action_finished"; + + public static readonly StringName[] RequiredMethods = + { + "get_pet_animation_names", + "get_pet_animation_frame_count", + "has_pet_animation", + "play_pet_animation", + "pause_pet_animation", + "stop_pet_animation", + "get_current_pet_animation", + "get_current_pet_frame", + }; + + public static readonly StringName[] CompositeActionMethods = + { + HasCompositeActionMethod, + StartCompositeActionMethod, + CancelCompositeActionMethod, + }; + + public static bool IsCompatible(PackedScene scene) + { + Node instance = scene.Instantiate(); + try + { + if (instance is not Node2D pet) + { + return false; + } + + foreach (StringName method in RequiredMethods) + { + if (!pet.HasMethod(method)) + { + return false; + } + } + + return pet.HasSignal(AnimationStartedSignal) + && pet.HasSignal(AnimationCompletedSignal); + } + finally + { + instance.Free(); + } + } + + public static bool HasCompositeActionContract(Node pet) + { + foreach (StringName method in CompositeActionMethods) + { + if (!pet.HasMethod(method)) + { + return false; + } + } + + return pet.HasSignal(CompositeActionStartedSignal) + && pet.HasSignal(CompositeActionFinishedSignal); + } +} diff --git a/src/core/ThemeManager/InteractivePetContract.cs.uid b/src/core/ThemeManager/InteractivePetContract.cs.uid new file mode 100644 index 0000000..5173ab2 --- /dev/null +++ b/src/core/ThemeManager/InteractivePetContract.cs.uid @@ -0,0 +1 @@ +uid://cu4u32w3msr7r diff --git a/src/core/ThemeManager/ThemeBindableScreen.cs b/src/core/ThemeManager/ThemeBindableScreen.cs new file mode 100644 index 0000000..5955061 --- /dev/null +++ b/src/core/ThemeManager/ThemeBindableScreen.cs @@ -0,0 +1,208 @@ +using Godot; +using System; +using System.Collections.Generic; + +namespace Exchanger.Core.Theming; + +/// +/// App-owned контроллер экрана. DLC заменяет визуальный корень и может выполнять +/// доверенный GDScript, а обязательная логика оплаты, навигации и оборудования +/// остаётся подключённой C#-контроллером через binding-id. +/// +public abstract partial class ThemeBindableScreen : Control +{ + private Control? _externalThemeView; + private IReadOnlyDictionary? _externalBindings; + private CanvasItem? _selfContainedDecoration; + private ThemeManager? _runtimeThemeManager; + + protected abstract string ThemeScreenKey { get; } + + public bool UsesExternalThemeScene => _externalThemeView is not null; + + public bool UsesBuiltInFallbackVisuals { get; private set; } + + internal void UseBuiltInFallbackVisuals() => UsesBuiltInFallbackVisuals = true; + + /// + /// Самодостаточная сцена владеет своим визуальным деревом. Host меняет только + /// функциональные значения и подключает сигналы по binding-id. Исключение — + /// отсутствующий обязательный binding: для обратной совместимости он дополняется + /// готовым узлом встроенного экрана по закреплённому fallback-path. + /// + public bool UsesSelfContainedThemeScene => + _externalThemeView is not null + && _externalThemeView.HasMeta(ThemeSceneContract.SelfContainedVisualsMetadata) + && _externalThemeView.GetMeta(ThemeSceneContract.SelfContainedVisualsMetadata).VariantType + == Variant.Type.Bool + && _externalThemeView.GetMeta(ThemeSceneContract.SelfContainedVisualsMetadata).AsBool(); + + public virtual bool TryInstallThemeView( + Control themeView, + ThemeScreenDescriptor descriptor, + ThemeScreenBindingContract bindingContract, + out int fallbackBindingCount, + out string failure) + { + ArgumentNullException.ThrowIfNull(themeView); + ArgumentNullException.ThrowIfNull(bindingContract); + fallbackBindingCount = 0; + failure = string.Empty; + if (IsInsideTree()) + { + throw new InvalidOperationException("Тематический экран необходимо установить до входа контроллера в дерево."); + } + + Control? defaultView = base.GetNodeOrNull("SafeMargin"); + Control? defaultFooter = base.GetNodeOrNull("Footer"); + if (defaultView is null) + { + UsesBuiltInFallbackVisuals = true; + failure = "во встроенном экране отсутствует SafeMargin"; + return false; + } + + if (!ThemeBindingFallbackComposer.TryCompose( + this, + themeView, + descriptor, + bindingContract, + out IReadOnlyDictionary bindings, + out fallbackBindingCount, + out failure)) + { + UsesBuiltInFallbackVisuals = true; + return false; + } + + RemoveChild(defaultView); + defaultView.Free(); + if (defaultFooter is not null && defaultFooter.GetParent() == this) + { + RemoveChild(defaultFooter); + defaultFooter.Free(); + } + + PrepareSelfContainedVisuals(themeView); + AddChild(themeView); + _externalThemeView = themeView; + _externalBindings = bindings; + return true; + } + + public void BindThemeRuntime(ThemeManager themeManager) + { + ArgumentNullException.ThrowIfNull(themeManager); + if (_runtimeThemeManager is not null) + { + throw new InvalidOperationException("Runtime темы уже подключён к контроллеру экрана."); + } + + _runtimeThemeManager = themeManager; + _runtimeThemeManager.ThemeChanged += OnRuntimeThemeChanged; + TreeExiting += OnThemeScreenTreeExiting; + ApplyReducedEffects(themeManager.ReducedEffects); + } + + public new T GetNode(NodePath path) where T : Node + { + string pathText = path.ToString(); + if (_externalThemeView is null + || pathText.StartsWith("/", StringComparison.Ordinal)) + { + return base.GetNode(path); + } + + string bindingId = ThemeBindingResolver.FromFallbackPath(ThemeScreenKey, path); + return _externalBindings!.ContainsKey(bindingId) + ? ThemeBindingResolver.Resolve(_externalBindings, bindingId) + : base.GetNode(path); + } + + public new Node GetNode(NodePath path) + { + string pathText = path.ToString(); + if (_externalThemeView is null + || pathText.StartsWith("/", StringComparison.Ordinal)) + { + return base.GetNode(path); + } + + string bindingId = ThemeBindingResolver.FromFallbackPath(ThemeScreenKey, path); + return _externalBindings!.ContainsKey(bindingId) + ? ThemeBindingResolver.Resolve(_externalBindings, bindingId) + : base.GetNode(path); + } + + protected T GetThemeBinding(string bindingId) where T : Node + { + if (_externalBindings is null) + { + throw new InvalidOperationException( + $"Binding {bindingId} доступен только после установки внешней сцены темы."); + } + + return ThemeBindingResolver.Resolve(_externalBindings, bindingId); + } + + protected T? GetOptionalThemeBinding(string bindingId) where T : Node + { + if (_externalBindings is null) + { + throw new InvalidOperationException( + $"Binding {bindingId} доступен только после установки внешней сцены темы."); + } + + return _externalBindings.TryGetValue(bindingId, out Node? node) + ? node as T + : null; + } + + private void PrepareSelfContainedVisuals(Control themeView) + { + if (!themeView.HasMeta(ThemeSceneContract.SelfContainedVisualsMetadata) + || !themeView.GetMeta(ThemeSceneContract.SelfContainedVisualsMetadata).AsBool()) + { + return; + } + + _selfContainedDecoration = themeView.GetNodeOrNull( + ThemeSceneContract.SelfContainedDecorationNode); + if (_selfContainedDecoration is null) + { + return; + } + + } + + private void OnRuntimeThemeChanged(VendingThemeDefinition definition) + { + if (_runtimeThemeManager is not null) + { + ApplyReducedEffects(_runtimeThemeManager.ReducedEffects); + } + } + + private void ApplyReducedEffects(bool reducedEffects) + { + if (!GodotObject.IsInstanceValid(_selfContainedDecoration)) + { + return; + } + + _selfContainedDecoration!.Visible = !reducedEffects; + _selfContainedDecoration.ProcessMode = reducedEffects + ? ProcessModeEnum.Disabled + : ProcessModeEnum.Inherit; + } + + private void OnThemeScreenTreeExiting() + { + TreeExiting -= OnThemeScreenTreeExiting; + if (_runtimeThemeManager is not null) + { + _runtimeThemeManager.ThemeChanged -= OnRuntimeThemeChanged; + _runtimeThemeManager = null; + } + } +} diff --git a/src/core/ThemeManager/ThemeBindableScreen.cs.uid b/src/core/ThemeManager/ThemeBindableScreen.cs.uid new file mode 100644 index 0000000..b233ccc --- /dev/null +++ b/src/core/ThemeManager/ThemeBindableScreen.cs.uid @@ -0,0 +1 @@ +uid://404qjjbg86ss diff --git a/src/core/ThemeManager/ThemeBindingContract.cs b/src/core/ThemeManager/ThemeBindingContract.cs new file mode 100644 index 0000000..0ace6da --- /dev/null +++ b/src/core/ThemeManager/ThemeBindingContract.cs @@ -0,0 +1,180 @@ +using Godot; +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Security.Cryptography; +using System.Text.Json; +using GodotFileAccess = Godot.FileAccess; + +namespace Exchanger.Core.Theming; + +public enum ThemeBindingContractLoadFailure +{ + None, + Missing, + Unreadable, + HashMismatch, + Invalid, +} + +public sealed class ThemeBindingRequirement +{ + public string Id { get; set; } = string.Empty; + public string[] Types { get; set; } = []; + public bool Required { get; set; } + public string FallbackPath { get; set; } = string.Empty; +} + +public sealed class ThemeScreenBindingContract +{ + public string BindingId { get; set; } = string.Empty; + public string Key { get; set; } = string.Empty; + public string RootName { get; set; } = string.Empty; + public string Path { get; set; } = string.Empty; + public ThemeBindingRequirement[] Bindings { get; set; } = []; +} + +/// +/// Загруженный из DLC каталог биндингов, подлинность которого закреплена SHA-256 +/// в приложении. Благодаря этому тема несёт человекочитаемый контракт, но не может +/// самостоятельно ослабить требования приложения. +/// +public sealed class ThemeBindingContract +{ + public const string ResourcePath = + "res://exchanger_theme_dlc/contracts/screen_bindings.v2.json"; + public const int RequiredBindingCount = 481; + + // SHA-256 точного screen_bindings.v2.json, общего для приложения и Theme Builder. + public const string ExpectedSha256 = + "DDDC89118BEEA78A820561464001656136ED42AC1AD5710FB109D25ADAF44143"; + + private static readonly JsonSerializerOptions JsonOptions = new() + { + PropertyNameCaseInsensitive = true, + ReadCommentHandling = JsonCommentHandling.Skip, + AllowTrailingCommas = true, + }; + + private readonly IReadOnlyDictionary _screens; + + private ThemeBindingContract( + IReadOnlyDictionary screens) + { + _screens = screens; + } + + public ThemeScreenBindingContract GetScreen(string bindingId) => _screens[bindingId]; + + public static ThemeBindingContractLoadFailure TryLoad(out ThemeBindingContract? contract) + { + contract = null; + if (!GodotFileAccess.FileExists(ResourcePath)) + { + return ThemeBindingContractLoadFailure.Missing; + } + + byte[] bytes; + try + { + using GodotFileAccess? file = GodotFileAccess.Open(ResourcePath, GodotFileAccess.ModeFlags.Read); + if (file is null) + { + return ThemeBindingContractLoadFailure.Unreadable; + } + + bytes = file.GetBuffer((long)file.GetLength()); + } + catch (Exception exception) when (exception is IOException or UnauthorizedAccessException) + { + return ThemeBindingContractLoadFailure.Unreadable; + } + + string actualHash = Convert.ToHexString(SHA256.HashData(bytes)); + if (!actualHash.Equals(ExpectedSha256, StringComparison.Ordinal)) + { + return ThemeBindingContractLoadFailure.HashMismatch; + } + + ThemeBindingContractDocument? document; + try + { + document = JsonSerializer.Deserialize(bytes, JsonOptions); + } + catch (JsonException) + { + return ThemeBindingContractLoadFailure.Invalid; + } + + if (!TryValidate(document, out Dictionary? screens)) + { + return ThemeBindingContractLoadFailure.Invalid; + } + + contract = new ThemeBindingContract(screens); + return ThemeBindingContractLoadFailure.None; + } + + private static bool TryValidate( + ThemeBindingContractDocument? document, + out Dictionary screens) + { + screens = new Dictionary(StringComparer.Ordinal); + if (document is null + || !document.Format.Equals("ExchangerThemeBindingContract", StringComparison.Ordinal) + || document.Version != ThemeDlcManifestValidator.SupportedFormatVersion + || !document.ScreenMetadataKey.Equals(ThemeSceneContract.ScreenBindingMetadata, StringComparison.Ordinal) + || !document.ElementMetadataKey.Equals(ThemeSceneContract.ElementBindingMetadata, StringComparison.Ordinal) + || document.Screens.Length != ThemeSceneContract.Screens.Count) + { + return false; + } + + var allBindings = new HashSet(StringComparer.Ordinal); + foreach (ThemeScreenBindingContract screen in document.Screens) + { + if (!ThemeSceneContract.TryGetByBindingId(screen.BindingId, out ThemeScreenDescriptor descriptor) + || !screen.Key.Equals(descriptor.Key, StringComparison.Ordinal) + || !screen.RootName.Equals(descriptor.RootName, StringComparison.Ordinal) + || !screen.Path.Equals(descriptor.ScenePath, StringComparison.Ordinal) + || screen.Bindings.Length == 0 + || !screens.TryAdd(screen.BindingId, screen)) + { + return false; + } + + foreach (ThemeBindingRequirement binding in screen.Bindings) + { + if (!binding.Required + || string.IsNullOrWhiteSpace(binding.FallbackPath) + || binding.Types.Length == 0 + || binding.Types.Any(string.IsNullOrWhiteSpace) + || !ThemeSceneContract.IsValidElementBinding(descriptor.Key, binding.Id) + || !allBindings.Add(binding.Id)) + { + return false; + } + } + } + + foreach (ThemeScreenDescriptor screen in ThemeSceneContract.Screens) + { + if (!screens.ContainsKey(screen.BindingId)) + { + return false; + } + } + + return allBindings.Count == RequiredBindingCount; + } + + private sealed class ThemeBindingContractDocument + { + public string Format { get; set; } = string.Empty; + public int Version { get; set; } + public string ScreenMetadataKey { get; set; } = string.Empty; + public string ElementMetadataKey { get; set; } = string.Empty; + public ThemeScreenBindingContract[] Screens { get; set; } = []; + } +} diff --git a/src/core/ThemeManager/ThemeBindingContract.cs.uid b/src/core/ThemeManager/ThemeBindingContract.cs.uid new file mode 100644 index 0000000..499b0e7 --- /dev/null +++ b/src/core/ThemeManager/ThemeBindingContract.cs.uid @@ -0,0 +1 @@ +uid://bmy1o2fxqbn21 diff --git a/src/core/ThemeManager/ThemeBindingFallbackComposer.cs b/src/core/ThemeManager/ThemeBindingFallbackComposer.cs new file mode 100644 index 0000000..ca7f5df --- /dev/null +++ b/src/core/ThemeManager/ThemeBindingFallbackComposer.cs @@ -0,0 +1,198 @@ +using Godot; +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Exchanger.Core.Theming; + +/// +/// Дополняет неполную внешнюю сцену готовыми узлами встроенного экрана. +/// Узлы переносятся только по объявленным fallback-path и сохраняют встроенную Theme. +/// +internal static class ThemeBindingFallbackComposer +{ + public static bool TryCompose( + Control fallbackHost, + Control externalView, + ThemeScreenDescriptor descriptor, + ThemeScreenBindingContract bindingContract, + out IReadOnlyDictionary bindings, + out int fallbackBindingCount, + out string failure) + { + ArgumentNullException.ThrowIfNull(fallbackHost); + ArgumentNullException.ThrowIfNull(externalView); + ArgumentNullException.ThrowIfNull(bindingContract); + + IReadOnlyDictionary externalBindings = + ThemeBindingResolver.BuildIndex(externalView); + bindings = externalBindings; + fallbackBindingCount = 0; + failure = string.Empty; + + ThemeSceneContract.FallbackBindingRequirement[] requirements = + ThemeSceneContract.GetFallbackBindings(descriptor.ScreenId, bindingContract) + .GroupBy(requirement => requirement.Id, StringComparer.Ordinal) + .Select(group => group.First()) + .ToArray(); + + ThemeSceneContract.FallbackBindingRequirement[] missing = requirements + .Where(requirement => requirement.Required && !externalBindings.ContainsKey(requirement.Id)) + .OrderBy(requirement => GetPathDepth(requirement.FallbackPath)) + .ToArray(); + if (missing.Length == 0) + { + return true; + } + + int compatibilityBindingCount = missing.Length; + foreach (ThemeSceneContract.FallbackBindingRequirement requirement in missing) + { + Node? legacyNode = externalView.GetNodeOrNull(requirement.FallbackPath); + if (legacyNode is not null + && !legacyNode.HasMeta(ThemeSceneContract.ElementBindingMetadata) + && requirement.Types.Any(type => legacyNode.IsClass(type))) + { + legacyNode.SetMeta(ThemeSceneContract.ElementBindingMetadata, requirement.Id); + } + } + + externalBindings = ThemeBindingResolver.BuildIndex(externalView); + bindings = externalBindings; + missing = requirements + .Where(requirement => requirement.Required && !externalBindings.ContainsKey(requirement.Id)) + .OrderBy(requirement => GetPathDepth(requirement.FallbackPath)) + .ToArray(); + if (missing.Length == 0) + { + fallbackBindingCount = compatibilityBindingCount; + return true; + } + + var fallbackNodes = new Dictionary(StringComparer.Ordinal); + foreach (ThemeSceneContract.FallbackBindingRequirement requirement in missing) + { + if (string.IsNullOrWhiteSpace(requirement.FallbackPath)) + { + failure = $"для обязательного биндинга {requirement.Id} не объявлен fallback-path"; + return false; + } + + Node? fallbackNode = fallbackHost.GetNodeOrNull(requirement.FallbackPath); + if (fallbackNode is null) + { + failure = $"во встроенной сцене отсутствует fallback {requirement.FallbackPath}"; + return false; + } + + if (!requirement.Types.Any(type => fallbackNode.IsClass(type))) + { + failure = $"fallback {requirement.FallbackPath} имеет несовместимый тип {fallbackNode.GetClass()}"; + return false; + } + + fallbackNodes.Add(requirement.Id, fallbackNode); + } + + ThemeSceneContract.FallbackBindingRequirement[] transplantRoots = + SelectTransplantRoots(missing); + var targetParents = new Dictionary(StringComparer.Ordinal); + foreach (ThemeSceneContract.FallbackBindingRequirement rootRequirement in transplantRoots) + { + string parentPath = GetParentPath(rootRequirement.FallbackPath); + Node? targetParent = string.IsNullOrEmpty(parentPath) + ? externalView + : externalView.GetNodeOrNull(parentPath); + if (targetParent is null) + { + string parentBindingId = ThemeBindingResolver.FromFallbackPath(descriptor.Key, parentPath); + externalBindings.TryGetValue(parentBindingId, out targetParent); + } + + if (targetParent is null) + { + failure = $"в тематической сцене отсутствует родитель для fallback {rootRequirement.FallbackPath}"; + return false; + } + + targetParents.Add(rootRequirement.Id, targetParent); + } + + foreach (ThemeSceneContract.FallbackBindingRequirement requirement in missing) + { + fallbackNodes[requirement.Id].SetMeta( + ThemeSceneContract.ElementBindingMetadata, + requirement.Id); + } + + Theme fallbackTheme = BuiltInFallbackTheme.Create().UiTheme!; + foreach (ThemeSceneContract.FallbackBindingRequirement rootRequirement in transplantRoots) + { + Node fallbackNode = fallbackNodes[rootRequirement.Id]; + Node? oldParent = fallbackNode.GetParent(); + oldParent?.RemoveChild(fallbackNode); + ClearOwners(fallbackNode); + targetParents[rootRequirement.Id].AddChild(fallbackNode, forceReadableName: true); + ApplyBuiltInTheme(fallbackNode, fallbackTheme); + } + + bindings = ThemeBindingResolver.BuildIndex(externalView); + foreach (ThemeSceneContract.FallbackBindingRequirement requirement in missing) + { + if (!bindings.TryGetValue(requirement.Id, out Node? node) + || !requirement.Types.Any(type => node.IsClass(type))) + { + failure = $"не удалось подключить встроенный fallback для {requirement.Id}"; + return false; + } + } + + fallbackBindingCount = compatibilityBindingCount; + return true; + } + + internal static ThemeSceneContract.FallbackBindingRequirement[] SelectTransplantRoots( + IReadOnlyCollection missing) + { + return missing + .Where(candidate => !missing.Any(other => + !candidate.Id.Equals(other.Id, StringComparison.Ordinal) + && IsDescendantPath(candidate.FallbackPath, other.FallbackPath))) + .OrderBy(candidate => GetPathDepth(candidate.FallbackPath)) + .ToArray(); + } + + private static void ApplyBuiltInTheme(Node root, Theme fallbackTheme) + { + if (root is Control control) + { + control.Theme = fallbackTheme; + } + + foreach (Node child in root.GetChildren()) + { + ApplyBuiltInTheme(child, fallbackTheme); + } + } + + private static void ClearOwners(Node root) + { + root.Owner = null; + foreach (Node child in root.GetChildren()) + { + ClearOwners(child); + } + } + + private static bool IsDescendantPath(string candidate, string ancestor) => + candidate.StartsWith(ancestor + "/", StringComparison.Ordinal); + + private static int GetPathDepth(string path) => + path.Count(character => character == '/'); + + private static string GetParentPath(string path) + { + int separator = path.LastIndexOf('/'); + return separator > 0 ? path[..separator] : string.Empty; + } +} diff --git a/src/core/ThemeManager/ThemeBindingFallbackComposer.cs.uid b/src/core/ThemeManager/ThemeBindingFallbackComposer.cs.uid new file mode 100644 index 0000000..9afa5c9 --- /dev/null +++ b/src/core/ThemeManager/ThemeBindingFallbackComposer.cs.uid @@ -0,0 +1 @@ +uid://besosx70s8yju diff --git a/src/core/ThemeManager/ThemeBindingResolver.cs b/src/core/ThemeManager/ThemeBindingResolver.cs new file mode 100644 index 0000000..cc7071d --- /dev/null +++ b/src/core/ThemeManager/ThemeBindingResolver.cs @@ -0,0 +1,129 @@ +using Godot; +using System; +using System.Collections.Generic; +using System.Text; + +namespace Exchanger.Core.Theming; + +/// Разрешает узлы тематической сцены по стабильным metadata binding-id. +public static class ThemeBindingResolver +{ + public static string FromFallbackPath(string screenKey, NodePath fallbackPath) + => FromFallbackPath(screenKey, fallbackPath.ToString()); + + public static string FromFallbackPath(string screenKey, string fallbackPath) + { + string path = fallbackPath.Trim(); + if (path.StartsWith("SafeMargin/", StringComparison.Ordinal)) + { + path = path["SafeMargin/".Length..]; + } + + var result = new StringBuilder(screenKey); + foreach (string segment in path.Split('/', StringSplitOptions.RemoveEmptyEntries)) + { + result.Append('.'); + AppendSnakeCase(result, segment); + } + + return result.ToString(); + } + + public static T Resolve(Node bindingRoot, string bindingId) where T : Node + { + ArgumentNullException.ThrowIfNull(bindingRoot); + + Node? match = null; + Find(bindingRoot, bindingId, ref match); + if (match is T typed) + { + return typed; + } + + if (match is not null) + { + throw new InvalidOperationException( + $"Биндинг темы '{bindingId}' имеет тип {match.GetClass()}, ожидался {typeof(T).Name}."); + } + + throw new InvalidOperationException($"В тематической сцене отсутствует обязательный биндинг '{bindingId}'."); + } + + public static T Resolve(IReadOnlyDictionary bindings, string bindingId) where T : Node + { + ArgumentNullException.ThrowIfNull(bindings); + if (!bindings.TryGetValue(bindingId, out Node? match)) + { + throw new InvalidOperationException($"В тематической сцене отсутствует обязательный биндинг '{bindingId}'."); + } + + if (match is not T typed) + { + throw new InvalidOperationException( + $"Биндинг темы '{bindingId}' имеет тип {match.GetClass()}, ожидался {typeof(T).Name}."); + } + + return typed; + } + + public static IReadOnlyDictionary BuildIndex(Node bindingRoot) + { + ArgumentNullException.ThrowIfNull(bindingRoot); + var result = new Dictionary(StringComparer.Ordinal); + Index(bindingRoot, result); + return result; + } + + private static void Find(Node node, string bindingId, ref Node? match) + { + if (match is not null) + { + return; + } + + if (node.HasMeta(ThemeSceneContract.ElementBindingMetadata) + && node.GetMeta(ThemeSceneContract.ElementBindingMetadata).AsString() + .Equals(bindingId, StringComparison.Ordinal)) + { + match = node; + return; + } + + foreach (Node child in node.GetChildren()) + { + Find(child, bindingId, ref match); + } + } + + private static void Index(Node node, IDictionary result) + { + if (node.HasMeta(ThemeSceneContract.ElementBindingMetadata)) + { + string bindingId = node.GetMeta(ThemeSceneContract.ElementBindingMetadata).AsString(); + if (!string.IsNullOrWhiteSpace(bindingId) && !result.TryAdd(bindingId, node)) + { + throw new InvalidOperationException($"Биндинг темы '{bindingId}' указан более одного раза."); + } + } + + foreach (Node child in node.GetChildren()) + { + Index(child, result); + } + } + + private static void AppendSnakeCase(StringBuilder result, string value) + { + for (int index = 0; index < value.Length; index++) + { + char character = value[index]; + if (char.IsUpper(character) && index > 0 + && (char.IsLower(value[index - 1]) || char.IsDigit(value[index - 1]))) + { + result.Append('_'); + } + + result.Append(char.ToLowerInvariant(character)); + } + } +} diff --git a/src/core/ThemeManager/ThemeBindingResolver.cs.uid b/src/core/ThemeManager/ThemeBindingResolver.cs.uid new file mode 100644 index 0000000..5b61dd1 --- /dev/null +++ b/src/core/ThemeManager/ThemeBindingResolver.cs.uid @@ -0,0 +1 @@ +uid://rdauhxvp7qg4 diff --git a/src/core/ThemeManager/ThemeDlcLoader.cs b/src/core/ThemeManager/ThemeDlcLoader.cs new file mode 100644 index 0000000..fb6c6a3 --- /dev/null +++ b/src/core/ThemeManager/ThemeDlcLoader.cs @@ -0,0 +1,261 @@ +using Godot; +using Exchanger.Core.Navigation; +using System; +using System.IO; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using GodotFileAccess = Godot.FileAccess; + +namespace Exchanger.Core.Theming; + +public enum ThemeDlcLoadStatus +{ + Disabled, + NotFound, + InvalidExternalPath, + InvalidExtension, + MountFailed, + ManifestMissing, + ManifestUnreadable, + ManifestInvalid, + ResourceMissing, + ResourceTypeMismatch, + BindingContractMissing, + BindingContractInvalid, + IncompatibleVisualComposition, + Loaded, +} + +public readonly record struct ThemeDlcLoadResult( + ThemeDlcLoadStatus Status, + VendingThemeDefinition? Theme = null, + ThemeDlcManifestFailure ManifestFailure = ThemeDlcManifestFailure.None, + ThemeBindingContractLoadFailure BindingContractFailure = ThemeBindingContractLoadFailure.None, + ThemeScreenSceneFailure ScreenSceneFailure = ThemeScreenSceneFailure.None, + string ScreenBindingId = ""); + +/// +/// Монтирует один внешний .pck без права заменять ресурсы приложения, +/// валидирует manifest и создаёт runtime-описание темы. +/// +public static class ThemeDlcLoader +{ + private static readonly JsonSerializerOptions JsonOptions = new() + { + PropertyNameCaseInsensitive = true, + ReadCommentHandling = JsonCommentHandling.Skip, + AllowTrailingCommas = true, + }; + + public static ThemeDlcLoadResult Load(string configuredPath) + { + string? absolutePath = ResolveExternalPath(configuredPath); + if (absolutePath is null) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.InvalidExternalPath); + } + + if (!Path.GetExtension(absolutePath).Equals(".pck", StringComparison.OrdinalIgnoreCase)) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.InvalidExtension); + } + + if (!File.Exists(absolutePath)) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.NotFound); + } + + if (!ProjectSettings.LoadResourcePack(absolutePath, replaceFiles: false)) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.MountFailed); + } + + if (!GodotFileAccess.FileExists(ThemeDlcManifestValidator.ManifestPath)) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.ManifestMissing); + } + + ThemeDlcManifest? manifest; + try + { + using GodotFileAccess? file = GodotFileAccess.Open( + ThemeDlcManifestValidator.ManifestPath, + GodotFileAccess.ModeFlags.Read); + if (file is null) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.ManifestUnreadable); + } + + manifest = JsonSerializer.Deserialize(file.GetAsText(), JsonOptions); + } + catch (JsonException) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.ManifestUnreadable); + } + + ThemeDlcManifestFailure failure = ThemeDlcManifestValidator.Validate(manifest); + if (failure != ThemeDlcManifestFailure.None || manifest is null) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.ManifestInvalid, ManifestFailure: failure); + } + + ThemeBindingContract? bindingContract = null; + if (manifest.FormatVersion >= ThemeDlcManifestValidator.SupportedFormatVersion) + { + ThemeBindingContractLoadFailure contractFailure = ThemeBindingContract.TryLoad(out bindingContract); + if (contractFailure == ThemeBindingContractLoadFailure.Missing) + { + return new ThemeDlcLoadResult( + ThemeDlcLoadStatus.BindingContractMissing, + BindingContractFailure: contractFailure); + } + + if (contractFailure != ThemeBindingContractLoadFailure.None || bindingContract is null) + { + return new ThemeDlcLoadResult( + ThemeDlcLoadStatus.BindingContractInvalid, + BindingContractFailure: contractFailure); + } + } + + if (!ResourceLoader.Exists(manifest.UiThemePath) + || (!string.IsNullOrWhiteSpace(manifest.BackgroundTexturePath) + && !ResourceLoader.Exists(manifest.BackgroundTexturePath)) + || (!string.IsNullOrWhiteSpace(manifest.BackgroundDecorationPath) + && !ResourceLoader.Exists(manifest.BackgroundDecorationPath)) + || (!string.IsNullOrWhiteSpace(manifest.InteractivePetScene) + && !ResourceLoader.Exists(manifest.InteractivePetScene)) + || manifest.VisualSlots.Values.Any(path => !ResourceLoader.Exists(path)) + || manifest.ScreenScenes.Values.Any(path => !ResourceLoader.Exists(path))) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.ResourceMissing); + } + + Theme? uiTheme = ResourceLoader.Load(manifest.UiThemePath); + Texture2D? background = string.IsNullOrWhiteSpace(manifest.BackgroundTexturePath) + ? null + : ResourceLoader.Load(manifest.BackgroundTexturePath); + PackedScene? decoration = string.IsNullOrWhiteSpace(manifest.BackgroundDecorationPath) + ? null + : ResourceLoader.Load(manifest.BackgroundDecorationPath); + PackedScene? interactivePet = string.IsNullOrWhiteSpace(manifest.InteractivePetScene) + ? null + : ResourceLoader.Load(manifest.InteractivePetScene); + var visualSlots = new Dictionary(StringComparer.Ordinal); + foreach ((string slotId, string path) in manifest.VisualSlots) + { + PackedScene? scene = ResourceLoader.Load(path); + if (scene is null) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.ResourceTypeMismatch); + } + + visualSlots.Add(slotId, scene); + } + + var screenScenes = new Dictionary(); + var screenBindingContracts = new Dictionary(); + bool? selfContainedScreenVisuals = null; + foreach ((string screenBindingId, string path) in manifest.ScreenScenes) + { + if (!ThemeSceneContract.TryGetByBindingId(screenBindingId, out ThemeScreenDescriptor descriptor)) + { + return new ThemeDlcLoadResult( + ThemeDlcLoadStatus.ManifestInvalid, + ManifestFailure: ThemeDlcManifestFailure.InvalidScreenScene); + } + + PackedScene? scene = ResourceLoader.Load(path); + ThemeScreenBindingContract? screenBindingContract = + bindingContract?.GetScreen(descriptor.BindingId); + ThemeScreenSceneFailure sceneFailure = ThemeSceneContract.ValidateScene( + scene, + descriptor, + screenBindingContract, + out bool sceneSelfContainedVisuals); + if (scene is null || sceneFailure != ThemeScreenSceneFailure.None) + { + return new ThemeDlcLoadResult( + ThemeDlcLoadStatus.ResourceTypeMismatch, + ScreenSceneFailure: sceneFailure, + ScreenBindingId: descriptor.BindingId); + } + + if (selfContainedScreenVisuals is not null + && selfContainedScreenVisuals.Value != sceneSelfContainedVisuals) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.IncompatibleVisualComposition); + } + + selfContainedScreenVisuals ??= sceneSelfContainedVisuals; + + screenScenes.Add(descriptor.ScreenId, scene); + if (screenBindingContract is not null) + { + screenBindingContracts.Add(descriptor.ScreenId, screenBindingContract); + } + } + + bool usesSelfContainedScreenVisuals = selfContainedScreenVisuals == true; + if (!ThemeSceneContract.IsCompatibleVisualComposition( + usesSelfContainedScreenVisuals, + manifest.BackgroundTexturePath, + manifest.BackgroundDecorationPath)) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.IncompatibleVisualComposition); + } + if (uiTheme is null + || (!string.IsNullOrWhiteSpace(manifest.BackgroundTexturePath) && background is null) + || (!string.IsNullOrWhiteSpace(manifest.BackgroundDecorationPath) && decoration is null) + || (!string.IsNullOrWhiteSpace(manifest.InteractivePetScene) && interactivePet is null) + || (interactivePet is not null && !InteractivePetContract.IsCompatible(interactivePet))) + { + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.ResourceTypeMismatch); + } + + var definition = new VendingThemeDefinition + { + ThemeId = manifest.ThemeId.Trim(), + DisplayName = manifest.DisplayName.Trim(), + UiTheme = uiTheme, + BackgroundTexture = background, + BackgroundDecoration = decoration, + InteractivePetScene = interactivePet, + BackgroundDecorationScale = manifest.BackgroundDecorationScale, + FallbackColor = Color.FromHtml(manifest.FallbackColor), + UseNearestTextureFilter = manifest.UseNearestTextureFilter, + VisualSlots = visualSlots, + ScreenScenes = screenScenes, + ScreenBindingContracts = screenBindingContracts, + SelfContainedScreenVisuals = usesSelfContainedScreenVisuals, + }; + return new ThemeDlcLoadResult(ThemeDlcLoadStatus.Loaded, definition); + } + + private static string? ResolveExternalPath(string configuredPath) + { + if (string.IsNullOrWhiteSpace(configuredPath) + || configuredPath.StartsWith("res://", StringComparison.OrdinalIgnoreCase)) + { + return null; + } + + try + { + string trimmed = configuredPath.Trim(); + if (trimmed.StartsWith("user://", StringComparison.OrdinalIgnoreCase)) + { + return Path.GetFullPath(ProjectSettings.GlobalizePath(trimmed)); + } + + return Path.IsPathFullyQualified(trimmed) + ? Path.GetFullPath(trimmed) + : null; + } + catch (Exception exception) when (exception is ArgumentException or NotSupportedException or PathTooLongException) + { + return null; + } + } +} diff --git a/src/core/ThemeManager/ThemeDlcLoader.cs.uid b/src/core/ThemeManager/ThemeDlcLoader.cs.uid new file mode 100644 index 0000000..cc668a2 --- /dev/null +++ b/src/core/ThemeManager/ThemeDlcLoader.cs.uid @@ -0,0 +1 @@ +uid://bsstxhjcr4u7d diff --git a/src/core/ThemeManager/ThemeDlcManifest.cs b/src/core/ThemeManager/ThemeDlcManifest.cs new file mode 100644 index 0000000..b599411 --- /dev/null +++ b/src/core/ThemeManager/ThemeDlcManifest.cs @@ -0,0 +1,243 @@ +using System; +using System.Collections.Generic; + +namespace Exchanger.Core.Theming; + +public sealed class ThemeDlcManifest +{ + public string Format { get; set; } = string.Empty; + + public int FormatVersion { get; set; } + + public string ThemeId { get; set; } = string.Empty; + + public string DisplayName { get; set; } = string.Empty; + + public string UiThemePath { get; set; } = string.Empty; + + public string BackgroundTexturePath { get; set; } = string.Empty; + + public string BackgroundDecorationPath { get; set; } = string.Empty; + + public float BackgroundDecorationScale { get; set; } = 1f; + + public string InteractivePetScene { get; set; } = string.Empty; + + public Dictionary VisualSlots { get; set; } = new(StringComparer.Ordinal); + + public Dictionary ScreenScenes { get; set; } = new(StringComparer.Ordinal); + + public string FallbackColor { get; set; } = "#061229"; + + public bool UseNearestTextureFilter { get; set; } +} + +public enum ThemeDlcManifestFailure +{ + None, + WrongFormat, + UnsupportedVersion, + InvalidThemeId, + InvalidDisplayName, + InvalidUiThemePath, + InvalidBackgroundTexturePath, + InvalidBackgroundDecorationPath, + InvalidBackgroundDecorationScale, + InvalidInteractivePetScenePath, + InvalidVisualSlot, + InvalidScreenScene, + InvalidFallbackColor, +} + +public static class ThemeDlcManifestValidator +{ + public const string ExpectedFormat = "ExchangerThemeDlc"; + public const int LegacyFormatVersion = 1; + public const int SupportedFormatVersion = 2; + public const string ResourceRoot = "res://exchanger_theme_dlc/"; + public const string ManifestPath = ResourceRoot + "manifest.json"; + + public static ThemeDlcManifestFailure Validate(ThemeDlcManifest? manifest) + { + if (manifest is null || !manifest.Format.Equals(ExpectedFormat, StringComparison.Ordinal)) + { + return ThemeDlcManifestFailure.WrongFormat; + } + + if (manifest.FormatVersion is < LegacyFormatVersion or > SupportedFormatVersion) + { + return ThemeDlcManifestFailure.UnsupportedVersion; + } + + if (!IsValidThemeId(manifest.ThemeId)) + { + return ThemeDlcManifestFailure.InvalidThemeId; + } + + if (string.IsNullOrWhiteSpace(manifest.DisplayName) || manifest.DisplayName.Trim().Length > 80) + { + return ThemeDlcManifestFailure.InvalidDisplayName; + } + + if (!IsDlcResourcePath(manifest.UiThemePath, ".tres", ".res")) + { + return ThemeDlcManifestFailure.InvalidUiThemePath; + } + + if (!IsOptionalDlcResourcePath(manifest.BackgroundTexturePath, ".png", ".webp", ".jpg", ".jpeg", ".svg")) + { + return ThemeDlcManifestFailure.InvalidBackgroundTexturePath; + } + + if (!IsOptionalDlcResourcePath(manifest.BackgroundDecorationPath, ".tscn", ".scn")) + { + return ThemeDlcManifestFailure.InvalidBackgroundDecorationPath; + } + + if (!float.IsFinite(manifest.BackgroundDecorationScale) + || manifest.BackgroundDecorationScale is < 0.1f or > 4f) + { + return ThemeDlcManifestFailure.InvalidBackgroundDecorationScale; + } + + if (!IsOptionalDlcResourcePath(manifest.InteractivePetScene, ".tscn", ".scn")) + { + return ThemeDlcManifestFailure.InvalidInteractivePetScenePath; + } + + if (manifest.VisualSlots is null || manifest.VisualSlots.Count > 32) + { + return ThemeDlcManifestFailure.InvalidVisualSlot; + } + + foreach ((string slotId, string path) in manifest.VisualSlots) + { + if (!IsValidSlotId(slotId) || !IsDlcResourcePath(path, ".tscn", ".scn")) + { + return ThemeDlcManifestFailure.InvalidVisualSlot; + } + } + + if (manifest.ScreenScenes is null) + { + return ThemeDlcManifestFailure.InvalidScreenScene; + } + + // Полносценовые темы требуют строгий v2-контракт биндингов. Старый v1 + // допускается только для UI-theme/слотов: иначе новый host может упасть + // при обращении к отсутствующему обязательному элементу сцены. + if (manifest.FormatVersion == LegacyFormatVersion && manifest.ScreenScenes.Count > 0) + { + return ThemeDlcManifestFailure.InvalidScreenScene; + } + + if (manifest.FormatVersion >= 2) + { + if (manifest.ScreenScenes.Count != ThemeSceneContract.Screens.Count) + { + return ThemeDlcManifestFailure.InvalidScreenScene; + } + + foreach (ThemeScreenDescriptor descriptor in ThemeSceneContract.Screens) + { + if (!manifest.ScreenScenes.TryGetValue(descriptor.BindingId, out string? path) + || !path.Equals(descriptor.ScenePath, StringComparison.Ordinal)) + { + return ThemeDlcManifestFailure.InvalidScreenScene; + } + } + } + else if (manifest.ScreenScenes.Count > 0) + { + return ThemeDlcManifestFailure.InvalidScreenScene; + } + + if (!IsHexColor(manifest.FallbackColor)) + { + return ThemeDlcManifestFailure.InvalidFallbackColor; + } + + return ThemeDlcManifestFailure.None; + } + + private static bool IsValidThemeId(string value) + { + if (string.IsNullOrWhiteSpace(value) || value.Length > 64 || !char.IsLetterOrDigit(value[0])) + { + return false; + } + + foreach (char character in value) + { + if (!char.IsLetterOrDigit(character) && character is not ('-' or '_' or '.')) + { + return false; + } + } + + return true; + } + + private static bool IsValidSlotId(string value) + { + if (string.IsNullOrWhiteSpace(value) || value.Length > 64 || !char.IsLetterOrDigit(value[0])) + { + return false; + } + + foreach (char character in value) + { + if (!char.IsLetterOrDigit(character) && character is not ('-' or '_' or '.')) + { + return false; + } + } + + return true; + } + + private static bool IsOptionalDlcResourcePath(string value, params string[] extensions) + { + return string.IsNullOrWhiteSpace(value) || IsDlcResourcePath(value, extensions); + } + + private static bool IsDlcResourcePath(string value, params string[] extensions) + { + if (string.IsNullOrWhiteSpace(value) + || !value.StartsWith(ResourceRoot, StringComparison.Ordinal) + || value.Contains("..", StringComparison.Ordinal) + || value.Contains('\\')) + { + return false; + } + + foreach (string extension in extensions) + { + if (value.EndsWith(extension, StringComparison.OrdinalIgnoreCase)) + { + return true; + } + } + + return false; + } + + private static bool IsHexColor(string value) + { + string hex = (value ?? string.Empty).Trim().TrimStart('#'); + if (hex.Length is not (6 or 8)) + { + return false; + } + + foreach (char character in hex) + { + if (!Uri.IsHexDigit(character)) + { + return false; + } + } + + return true; + } +} diff --git a/src/core/ThemeManager/ThemeDlcManifest.cs.uid b/src/core/ThemeManager/ThemeDlcManifest.cs.uid new file mode 100644 index 0000000..6adfb6e --- /dev/null +++ b/src/core/ThemeManager/ThemeDlcManifest.cs.uid @@ -0,0 +1 @@ +uid://c4jg4txnu2vap diff --git a/src/core/ThemeManager/ThemeManager.cs b/src/core/ThemeManager/ThemeManager.cs new file mode 100644 index 0000000..f6c1019 --- /dev/null +++ b/src/core/ThemeManager/ThemeManager.cs @@ -0,0 +1,119 @@ +using Exchanger.Core.Configuration; +using Exchanger.Core.Logging; +using Godot; + +namespace Exchanger.Core.Theming; + +/// +/// Загружает единственную встроенную fallback-тему и при наличии дополняет её +/// одной проверенной темой из внешнего DLC resource pack. +/// +public partial class ThemeManager : Node +{ + [Signal] + public delegate void ThemeChangedEventHandler(VendingThemeDefinition theme); + + private VendingThemeDefinition? _currentTheme; + + public VendingThemeDefinition? CurrentTheme => _currentTheme; + + public bool ReducedEffects { get; private set; } + + public bool IsExternalDlcActive { get; private set; } + + public void Configure(ThemeSettings settings) + { + ReducedEffects = settings.ReducedEffects; + IsExternalDlcActive = false; + _currentTheme = BuiltInFallbackTheme.Create(); + + if (settings.ExternalDlcEnabled) + { + ThemeDlcLoadResult result = ThemeDlcLoader.Load(settings.ExternalDlcPath); + if (result.Status == ThemeDlcLoadStatus.Loaded && result.Theme is not null) + { + _currentTheme = result.Theme; + IsExternalDlcActive = true; + AppLogger.Info("Theme", $"Активирована внешняя DLC-тема {result.Theme.ThemeId} ({result.Theme.DisplayName})."); + } + else if (result.Status == ThemeDlcLoadStatus.NotFound) + { + AppLogger.Info("Theme", "Внешний DLC темы не найден; используется встроенная тема."); + } + else if (result.Status != ThemeDlcLoadStatus.Disabled) + { + string contractDetails = result.BindingContractFailure == ThemeBindingContractLoadFailure.None + ? string.Empty + : $", контракт: {result.BindingContractFailure}"; + string sceneDetails = result.ScreenSceneFailure == ThemeScreenSceneFailure.None + ? string.Empty + : $", сцена {result.ScreenBindingId}: {result.ScreenSceneFailure}"; + AppLogger.Warning( + "Theme", + $"DLC темы отклонён ({result.Status}{contractDetails}{sceneDetails}); используется встроенная тема."); + } + } + + if (_currentTheme.UiTheme is not null) + { + // Manifest v1 themes remain forward-compatible when the host adds a + // semantic role: an unstyled role safely inherits its Godot base type. + ThemeSemanticTypes.RegisterFallbackBaseTypes(_currentTheme.UiTheme); + } + + AppLogger.Info( + "Theme", + IsExternalDlcActive + ? "Тема загружена из внешнего DLC." + : "Активирована единственная встроенная тема по умолчанию."); + EmitSignal(SignalName.ThemeChanged, _currentTheme); + } + + public void SetReducedEffects(bool reducedEffects) + { + if (ReducedEffects == reducedEffects) + { + return; + } + + ReducedEffects = reducedEffects; + AppLogger.Info("Theme", reducedEffects + ? "Включён облегчённый режим визуальных эффектов." + : "Включён полный режим визуальных эффектов."); + + if (_currentTheme is not null) + { + EmitSignal(SignalName.ThemeChanged, _currentTheme); + } + } + + public void ApplyTo(Control root) + { + if (root is ThemeBindableScreen { UsesBuiltInFallbackVisuals: true }) + { + root.TextureFilter = CanvasItem.TextureFilterEnum.ParentNode; + root.Theme = BuiltInFallbackTheme.Create().UiTheme; + return; + } + + if (root is ThemeBindableScreen { UsesSelfContainedThemeScene: true }) + { + // Полносценовая тема уже содержит собственные Theme, фильтрацию, + // геометрию и type variations. Host не должен менять её визуалы. + return; + } + + // Pixel-art DLC resources are scaled by controls owned by the host + // application, so their filter cannot be selected from inside the PCK. + // Keep the built-in theme on the project default and make an external + // theme crisp without changing the global renderer configuration. + root.TextureFilter = _currentTheme?.UseNearestTextureFilter == true + ? CanvasItem.TextureFilterEnum.Nearest + : CanvasItem.TextureFilterEnum.ParentNode; + + if (_currentTheme?.UiTheme is not null) + { + root.Theme = _currentTheme.UiTheme; + } + } +} diff --git a/src/core/ThemeManager/ThemeManager.cs.uid b/src/core/ThemeManager/ThemeManager.cs.uid new file mode 100644 index 0000000..1958f50 --- /dev/null +++ b/src/core/ThemeManager/ThemeManager.cs.uid @@ -0,0 +1 @@ +uid://bu1etfjm4dbmt diff --git a/src/core/ThemeManager/ThemeSceneContract.cs b/src/core/ThemeManager/ThemeSceneContract.cs new file mode 100644 index 0000000..b79d2a9 --- /dev/null +++ b/src/core/ThemeManager/ThemeSceneContract.cs @@ -0,0 +1,503 @@ +using Exchanger.Core.Navigation; +using Godot; +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Exchanger.Core.Theming; + +public readonly record struct ThemeScreenDescriptor( + ScreenId ScreenId, + string BindingId, + string Key, + string ScenePath, + string RootName); + +public enum ThemeScreenSceneFailure +{ + None, + MissingScene, + WrongRootType, + WrongRootName, + MissingScreenBinding, + MissingElementBinding, + DuplicateElementBinding, + InvalidElementBinding, + UnexpectedElementBinding, + MissingRequiredBinding, + WrongBindingType, + InvalidSelfContainedMetadata, + MissingSelfContainedTheme, + MissingSelfContainedBackground, + MissingSelfContainedDecoration, +} + +/// +/// Стабильный контракт имён полносценовой DLC-темы. Идентификаторы не зависят +/// от расположения узлов внутри тематической сцены. +/// +public static class ThemeSceneContract +{ + private readonly record struct RuntimeBindingRequirement( + string Id, + string Type, + string FallbackPath, + bool Required = true); + + internal readonly record struct FallbackBindingRequirement( + string Id, + string[] Types, + string FallbackPath, + bool Required); + + public const string ScreenBindingMetadata = "exchanger_screen_binding_id"; + public const string ElementBindingMetadata = "exchanger_binding_id"; + public const string SelfContainedVisualsMetadata = "exchanger_self_contained_visuals"; + public const string SelfContainedBackgroundNode = "ThemeBackground"; + public const string SelfContainedDecorationNode = "BackgroundDecoration"; + + public static readonly IReadOnlyList Screens = + [ + Describe(ScreenId.Home, "home", "Home"), + Describe(ScreenId.CashPayment, "cash_payment", "CashPayment"), + Describe(ScreenId.CardAmount, "card_amount", "CardAmount"), + Describe(ScreenId.CardCustomAmount, "card_custom_amount", "CardCustomAmount"), + Describe(ScreenId.CardTerminal, "card_terminal", "CardTerminal"), + Describe(ScreenId.Success, "success", "Success"), + Describe(ScreenId.Error, "error", "Error"), + Describe(ScreenId.ServiceAccess, "service_access", "ServiceAccess"), + Describe(ScreenId.Settings, "settings", "Settings"), + ]; + + // Защита от рассинхронизации host-кода и уже выпущенного JSON-контракта. + // Эти элементы используются контроллерами напрямую и должны проверяться + // до активации DLC, иначе несовместимая тема сорвёт запуск приложения. + private static readonly IReadOnlyDictionary RuntimeBindings = + new Dictionary + { + [ScreenId.Home] = + [ + new( + "home.scroll.content.advertisement_panel", + "Control", + "SafeMargin/Scroll/Content/AdvertisementPanel"), + new("home.scroll.content.stock_status.meter.empty", "Control", string.Empty, Required: false), + new("home.scroll.content.stock_status.meter.low", "Control", string.Empty, Required: false), + new("home.scroll.content.stock_status.meter.enough", "Control", string.Empty, Required: false), + new("home.scroll.content.stock_status.meter.much", "Control", string.Empty, Required: false), + new( + "home.scroll.content.stock_status.approximate_count", + "Label", + "SafeMargin/Scroll/Content/StockStatus/Margin/Content/AvailabilityRow/ApproximateCount"), + new("home.decoration.custom_text_block", "CanvasItem", string.Empty, Required: false), + new("home.decoration.right_character", "CanvasItem", string.Empty, Required: false), + ], + [ScreenId.CardAmount] = + [ + new( + "card_amount.content.reward_panel.content.bonus", + "Label", + "SafeMargin/Content/RewardPanel/Content/Bonus"), + new( + "card_amount.content.top_bar.home_navigation_button", + "Button", + "SafeMargin/Content/TopBar/HomeNavigationButton"), + ], + [ScreenId.CashPayment] = + [ + new( + "cash_payment.content.banner_text", + "Label", + "SafeMargin/Content/BannerText"), + new( + "cash_payment.content.top_bar.home_navigation_button", + "Button", + "SafeMargin/Content/TopBar/HomeNavigationButton"), + ], + [ScreenId.CardCustomAmount] = + [ + new( + "card_custom_amount.content.top_bar.home_navigation_button", + "Button", + "SafeMargin/Content/TopBar/HomeNavigationButton"), + ], + [ScreenId.CardTerminal] = + [ + new( + "card_terminal.content.top_bar.home_navigation_button", + "Button", + "SafeMargin/Content/TopBar/HomeNavigationButton"), + ], + [ScreenId.Success] = + [ + new( + "success.content.home_navigation_button", + "Button", + "SafeMargin/Content/HomeNavigationButton"), + ], + [ScreenId.Error] = + [ + new( + "error.content.home_navigation_button", + "Button", + "SafeMargin/Content/HomeNavigationButton"), + ], + [ScreenId.ServiceAccess] = + [ + new( + "service_access.content.home_navigation_button", + "Button", + "SafeMargin/Content/HomeNavigationButton"), + ], + [ScreenId.Settings] = + [ + new( + "settings.scroll.content.animated_banner_texts_panel", + "Control", + "SafeMargin/Scroll/Content/AnimatedBannerTextsPanel"), + new( + "settings.scroll.content.menu_visibility_panel", + "Control", + "SafeMargin/Scroll/Content/MenuVisibilityPanel"), + new( + "settings.scroll.content.menu_visibility_panel.margin.content.show_stock_status", + "CheckButton", + "SafeMargin/Scroll/Content/MenuVisibilityPanel/Margin/Content/ShowStockStatus"), + new( + "settings.scroll.content.menu_visibility_panel.margin.content.show_right_character", + "CheckButton", + "SafeMargin/Scroll/Content/MenuVisibilityPanel/Margin/Content/ShowRightCharacter"), + new( + "settings.scroll.content.menu_visibility_panel.margin.content.show_promotion_block", + "CheckButton", + "SafeMargin/Scroll/Content/MenuVisibilityPanel/Margin/Content/ShowPromotionBlock"), + new( + "settings.scroll.content.menu_visibility_panel.margin.content.show_interactive_pet", + "CheckButton", + "SafeMargin/Scroll/Content/MenuVisibilityPanel/Margin/Content/ShowInteractivePet"), + new( + "settings.scroll.content.advertisement_poster_panel.margin.content.select_button", + "Button", + "SafeMargin/Scroll/Content/AdvertisementPosterPanel/Margin/Content/SelectButton"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.hopper1_label", + "Label", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/Hopper1Label"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.description", + "Label", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/Description"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.inventory_enabled", + "CheckButton", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/InventoryAccountingEnabled"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.purchase_limit_enabled", + "CheckButton", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/PurchaseLimitEnabled"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.hopper1.recount_button", + "Button", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/Hopper1/RecountButton"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.hopper1.manual_add_button", + "Button", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/Hopper1/ManualAddButton"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.hopper2_label", + "Label", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/Hopper2Label"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.hopper2.recount_button", + "Button", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/Hopper2/RecountButton"), + new( + "settings.scroll.content.service_inventory_panel.margin.content.hopper2.manual_add_button", + "Button", + "SafeMargin/Scroll/Content/ServiceInventoryPanel/Margin/Content/Hopper2/ManualAddButton"), + new( + "settings.scroll.content.footer_clearance", + "Control", + "SafeMargin/Scroll/Content/FooterClearance"), + new( + "settings.footer", + "Control", + "Footer"), + new( + "settings.footer.save_and_exit_button", + "Button", + "Footer/SaveAndExitButton"), + ], + }; + + internal static IReadOnlyList GetFallbackBindings( + ScreenId screenId, + ThemeScreenBindingContract bindingContract) + { + ArgumentNullException.ThrowIfNull(bindingContract); + var result = new List(bindingContract.Bindings.Length + 12); + result.AddRange(bindingContract.Bindings.Select(binding => new FallbackBindingRequirement( + binding.Id, + binding.Types, + binding.FallbackPath, + binding.Required))); + + if (RuntimeBindings.TryGetValue(screenId, out RuntimeBindingRequirement[]? runtimeBindings)) + { + result.AddRange(runtimeBindings.Select(binding => new FallbackBindingRequirement( + binding.Id, + [binding.Type], + binding.FallbackPath, + binding.Required))); + } + + return result; + } + + public static bool TryGetByBindingId(string bindingId, out ThemeScreenDescriptor descriptor) + { + foreach (ThemeScreenDescriptor candidate in Screens) + { + if (candidate.BindingId.Equals(bindingId, StringComparison.Ordinal)) + { + descriptor = candidate; + return true; + } + } + + descriptor = default; + return false; + } + + public static ThemeScreenSceneFailure ValidateScene( + PackedScene? packedScene, + ThemeScreenDescriptor descriptor, + ThemeScreenBindingContract? bindingContract = null) + => ValidateScene(packedScene, descriptor, bindingContract, out _); + + public static ThemeScreenSceneFailure ValidateScene( + PackedScene? packedScene, + ThemeScreenDescriptor descriptor, + ThemeScreenBindingContract? bindingContract, + out bool selfContainedVisuals) + { + selfContainedVisuals = false; + if (packedScene is null) + { + return ThemeScreenSceneFailure.MissingScene; + } + + Node root = packedScene.Instantiate(); + try + { + if (root is not Control) + { + return ThemeScreenSceneFailure.WrongRootType; + } + + if (!root.Name.ToString().Equals(descriptor.RootName, StringComparison.Ordinal)) + { + return ThemeScreenSceneFailure.WrongRootName; + } + + if (!TryReadMetadata(root, ScreenBindingMetadata, out string screenBinding) + || !screenBinding.Equals(descriptor.BindingId, StringComparison.Ordinal)) + { + return ThemeScreenSceneFailure.MissingScreenBinding; + } + + if (!TryReadOptionalBooleanMetadata( + root, + SelfContainedVisualsMetadata, + out selfContainedVisuals)) + { + return ThemeScreenSceneFailure.InvalidSelfContainedMetadata; + } + + if (selfContainedVisuals) + { + var themedRoot = (Control)root; + if (themedRoot.Theme is null) + { + return ThemeScreenSceneFailure.MissingSelfContainedTheme; + } + + TextureRect? background = root.GetNodeOrNull(SelfContainedBackgroundNode); + if (background?.Texture is null) + { + return ThemeScreenSceneFailure.MissingSelfContainedBackground; + } + + CanvasItem? decoration = root.GetNodeOrNull(SelfContainedDecorationNode); + if (decoration is null) + { + return ThemeScreenSceneFailure.MissingSelfContainedDecoration; + } + } + + var elementBindings = new Dictionary(StringComparer.Ordinal); + foreach (Node node in EnumerateTree(root)) + { + if (!TryReadMetadata(node, ElementBindingMetadata, out string elementBinding)) + { + continue; + } + + if (!IsValidElementBinding(descriptor.Key, elementBinding)) + { + return ThemeScreenSceneFailure.InvalidElementBinding; + } + + if (!elementBindings.TryAdd(elementBinding, node)) + { + return ThemeScreenSceneFailure.DuplicateElementBinding; + } + } + + if (elementBindings.Count == 0 && bindingContract is null) + { + return ThemeScreenSceneFailure.MissingElementBinding; + } + + if (bindingContract is not null) + { + var expectedBindings = new HashSet( + bindingContract.Bindings.Select(binding => binding.Id), + StringComparer.Ordinal); + if (RuntimeBindings.TryGetValue( + descriptor.ScreenId, + out RuntimeBindingRequirement[]? supplementalBindings)) + { + expectedBindings.UnionWith( + supplementalBindings.Select(requirement => requirement.Id)); + } + + if (elementBindings.Keys.Any(binding => !expectedBindings.Contains(binding))) + { + return ThemeScreenSceneFailure.UnexpectedElementBinding; + } + + foreach (ThemeBindingRequirement requirement in bindingContract.Bindings) + { + if (!elementBindings.TryGetValue(requirement.Id, out Node? node)) + { + continue; + } + + if (!requirement.Types.Any(type => node.IsClass(type))) + { + return ThemeScreenSceneFailure.WrongBindingType; + } + } + } + + if (RuntimeBindings.TryGetValue(descriptor.ScreenId, out RuntimeBindingRequirement[]? runtimeBindings)) + { + foreach (RuntimeBindingRequirement requirement in runtimeBindings) + { + if (!elementBindings.TryGetValue(requirement.Id, out Node? node)) + { + if (requirement.Required && string.IsNullOrWhiteSpace(requirement.FallbackPath)) + { + return ThemeScreenSceneFailure.MissingRequiredBinding; + } + + continue; + } + + if (!node.IsClass(requirement.Type)) + { + return ThemeScreenSceneFailure.WrongBindingType; + } + } + } + + return ThemeScreenSceneFailure.None; + } + finally + { + root.Free(); + } + } + + private static ThemeScreenDescriptor Describe(ScreenId id, string key, string pascalName) + { + return new ThemeScreenDescriptor( + id, + $"screen.{key}", + key, + $"{ThemeDlcManifestValidator.ResourceRoot}scenes/screen_{key}.tscn", + $"ThemeScreen_{pascalName}"); + } + + internal static bool IsValidElementBinding(string screenKey, string binding) + { + if (binding.Length is < 3 or > 240 + || !binding.StartsWith(screenKey + ".", StringComparison.Ordinal)) + { + return false; + } + + foreach (char character in binding) + { + if (!char.IsAsciiLetterOrDigit(character) && character is not ('.' or '_')) + { + return false; + } + } + + return true; + } + + internal static bool IsCompatibleVisualComposition( + bool selfContainedVisuals, + string backgroundTexturePath, + string backgroundDecorationPath) + { + return !selfContainedVisuals + || (string.IsNullOrWhiteSpace(backgroundTexturePath) + && string.IsNullOrWhiteSpace(backgroundDecorationPath)); + } + + private static bool TryReadMetadata(Node node, string key, out string value) + { + value = string.Empty; + if (!node.HasMeta(key)) + { + return false; + } + + value = node.GetMeta(key).AsString().Trim(); + return value.Length > 0; + } + + private static bool TryReadOptionalBooleanMetadata(Node node, string key, out bool value) + { + value = false; + if (!node.HasMeta(key)) + { + return true; + } + + Variant metadata = node.GetMeta(key); + if (metadata.VariantType != Variant.Type.Bool) + { + return false; + } + + value = metadata.AsBool(); + return true; + } + + private static IEnumerable EnumerateTree(Node root) + { + yield return root; + foreach (Node child in root.GetChildren()) + { + foreach (Node descendant in EnumerateTree(child)) + { + yield return descendant; + } + } + } +} diff --git a/src/core/ThemeManager/ThemeSceneContract.cs.uid b/src/core/ThemeManager/ThemeSceneContract.cs.uid new file mode 100644 index 0000000..0d27720 --- /dev/null +++ b/src/core/ThemeManager/ThemeSceneContract.cs.uid @@ -0,0 +1 @@ +uid://bgy6o5osqkdn diff --git a/src/core/ThemeManager/ThemeSemanticTypes.cs b/src/core/ThemeManager/ThemeSemanticTypes.cs new file mode 100644 index 0000000..0e4c8bb --- /dev/null +++ b/src/core/ThemeManager/ThemeSemanticTypes.cs @@ -0,0 +1,53 @@ +using Godot; + +namespace Exchanger.Core.Theming; + +/// +/// Стабильные семантические типы host-интерфейса. Внешняя DLC-тема оформляет +/// их без привязки к именам узлов и структуре конкретной сцены. +/// +public static class ThemeSemanticTypes +{ + public static readonly StringName ScreenTitle = "ScreenTitle"; + public static readonly StringName ScreenDescription = "ScreenDescription"; + public static readonly StringName PanelTitle = "PanelTitle"; + public static readonly StringName PanelText = "PanelText"; + public static readonly StringName FieldLabel = "FieldLabel"; + public static readonly StringName SupportText = "SupportText"; + public static readonly StringName StatusText = "StatusText"; + public static readonly StringName WarningText = "WarningText"; + public static readonly StringName ErrorText = "ErrorText"; + public static readonly StringName PrimaryButton = "PrimaryButton"; + public static readonly StringName CompactButton = "CompactButton"; + public static readonly StringName BackButton = "BackButton"; + public static readonly StringName SectionTabButton = "SectionTabButton"; + public static readonly StringName SecondaryButton = "SecondaryButton"; + public static readonly StringName DangerButton = "DangerButton"; + public static readonly StringName WhitePanel = "WhitePanel"; + public static readonly StringName AdvertisementPanel = "AdvertisementPanel"; + public static readonly StringName FooterPanel = "FooterPanel"; + public static readonly StringName StatusPanel = "StatusPanel"; + + public static void RegisterFallbackBaseTypes(Theme theme) + { + theme.SetTypeVariation(ScreenTitle, "Label"); + theme.SetTypeVariation(ScreenDescription, "Label"); + theme.SetTypeVariation(PanelTitle, "Label"); + theme.SetTypeVariation(PanelText, "Label"); + theme.SetTypeVariation(FieldLabel, "Label"); + theme.SetTypeVariation(SupportText, "Label"); + theme.SetTypeVariation(StatusText, "Label"); + theme.SetTypeVariation(WarningText, "Label"); + theme.SetTypeVariation(ErrorText, "Label"); + theme.SetTypeVariation(PrimaryButton, "Button"); + theme.SetTypeVariation(CompactButton, "Button"); + theme.SetTypeVariation(BackButton, "Button"); + theme.SetTypeVariation(SectionTabButton, "Button"); + theme.SetTypeVariation(SecondaryButton, "Button"); + theme.SetTypeVariation(DangerButton, "Button"); + theme.SetTypeVariation(WhitePanel, "PanelContainer"); + theme.SetTypeVariation(AdvertisementPanel, "PanelContainer"); + theme.SetTypeVariation(FooterPanel, "PanelContainer"); + theme.SetTypeVariation(StatusPanel, "PanelContainer"); + } +} diff --git a/src/core/ThemeManager/ThemeSemanticTypes.cs.uid b/src/core/ThemeManager/ThemeSemanticTypes.cs.uid new file mode 100644 index 0000000..54b4704 --- /dev/null +++ b/src/core/ThemeManager/ThemeSemanticTypes.cs.uid @@ -0,0 +1 @@ +uid://c7hgume8ckmgl diff --git a/src/core/ThemeManager/VendingThemeDefinition.cs b/src/core/ThemeManager/VendingThemeDefinition.cs new file mode 100644 index 0000000..e45857a --- /dev/null +++ b/src/core/ThemeManager/VendingThemeDefinition.cs @@ -0,0 +1,51 @@ +using Godot; +using Exchanger.Core.Navigation; +using System.Collections.Generic; + +namespace Exchanger.Core.Theming; + +/// +/// Единое описание визуальной темы: стили Control, статический фон и +/// необязательные тематические 2D-декорации. +/// +[GlobalClass] +public partial class VendingThemeDefinition : Resource +{ + [Export] + public string ThemeId { get; set; } = "base"; + + [Export] + public string DisplayName { get; set; } = "Базовая"; + + [Export] + public Theme? UiTheme { get; set; } + + [Export] + public Texture2D? BackgroundTexture { get; set; } + + [Export] + public PackedScene? BackgroundDecoration { get; set; } + + [Export] + public PackedScene? InteractivePetScene { get; set; } + + public float BackgroundDecorationScale { get; set; } = 1f; + + [Export] + public Color FallbackColor { get; set; } = new("101827"); + + [Export] + public bool UseNearestTextureFilter { get; set; } + + public IReadOnlyDictionary VisualSlots { get; set; } + = new Dictionary(); + + public IReadOnlyDictionary ScreenScenes { get; set; } + = new Dictionary(); + + public IReadOnlyDictionary ScreenBindingContracts { get; set; } + = new Dictionary(); + + public bool SelfContainedScreenVisuals { get; set; } + +} diff --git a/src/core/ThemeManager/VendingThemeDefinition.cs.uid b/src/core/ThemeManager/VendingThemeDefinition.cs.uid new file mode 100644 index 0000000..c88cf85 --- /dev/null +++ b/src/core/ThemeManager/VendingThemeDefinition.cs.uid @@ -0,0 +1 @@ +uid://8k6iouciutid diff --git a/src/hardware/Abstractions/DualHopperDispensePlanner.cs b/src/hardware/Abstractions/DualHopperDispensePlanner.cs new file mode 100644 index 0000000..23a6feb --- /dev/null +++ b/src/hardware/Abstractions/DualHopperDispensePlanner.cs @@ -0,0 +1,36 @@ +using System; + +namespace Exchanger.Hardware.Abstractions; + +public readonly record struct DualHopperDispensePlan(int Hopper1Count, int Hopper2Count) +{ + public int TotalCount => Hopper1Count + Hopper2Count; +} + +public static class DualHopperDispensePlanner +{ + public static bool TryCreate( + int requestedCount, + int hopper1Inventory, + int hopper2Inventory, + out DualHopperDispensePlan plan) + { + plan = default; + if (requestedCount <= 0) + { + return false; + } + + int availableInHopper1 = Math.Max(0, hopper1Inventory); + int availableInHopper2 = Math.Max(0, hopper2Inventory); + if ((long)availableInHopper1 + availableInHopper2 < requestedCount) + { + return false; + } + + int fromHopper1 = Math.Min(requestedCount, availableInHopper1); + int fromHopper2 = requestedCount - fromHopper1; + plan = new DualHopperDispensePlan(fromHopper1, fromHopper2); + return true; + } +} diff --git a/src/hardware/Abstractions/DualHopperDispensePlanner.cs.uid b/src/hardware/Abstractions/DualHopperDispensePlanner.cs.uid new file mode 100644 index 0000000..5443ca5 --- /dev/null +++ b/src/hardware/Abstractions/DualHopperDispensePlanner.cs.uid @@ -0,0 +1 @@ +uid://chdhj2yp4yjiv diff --git a/src/hardware/Abstractions/HardwareReconnectScheduler.cs b/src/hardware/Abstractions/HardwareReconnectScheduler.cs new file mode 100644 index 0000000..f212bfb --- /dev/null +++ b/src/hardware/Abstractions/HardwareReconnectScheduler.cs @@ -0,0 +1,56 @@ +using System; + +namespace Exchanger.Hardware.Abstractions; + +/// +/// Планирует повторные попытки подключения по монотонному времени. +/// После каждого обрыва и каждой попытки выдерживается полный настроенный интервал. +/// +internal sealed class HardwareReconnectScheduler +{ + private readonly ulong _intervalMilliseconds; + private ulong _nextAttemptAt; + private bool _connectionObserved; + private bool _wasConnected; + + public HardwareReconnectScheduler(int intervalSeconds) + { + if (intervalSeconds <= 0) + { + throw new ArgumentOutOfRangeException(nameof(intervalSeconds)); + } + + _intervalMilliseconds = checked((ulong)intervalSeconds * 1000UL); + } + + public void ScheduleFrom(ulong nowMilliseconds) + { + _nextAttemptAt = ulong.MaxValue - nowMilliseconds < _intervalMilliseconds + ? ulong.MaxValue + : nowMilliseconds + _intervalMilliseconds; + } + + public bool ObserveConnection(bool isConnected, ulong nowMilliseconds) + { + bool disconnectedNow = _connectionObserved && _wasConnected && !isConnected; + _connectionObserved = true; + _wasConnected = isConnected; + if (disconnectedNow) + { + ScheduleFrom(nowMilliseconds); + } + + return disconnectedNow; + } + + public bool TryBeginAttempt(ulong nowMilliseconds) + { + if (nowMilliseconds < _nextAttemptAt) + { + return false; + } + + ScheduleFrom(nowMilliseconds); + return true; + } +} diff --git a/src/hardware/Abstractions/HardwareReconnectScheduler.cs.uid b/src/hardware/Abstractions/HardwareReconnectScheduler.cs.uid new file mode 100644 index 0000000..12ac34a --- /dev/null +++ b/src/hardware/Abstractions/HardwareReconnectScheduler.cs.uid @@ -0,0 +1 @@ +uid://c68462dcm86sn diff --git a/src/hardware/Abstractions/HopperChannel.cs b/src/hardware/Abstractions/HopperChannel.cs new file mode 100644 index 0000000..cbd0cca --- /dev/null +++ b/src/hardware/Abstractions/HopperChannel.cs @@ -0,0 +1,7 @@ +namespace Exchanger.Hardware.Abstractions; + +public enum HopperChannel +{ + Hopper1 = 1, + Hopper2 = 2, +} diff --git a/src/hardware/Abstractions/HopperChannel.cs.uid b/src/hardware/Abstractions/HopperChannel.cs.uid new file mode 100644 index 0000000..9b94b05 --- /dev/null +++ b/src/hardware/Abstractions/HopperChannel.cs.uid @@ -0,0 +1 @@ +uid://dfcny0nlbvdic diff --git a/src/hardware/Abstractions/IDualHopperController.cs b/src/hardware/Abstractions/IDualHopperController.cs new file mode 100644 index 0000000..63266cf --- /dev/null +++ b/src/hardware/Abstractions/IDualHopperController.cs @@ -0,0 +1,42 @@ +using System; + +namespace Exchanger.Hardware.Abstractions; + +/// Раздельные датчики, маршрутизация выдачи и учёт подтверждений двух хопперов. +public interface IDualHopperMachineController +{ + MachineStockLevel Hopper1StockLevel { get; } + + MachineStockLevel Hopper2StockLevel { get; } + + event Action? HopperStockChanged; + + /// Сообщает контроллеру точный учётный остаток для безопасного выбора хоппера. + void SetHopperInventory(int hopper1Count, int hopper2Count); + + /// + /// При отключённом учёте точный остаток не ограничивает выдачу; DualHopperAuto + /// использует приоритетный первый хоппер без небезопасного автоматического failover. + /// + void SetInventoryAccountingEnabled(bool enabled); + + void SetPurchaseLimitEnabled(bool enabled); + + /// Фактически подтверждённое распределение завершившейся выдачи. + event Action? HopperDispenseAccounted; + + /// Прогресс текущей выдачи: подтверждённое и запрошенное количество жетонов. + event Action? DispenseProgressChanged; +} + +/// Раздельный сервисный пересчёт каждого хоппера. +public interface IDualHopperTokenRecountController +{ + bool CanStartHopperTokenRecount(HopperChannel hopper); + + event Action? HopperTokenRecountProgressChanged; + + event Action? HopperTokenRecountFinished; + + bool TryStartTokenRecount(HopperChannel hopper, ulong nowMilliseconds); +} diff --git a/src/hardware/Abstractions/IDualHopperController.cs.uid b/src/hardware/Abstractions/IDualHopperController.cs.uid new file mode 100644 index 0000000..cc5ffff --- /dev/null +++ b/src/hardware/Abstractions/IDualHopperController.cs.uid @@ -0,0 +1 @@ +uid://do52p1hcrr4q6 diff --git a/src/hardware/Abstractions/IHardwarePort.cs b/src/hardware/Abstractions/IHardwarePort.cs new file mode 100644 index 0000000..b69c809 --- /dev/null +++ b/src/hardware/Abstractions/IHardwarePort.cs @@ -0,0 +1,27 @@ +using System; + +namespace Exchanger.Hardware.Abstractions; + +/// +/// Платформонезависимый транспорт контроллера вендингового аппарата. +/// +public interface IHardwarePort +{ + bool IsConnected { get; } + + void Connect(string portName, int baudRate); + + void Disconnect(); + + void SendCommand(string command); + + /// + /// Доставляет накопленные фоновым транспортом события в вызывающий поток. + /// В Godot должен вызываться только из главного потока. + /// + void ProcessPendingEvents(); + + event Action? OnDataReceived; + + event Action? ConnectionChanged; +} diff --git a/src/hardware/Abstractions/IHardwarePort.cs.uid b/src/hardware/Abstractions/IHardwarePort.cs.uid new file mode 100644 index 0000000..ef221ff --- /dev/null +++ b/src/hardware/Abstractions/IHardwarePort.cs.uid @@ -0,0 +1 @@ +uid://cmk1740l7vkcy diff --git a/src/hardware/Abstractions/IMachineController.cs b/src/hardware/Abstractions/IMachineController.cs new file mode 100644 index 0000000..2086444 --- /dev/null +++ b/src/hardware/Abstractions/IMachineController.cs @@ -0,0 +1,36 @@ +using System; + +namespace Exchanger.Hardware.Abstractions; + +/// +/// Типизированная граница бизнес-логики и автомата. Будущий wire-протокол +/// преобразуется в эти события отдельным адаптером. +/// +public interface IMachineController +{ + MachineStockLevel StockLevel { get; } + + MachineConnectionState ConnectionState { get; } + + event Action? ConnectionStateChanged; + + event Action? StockChanged; + + event Action? CashBalanceChanged; + + event Action? CardPaymentFinished; + + event Action? DispenseFinished; + + event Action? FaultOccurred; + + void BeginCashAcceptance(); + + void EndCashAcceptance(); + + void BeginCardPayment(int amountRubles); + + void CancelActiveOperation(); + + void DispenseTokens(int tokenCount); +} diff --git a/src/hardware/Abstractions/IMachineController.cs.uid b/src/hardware/Abstractions/IMachineController.cs.uid new file mode 100644 index 0000000..415eea9 --- /dev/null +++ b/src/hardware/Abstractions/IMachineController.cs.uid @@ -0,0 +1 @@ +uid://dq4thsh54ex18 diff --git a/src/hardware/Abstractions/ITokenRecountController.cs b/src/hardware/Abstractions/ITokenRecountController.cs new file mode 100644 index 0000000..af2fcab --- /dev/null +++ b/src/hardware/Abstractions/ITokenRecountController.cs @@ -0,0 +1,22 @@ +using System; + +namespace Exchanger.Hardware.Abstractions; + +/// +/// Сервисный прямой пересчёт жетонов. В отличие от обычной выдачи включает +/// двигатель хоппера напрямую и считает фронты аппаратного датчика выдачи. +/// +public interface ITokenRecountController +{ + bool IsTokenRecountInProgress { get; } + + bool CanStartTokenRecount { get; } + + event Action? TokenRecountProgressChanged; + + event Action? TokenRecountFinished; + + bool TryStartTokenRecount(ulong nowMilliseconds); + + void CancelTokenRecount(); +} diff --git a/src/hardware/Abstractions/ITokenRecountController.cs.uid b/src/hardware/Abstractions/ITokenRecountController.cs.uid new file mode 100644 index 0000000..ad98d26 --- /dev/null +++ b/src/hardware/Abstractions/ITokenRecountController.cs.uid @@ -0,0 +1 @@ +uid://cah5f7n8hfbu0 diff --git a/src/hardware/Abstractions/MachineEvents.cs b/src/hardware/Abstractions/MachineEvents.cs new file mode 100644 index 0000000..cca0805 --- /dev/null +++ b/src/hardware/Abstractions/MachineEvents.cs @@ -0,0 +1,27 @@ +namespace Exchanger.Hardware.Abstractions; + +public enum MachineCardResult +{ + Approved, + Declined, + Cancelled, + Timeout, +} + +public enum MachineFault +{ + ConnectionLost, + Unavailable, +} + +/// +/// Безопасное сервисное состояние канала связи с автоматом. Не содержит +/// имени COM-порта, сырых ответов контроллера или деталей handshake. +/// +public enum MachineConnectionState +{ + Disconnected, + Authenticating, + Ready, + Faulted, +} diff --git a/src/hardware/Abstractions/MachineEvents.cs.uid b/src/hardware/Abstractions/MachineEvents.cs.uid new file mode 100644 index 0000000..4dc3d2e --- /dev/null +++ b/src/hardware/Abstractions/MachineEvents.cs.uid @@ -0,0 +1 @@ +uid://c1tk7hbv6nso5 diff --git a/src/hardware/Abstractions/MachineStock.cs b/src/hardware/Abstractions/MachineStock.cs new file mode 100644 index 0000000..6e2dafd --- /dev/null +++ b/src/hardware/Abstractions/MachineStock.cs @@ -0,0 +1,8 @@ +namespace Exchanger.Hardware.Abstractions; + +public enum MachineStockLevel +{ + Unknown, + Enough, + Low, +} diff --git a/src/hardware/Abstractions/MachineStock.cs.uid b/src/hardware/Abstractions/MachineStock.cs.uid new file mode 100644 index 0000000..037b4fe --- /dev/null +++ b/src/hardware/Abstractions/MachineStock.cs.uid @@ -0,0 +1 @@ +uid://bqqescnsgl6ij diff --git a/src/hardware/MockHardware/MockHardwarePort.cs b/src/hardware/MockHardware/MockHardwarePort.cs new file mode 100644 index 0000000..0d7b5fb --- /dev/null +++ b/src/hardware/MockHardware/MockHardwarePort.cs @@ -0,0 +1,56 @@ +using Exchanger.Core.Logging; +using Exchanger.Hardware.Abstractions; +using System; + +namespace Exchanger.Hardware.MockHardware; + +/// +/// Детерминированная заглушка контроллера для разработки без физического COM-порта. +/// +public sealed class MockHardwarePort : IHardwarePort +{ + public bool IsConnected { get; private set; } + + public event Action? OnDataReceived; + + public event Action? ConnectionChanged; + + public void Connect(string portName, int baudRate) + { + IsConnected = true; + ConnectionChanged?.Invoke(true); + AppLogger.Info("MockHardware", $"Подключена имитация порта {portName} @ {baudRate}."); + } + + public void Disconnect() + { + if (!IsConnected) + { + return; + } + + IsConnected = false; + ConnectionChanged?.Invoke(false); + AppLogger.Info("MockHardware", "Имитация порта отключена."); + } + + public void SendCommand(string command) + { + string normalized = command.Trim(); + AppLogger.Info("MockHardware", $"Команда: {normalized}"); + + if (!IsConnected) + { + OnDataReceived?.Invoke("ERROR:NOT_CONNECTED"); + return; + } + + OnDataReceived?.Invoke(normalized.StartsWith("DISPENSE:", StringComparison.OrdinalIgnoreCase) + ? "OK" + : "OK"); + } + + public void ProcessPendingEvents() + { + } +} diff --git a/src/hardware/MockHardware/MockHardwarePort.cs.uid b/src/hardware/MockHardware/MockHardwarePort.cs.uid new file mode 100644 index 0000000..3883079 --- /dev/null +++ b/src/hardware/MockHardware/MockHardwarePort.cs.uid @@ -0,0 +1 @@ +uid://d3oo5v16pblg8 diff --git a/src/hardware/MockHardware/PeripheryControllerSimulator.cs b/src/hardware/MockHardware/PeripheryControllerSimulator.cs new file mode 100644 index 0000000..8bb2a34 --- /dev/null +++ b/src/hardware/MockHardware/PeripheryControllerSimulator.cs @@ -0,0 +1,281 @@ +using Exchanger.Hardware.Abstractions; +using Exchanger.Hardware.PeripheryController; +using System; +using System.Collections.Generic; +using System.Globalization; + +namespace Exchanger.Hardware.MockHardware; + +/// +/// Детерминированный wire-симулятор документированной части протокола 2.3.5. +/// Прогоняет настоящий handshake и ASCII parser, но не предполагает форматы, +/// отсутствующие в спецификации производителя. +/// +public sealed class PeripheryControllerSimulator : IHardwarePort +{ + private static readonly byte[] ControllerChallenge = + Convert.FromHexString("FFEEDDCCBBAA99887766554433221100"); + + private readonly IControllerBlockCipher _cipher; + private readonly Queue _incomingFrames = new(); + private string _expectedChallengeResponse = string.Empty; + private string _controllerProof = string.Empty; + private bool _failNextDispense; + private int _confirmedPulsesBeforeFailure; + + public PeripheryControllerSimulator(IControllerBlockCipher cipher) + { + _cipher = cipher ?? throw new ArgumentNullException(nameof(cipher)); + } + + public bool IsConnected { get; private set; } + + public int DigitalInputMask { get; set; } = 67_108_863; + + public List SentCommands { get; } = new(); + + public event Action? OnDataReceived; + + public event Action? ConnectionChanged; + + public void Connect(string portName, int baudRate) + { + if (IsConnected) + { + return; + } + + IsConnected = true; + ConnectionChanged?.Invoke(true); + QueueFrame("periphery controller ver_simulator"); + } + + public void Disconnect() + { + if (!IsConnected) + { + return; + } + + IsConnected = false; + _incomingFrames.Clear(); + _expectedChallengeResponse = string.Empty; + _controllerProof = string.Empty; + ConnectionChanged?.Invoke(false); + } + + public void SendCommand(string command) + { + if (!IsConnected) + { + throw new InvalidOperationException("Wire-симулятор не подключён."); + } + + string normalized = (command ?? string.Empty).Trim(); + SentCommands.Add(normalized); + + if (TryHandleAuthenticationRequest(normalized) + || TryHandleAuthenticationResponse(normalized)) + { + return; + } + + if (normalized == PeripheryProtocolCommands.QueryDigitalInputs) + { + QueueFrame($"INPUT {DigitalInputMask.ToString(CultureInfo.InvariantCulture)}"); + return; + } + + if (normalized == PeripheryProtocolCommands.QueryHopper1Credit) + { + QueueFrame("HOPPER1 CREDIT=0"); + return; + } + + if (normalized.StartsWith("309", StringComparison.Ordinal) + && int.TryParse(normalized[3..], NumberStyles.None, CultureInfo.InvariantCulture, out int count)) + { + if (count is >= 1 and <= PeripheryProtocolCommands.MaxHopperDispenseBatch) + { + QueueDispenseResult(count); + } + else + { + QueueFrame("ERROR:30:invalid count (0-99)"); + } + + return; + } + + if (normalized == PeripheryProtocolCommands.QueryHopper2Credit) + { + QueueFrame("HOPPER2 CREDIT=0"); + return; + } + + if (normalized.StartsWith("409", StringComparison.Ordinal) + && int.TryParse(normalized[3..], NumberStyles.None, CultureInfo.InvariantCulture, out int hopper2Count)) + { + if (hopper2Count is >= 1 and <= PeripheryProtocolCommands.MaxHopperDispenseBatch) + { + QueueHopper2DispenseResult(hopper2Count); + } + else + { + QueueFrame("ERROR:40:invalid count (0-99)"); + } + } + } + + public void ProcessPendingEvents() + { + while (_incomingFrames.Count > 0 && IsConnected) + { + string frame = _incomingFrames.Dequeue(); + OnDataReceived?.Invoke(frame); + } + } + + public void ReportCoins(int amountRubles) => QueueMoney("COINS", amountRubles); + + public void ReportBill(int amountRubles) => QueueMoney("BILL", amountRubles); + + public void ReportCashless(int amountRubles) => QueueMoney("CASHLESS", amountRubles); + + public void ReportServiceRequest() => QueueFrame("SERVICE"); + + public void InjectFrame(string frame) => QueueFrame(frame); + + public void FailNextDispenseAfter(int confirmedPulses = 0) + { + _failNextDispense = true; + _confirmedPulsesBeforeFailure = Math.Max(0, confirmedPulses); + } + + private bool TryHandleAuthenticationRequest(string command) + { + if (command.Length != 34 || !command.StartsWith("07", StringComparison.Ordinal)) + { + return false; + } + + if (!TryParseHexBlock(command[2..], out byte[] hostChallenge)) + { + QueueFrame("ERROR:AUTH_FORMAT"); + return true; + } + + QueueFrame("CHAL" + Convert.ToHexString(ControllerChallenge)); + _expectedChallengeResponse = "08" + Convert.ToHexString(_cipher.EncryptBlock(ControllerChallenge)); + _controllerProof = "RAES" + Convert.ToHexString(_cipher.EncryptBlock(hostChallenge)); + return true; + } + + private bool TryHandleAuthenticationResponse(string command) + { + if (!command.StartsWith("08", StringComparison.Ordinal)) + { + return false; + } + + if (_expectedChallengeResponse.Length > 0 + && command.Equals(_expectedChallengeResponse, StringComparison.Ordinal)) + { + _expectedChallengeResponse = string.Empty; + QueueFrame(_controllerProof); + QueueFrame("AUTH_PC_OK"); + QueueFrame("READY!"); + _controllerProof = string.Empty; + } + else + { + QueueFrame("ERROR:AUTH_PROOF"); + } + + return true; + } + + private void QueueDispenseResult(int requestedCount) + { + QueueFrame($"HOPPER1 APPEND={requestedCount.ToString(CultureInfo.InvariantCulture)}"); + if (!_failNextDispense) + { + for (int index = 0; index < requestedCount; index++) + { + QueueFrame("HOPPER1 OK"); + } + + return; + } + + int confirmed = Math.Min(requestedCount, _confirmedPulsesBeforeFailure); + for (int index = 0; index < confirmed; index++) + { + QueueFrame("HOPPER1 OK"); + } + + QueueFrame("HOPPER1 ERROR"); + QueueFrame($"HOPPER1 CREDIT={(requestedCount - confirmed).ToString(CultureInfo.InvariantCulture)}"); + _failNextDispense = false; + _confirmedPulsesBeforeFailure = 0; + } + + private void QueueHopper2DispenseResult(int requestedCount) + { + QueueFrame($"HOPPER2 APPEND={requestedCount.ToString(CultureInfo.InvariantCulture)}"); + if (!_failNextDispense) + { + for (int index = 0; index < requestedCount; index++) + { + QueueFrame("HOPPER2 OK"); + } + + return; + } + + int confirmed = Math.Min(requestedCount, _confirmedPulsesBeforeFailure); + for (int index = 0; index < confirmed; index++) + { + QueueFrame("HOPPER2 OK"); + } + + QueueFrame("HOPPER2 ERROR"); + QueueFrame($"HOPPER2 CREDIT={(requestedCount - confirmed).ToString(CultureInfo.InvariantCulture)}"); + _failNextDispense = false; + _confirmedPulsesBeforeFailure = 0; + } + + private void QueueMoney(string source, int amountRubles) + { + if (amountRubles <= 0) + { + throw new ArgumentOutOfRangeException(nameof(amountRubles)); + } + + QueueFrame($"MONEY:{source}:{amountRubles.ToString(CultureInfo.InvariantCulture)}"); + } + + private void QueueFrame(string frame) + { + if (!IsConnected) + { + throw new InvalidOperationException("Wire-симулятор не подключён."); + } + + _incomingFrames.Enqueue(frame ?? string.Empty); + } + + private static bool TryParseHexBlock(string value, out byte[] bytes) + { + try + { + bytes = Convert.FromHexString(value); + return bytes.Length == 16; + } + catch (FormatException) + { + bytes = Array.Empty(); + return false; + } + } +} diff --git a/src/hardware/MockHardware/PeripheryControllerSimulator.cs.uid b/src/hardware/MockHardware/PeripheryControllerSimulator.cs.uid new file mode 100644 index 0000000..9da5bc5 --- /dev/null +++ b/src/hardware/MockHardware/PeripheryControllerSimulator.cs.uid @@ -0,0 +1 @@ +uid://dvlyyb6io83th diff --git a/src/hardware/MockMachine/MockMachineController.cs b/src/hardware/MockMachine/MockMachineController.cs new file mode 100644 index 0000000..b6501e7 --- /dev/null +++ b/src/hardware/MockMachine/MockMachineController.cs @@ -0,0 +1,378 @@ +using Exchanger.Core.Logging; +using Exchanger.Hardware.Abstractions; +using Godot; +using System; + +namespace Exchanger.Hardware.MockMachine; + +/// +/// Детерминированный симулятор типизированных событий автомата. +/// Не имитирует и не предполагает формат будущего wire-протокола. +/// +public partial class MockMachineController : Node, IMachineController, ITokenRecountController, + IDualHopperMachineController, IDualHopperTokenRecountController +{ + private int _cashBalance; + private bool _cashAcceptanceActive; + private bool _cardPaymentActive; + private int _operationGeneration; + private string? _nextDispenseError; + private int? _nextPartialDispenseCount; + private bool _tokenRecountInProgress; + private int _tokenRecountCount; + private HopperChannel _tokenRecountHopper = HopperChannel.Hopper1; + private int _hopper1Inventory; + private int _hopper2Inventory; + private bool _inventoryAccountingEnabled = true; + private bool _purchaseLimitEnabled = true; + + [Export(PropertyHint.Range, "0.05,10,0.05")] + public double DispenseDelaySeconds { get; set; } = 0.7; + + [Export(PropertyHint.Range, "0,1000,1")] + public int MockRecountTokenCount { get; set; } = 12; + + public MachineStockLevel StockLevel { get; private set; } = MachineStockLevel.Enough; + + public MachineStockLevel Hopper1StockLevel { get; private set; } = MachineStockLevel.Enough; + + public MachineStockLevel Hopper2StockLevel { get; private set; } = MachineStockLevel.Enough; + + public MachineConnectionState ConnectionState { get; private set; } = MachineConnectionState.Ready; + + public bool IsTokenRecountInProgress => _tokenRecountInProgress; + + public bool CanStartTokenRecount => + ConnectionState == MachineConnectionState.Ready + && !_cashAcceptanceActive + && !_cardPaymentActive + && !_tokenRecountInProgress; + + public event Action? ConnectionStateChanged; + + public event Action? StockChanged; + + public event Action? CashBalanceChanged; + + public event Action? CardPaymentFinished; + + public event Action? DispenseFinished; + + public event Action? FaultOccurred; + + public event Action? TokenRecountProgressChanged; + + public event Action? TokenRecountFinished; + + public event Action? HopperStockChanged; + + public event Action? HopperDispenseAccounted; + + public event Action? DispenseProgressChanged; + + public event Action? HopperTokenRecountProgressChanged; + + public event Action? HopperTokenRecountFinished; + + public void Configure(MachineStockLevel initialStockLevel) + { + SetConnectionState(MachineConnectionState.Ready); + SetStockLevel(initialStockLevel); + } + + public void SetStockLevel(MachineStockLevel level) + { + StockLevel = level is MachineStockLevel.Enough or MachineStockLevel.Low + ? level + : MachineStockLevel.Unknown; + Hopper1StockLevel = StockLevel; + Hopper2StockLevel = StockLevel; + HopperStockChanged?.Invoke(HopperChannel.Hopper1, Hopper1StockLevel); + HopperStockChanged?.Invoke(HopperChannel.Hopper2, Hopper2StockLevel); + StockChanged?.Invoke(StockLevel); + } + + public void SetHopperInventory(int hopper1Count, int hopper2Count) + { + _hopper1Inventory = Math.Max(0, hopper1Count); + _hopper2Inventory = Math.Max(0, hopper2Count); + } + + public void SetInventoryAccountingEnabled(bool enabled) => + _inventoryAccountingEnabled = enabled; + + public void SetPurchaseLimitEnabled(bool enabled) => + _purchaseLimitEnabled = enabled; + + public bool CanStartHopperTokenRecount(HopperChannel hopper) => CanStartTokenRecount; + + public void BeginCashAcceptance() + { + if (_tokenRecountInProgress) + { + return; + } + + _operationGeneration++; + _cashBalance = 0; + _cashAcceptanceActive = true; + _cardPaymentActive = false; + CashBalanceChanged?.Invoke(_cashBalance); + AppLogger.Info("MockMachine", "Начат mock-приём наличных."); + } + + public void EndCashAcceptance() + { + _cashAcceptanceActive = false; + AppLogger.Info("MockMachine", "Mock-приём наличных остановлен."); + } + + public void AddCash(int amountRubles) + { + if (!_cashAcceptanceActive || amountRubles <= 0) + { + return; + } + + _cashBalance += amountRubles; + CashBalanceChanged?.Invoke(_cashBalance); + AppLogger.Info("MockMachine", $"Принято {amountRubles} ₽, баланс {_cashBalance} ₽."); + } + + public void BeginCardPayment(int amountRubles) + { + if (_tokenRecountInProgress) + { + CardPaymentFinished?.Invoke(MachineCardResult.Declined); + return; + } + + _operationGeneration++; + _cashAcceptanceActive = false; + _cardPaymentActive = true; + AppLogger.Info("MockMachine", $"Начато mock-ожидание карточной оплаты {amountRubles} ₽."); + } + + public void SimulateCardResult(MachineCardResult result) + { + if (!_cardPaymentActive) + { + return; + } + + _cardPaymentActive = false; + CardPaymentFinished?.Invoke(result); + AppLogger.Info("MockMachine", $"Mock-результат карточной оплаты: {result}."); + } + + public void SimulateNextDispenseFailure(string message = "Смоделированная ошибка выдачи") + { + _nextDispenseError = string.IsNullOrWhiteSpace(message) + ? "Смоделированная ошибка выдачи" + : message.Trim(); + _nextPartialDispenseCount = null; + } + + public void SimulateNextPartialDispense(int dispensedTokens, string message = "Смоделирована частичная выдача") + { + _nextPartialDispenseCount = Math.Max(0, dispensedTokens); + _nextDispenseError = string.IsNullOrWhiteSpace(message) + ? "Смоделирована частичная выдача" + : message.Trim(); + } + + public void SimulateConnectionLoss() + { + CancelTokenRecount("CONNECTION_LOST"); + _operationGeneration++; + _cashAcceptanceActive = false; + _cardPaymentActive = false; + SetConnectionState(MachineConnectionState.Disconnected); + SetStockLevel(MachineStockLevel.Unknown); + FaultOccurred?.Invoke(MachineFault.ConnectionLost); + AppLogger.Warning("MockMachine", "Смоделирована потеря связи с автоматом."); + } + + public void RestoreConnection(MachineStockLevel stockLevel = MachineStockLevel.Enough) + { + SetConnectionState(MachineConnectionState.Ready); + SetStockLevel(stockLevel); + AppLogger.Info("MockMachine", "Mock-связь с автоматом восстановлена."); + } + + public void CancelActiveOperation() + { + CancelTokenRecount(); + _operationGeneration++; + _cashAcceptanceActive = false; + _cardPaymentActive = false; + AppLogger.Info("MockMachine", "Активная mock-операция отменена."); + } + + public async void DispenseTokens(int tokenCount) + { + if (_tokenRecountInProgress) + { + DispenseFinished?.Invoke(false, 0, "TOKEN_RECOUNT_IN_PROGRESS"); + return; + } + + if (tokenCount <= 0) + { + DispenseFinished?.Invoke(false, 0, "Некорректное количество жетонов"); + return; + } + + if (_inventoryAccountingEnabled + && _purchaseLimitEnabled + && !DualHopperDispensePlanner.TryCreate( + tokenCount, + _hopper1Inventory, + _hopper2Inventory, + out _)) + { + DispenseFinished?.Invoke(false, 0, "INSUFFICIENT_ACCOUNTED_TOKENS"); + return; + } + + int generation = ++_operationGeneration; + string? forcedError = _nextDispenseError; + int? forcedPartialCount = _nextPartialDispenseCount; + _nextDispenseError = null; + _nextPartialDispenseCount = null; + + double delay = Math.Clamp(DispenseDelaySeconds, 0.05, 10.0); + await ToSignal(GetTree().CreateTimer(delay), SceneTreeTimer.SignalName.Timeout); + if (generation != _operationGeneration) + { + return; + } + + if (forcedError is not null && forcedPartialCount is null) + { + DispenseFinished?.Invoke(false, 0, forcedError); + AppLogger.Warning("MockMachine", $"Mock-выдача завершена ошибкой: {forcedError}."); + return; + } + + int dispensedTokens = Math.Min(tokenCount, forcedPartialCount ?? tokenCount); + bool success = dispensedTokens == tokenCount && forcedError is null; + string? error = success ? null : forcedError ?? "Выдано не всё запрошенное количество жетонов"; + (int hopper1, int hopper2) = AllocateDispensedTokens(dispensedTokens); + if (hopper1 > 0 || hopper2 > 0) + { + DispenseProgressChanged?.Invoke(dispensedTokens, tokenCount); + HopperDispenseAccounted?.Invoke(hopper1, hopper2); + } + + DispenseFinished?.Invoke(success, dispensedTokens, error); + AppLogger.Info("MockMachine", $"Mock-выдача завершена: {dispensedTokens} из {tokenCount} жетонов, success={success}."); + } + + public bool TryStartTokenRecount(ulong nowMilliseconds) => + TryStartTokenRecount(HopperChannel.Hopper1, nowMilliseconds); + + public bool TryStartTokenRecount(HopperChannel hopper, ulong nowMilliseconds) + { + if (!CanStartHopperTokenRecount(hopper)) + { + return false; + } + + int generation = ++_operationGeneration; + _tokenRecountInProgress = true; + _tokenRecountHopper = hopper; + _tokenRecountCount = 0; + TokenRecountProgressChanged?.Invoke(0); + HopperTokenRecountProgressChanged?.Invoke(hopper, 0); + RunTokenRecountAsync(generation); + return true; + } + + public void CancelTokenRecount() => CancelTokenRecount("TOKEN_RECOUNT_CANCELLED"); + + private async void RunTokenRecountAsync(int generation) + { + int target = Math.Clamp(MockRecountTokenCount, 0, 1000); + for (int index = 0; index < target; index++) + { + await ToSignal(GetTree().CreateTimer(0.12), SceneTreeTimer.SignalName.Timeout); + if (generation != _operationGeneration || !_tokenRecountInProgress) + { + return; + } + + _tokenRecountCount++; + TokenRecountProgressChanged?.Invoke(_tokenRecountCount); + HopperTokenRecountProgressChanged?.Invoke(_tokenRecountHopper, _tokenRecountCount); + } + + await ToSignal(GetTree().CreateTimer(0.35), SceneTreeTimer.SignalName.Timeout); + if (generation != _operationGeneration || !_tokenRecountInProgress) + { + return; + } + + int counted = _tokenRecountCount; + _tokenRecountInProgress = false; + _tokenRecountCount = 0; + TokenRecountFinished?.Invoke(true, counted, null); + HopperTokenRecountFinished?.Invoke(_tokenRecountHopper, true, counted, null); + } + + private void CancelTokenRecount(string errorCode) + { + if (!_tokenRecountInProgress) + { + return; + } + + int counted = _tokenRecountCount; + _tokenRecountInProgress = false; + _tokenRecountCount = 0; + _operationGeneration++; + TokenRecountFinished?.Invoke(false, counted, errorCode); + HopperTokenRecountFinished?.Invoke(_tokenRecountHopper, false, counted, errorCode); + } + + private (int Hopper1, int Hopper2) AllocateDispensedTokens(int count) + { + if (!_inventoryAccountingEnabled) + { + return (count, 0); + } + + if (!_purchaseLimitEnabled) + { + int hopper1 = Math.Min(count, _hopper1Inventory); + int hopper2 = count - hopper1; + _hopper1Inventory = Math.Max(0, _hopper1Inventory - hopper1); + _hopper2Inventory = Math.Max(0, _hopper2Inventory - hopper2); + return (hopper1, hopper2); + } + + if (!DualHopperDispensePlanner.TryCreate( + count, + _hopper1Inventory, + _hopper2Inventory, + out DualHopperDispensePlan plan)) + { + return (0, 0); + } + + _hopper1Inventory -= plan.Hopper1Count; + _hopper2Inventory -= plan.Hopper2Count; + return (plan.Hopper1Count, plan.Hopper2Count); + } + + private void SetConnectionState(MachineConnectionState state) + { + if (ConnectionState == state) + { + return; + } + + ConnectionState = state; + ConnectionStateChanged?.Invoke(state); + } +} diff --git a/src/hardware/MockMachine/MockMachineController.cs.uid b/src/hardware/MockMachine/MockMachineController.cs.uid new file mode 100644 index 0000000..6ceae4a --- /dev/null +++ b/src/hardware/MockMachine/MockMachineController.cs.uid @@ -0,0 +1 @@ +uid://dcyo4ihm80oaa diff --git a/src/hardware/PeripheryController/ControllerAuthentication.cs b/src/hardware/PeripheryController/ControllerAuthentication.cs new file mode 100644 index 0000000..07fd72e --- /dev/null +++ b/src/hardware/PeripheryController/ControllerAuthentication.cs @@ -0,0 +1,186 @@ +using System; +using System.Security.Cryptography; + +namespace Exchanger.Hardware.PeripheryController; + +public interface IControllerBlockCipher +{ + byte[] EncryptBlock(ReadOnlySpan plaintext); +} + +/// +/// Подтверждённый владельцем профиль платы: AES-256, ECB, без padding. +/// Handshake всегда передаёт ровно один 16-байтовый блок. +/// +public sealed class Aes256EcbBlockCipher : IControllerBlockCipher, IDisposable +{ + private readonly Aes _aes; + + public Aes256EcbBlockCipher(ReadOnlySpan key) + { + if (key.Length != 32) + { + throw new ArgumentException("Ключ AES-256 должен содержать ровно 32 байта.", nameof(key)); + } + + _aes = Aes.Create(); + _aes.Key = key.ToArray(); + _aes.Mode = CipherMode.ECB; + _aes.Padding = PaddingMode.None; + } + + public byte[] EncryptBlock(ReadOnlySpan plaintext) + { + if (plaintext.Length != 16) + { + throw new ArgumentException("Handshake использует один блок из 16 байт.", nameof(plaintext)); + } + + using ICryptoTransform encryptor = _aes.CreateEncryptor(); + return encryptor.TransformFinalBlock(plaintext.ToArray(), 0, plaintext.Length); + } + + public void Dispose() => _aes.Dispose(); +} + +public enum ControllerAuthenticationState +{ + NotStarted, + ConfigurationMissing, + AwaitingStartupBanner, + StartupDelay, + AwaitingChallenge, + AwaitingControllerProof, + AwaitingReady, + Ready, + Failed, +} + +public sealed class ControllerAuthenticator +{ + private readonly IControllerBlockCipher? _cipher; + private readonly Func _challengeFactory; + private byte[]? _hostChallenge; + + public ControllerAuthenticator(IControllerBlockCipher? cipher, Func? challengeFactory = null) + { + _cipher = cipher; + _challengeFactory = challengeFactory ?? CreateRandomChallenge; + } + + public ControllerAuthenticationState State { get; private set; } + + public bool BeginStartup() + { + _hostChallenge = null; + if (_cipher is null) + { + State = ControllerAuthenticationState.ConfigurationMissing; + return false; + } + + State = ControllerAuthenticationState.AwaitingStartupBanner; + return true; + } + + public bool AcceptStartupBanner(PeripheryMessage message) + { + if (message.Kind != PeripheryMessageKind.StartupBanner + || State != ControllerAuthenticationState.AwaitingStartupBanner) + { + return false; + } + + State = ControllerAuthenticationState.StartupDelay; + return true; + } + + public string? StartHandshake() + { + if (_cipher is null) + { + State = ControllerAuthenticationState.ConfigurationMissing; + return null; + } + + if (State != ControllerAuthenticationState.StartupDelay) + { + return null; + } + + _hostChallenge = _challengeFactory(); + if (_hostChallenge.Length != 16) + { + throw new InvalidOperationException("Генератор challenge должен вернуть 16 байт."); + } + + State = ControllerAuthenticationState.AwaitingChallenge; + return "07" + Convert.ToHexString(_hostChallenge); + } + + public string? Handle(PeripheryMessage message) + { + if (_cipher is null) + { + State = ControllerAuthenticationState.ConfigurationMissing; + return null; + } + + if (message.Kind == PeripheryMessageKind.StartupBanner) + { + AcceptStartupBanner(message); + return null; + } + + if (message.Kind == PeripheryMessageKind.Challenge + && State == ControllerAuthenticationState.AwaitingChallenge) + { + byte[] response = _cipher.EncryptBlock(Convert.FromHexString(message.Payload)); + State = ControllerAuthenticationState.AwaitingControllerProof; + return "08" + Convert.ToHexString(response); + } + + if (message.Kind == PeripheryMessageKind.EncryptedResponse + && State == ControllerAuthenticationState.AwaitingControllerProof) + { + byte[] expected = _cipher.EncryptBlock(_hostChallenge!); + byte[] received = Convert.FromHexString(message.Payload); + if (!CryptographicOperations.FixedTimeEquals(expected, received)) + { + State = ControllerAuthenticationState.Failed; + return null; + } + + State = ControllerAuthenticationState.AwaitingReady; + return null; + } + + if (message.Kind == PeripheryMessageKind.Ready + && State == ControllerAuthenticationState.AwaitingReady) + { + State = ControllerAuthenticationState.Ready; + return null; + } + + return null; + } + + public void Reset() + { + _hostChallenge = null; + State = ControllerAuthenticationState.NotStarted; + } + + public void Fail() + { + _hostChallenge = null; + State = ControllerAuthenticationState.Failed; + } + + private static byte[] CreateRandomChallenge() + { + byte[] challenge = new byte[16]; + RandomNumberGenerator.Fill(challenge); + return challenge; + } +} diff --git a/src/hardware/PeripheryController/ControllerAuthentication.cs.uid b/src/hardware/PeripheryController/ControllerAuthentication.cs.uid new file mode 100644 index 0000000..e59226c --- /dev/null +++ b/src/hardware/PeripheryController/ControllerAuthentication.cs.uid @@ -0,0 +1 @@ +uid://b4ix3gybqwbqx diff --git a/src/hardware/PeripheryController/PeripheryControllerInputs.cs b/src/hardware/PeripheryController/PeripheryControllerInputs.cs new file mode 100644 index 0000000..378fe86 --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryControllerInputs.cs @@ -0,0 +1,16 @@ +namespace Exchanger.Hardware.PeripheryController; + +/// +/// Подтверждённая владельцем разводка цифровых входов контроллера. +/// Значения служат production-default и могут быть переопределены внешней конфигурацией. +/// +public static class PeripheryControllerInputs +{ + public const int ServiceButton = 8; + public const int Hopper1StockLow = 1; + public const int Hopper2StockLow = 4; + public const int Hopper1DispensePulse = 24; + + /// IN25 — физический датчик выдачи второго хоппера. + public const int Hopper2DispensePulse = 25; +} diff --git a/src/hardware/PeripheryController/PeripheryControllerInputs.cs.uid b/src/hardware/PeripheryController/PeripheryControllerInputs.cs.uid new file mode 100644 index 0000000..94aef69 --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryControllerInputs.cs.uid @@ -0,0 +1 @@ +uid://dyjk001h2a3wk diff --git a/src/hardware/PeripheryController/PeripheryControllerSecurity.cs b/src/hardware/PeripheryController/PeripheryControllerSecurity.cs new file mode 100644 index 0000000..f0664db --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryControllerSecurity.cs @@ -0,0 +1,40 @@ +using System; + +namespace Exchanger.Hardware.PeripheryController; + +/// +/// Обфусцированное представление ключа контроллера 2.3.5. +/// Перед AES каждый байт восстанавливается через XOR 0x37 — так же, как +/// в рабочей Unity-реализации контроллера. +/// +public static class PeripheryControllerSecurity +{ + private const byte KeyMask = 0x37; + + private static readonly byte[] AesEncryptedKey = + { + 0x69, 0x40, 0xC7, 0x0E, 0xF2, 0xC7, 0x45, 0x70, + 0x72, 0xCD, 0x28, 0x58, 0x99, 0x8F, 0x73, 0xA8, + 0x5F, 0x5F, 0xED, 0xB4, 0xC1, 0x62, 0xB4, 0x24, + 0xAC, 0xD7, 0xA3, 0xD6, 0xD8, 0x0B, 0x50, 0x37, + }; + + private static readonly byte[] AesKey = BuildAesKey(); + + /// + /// Эффективный 32-байтовый ключ AES-256. Значение переменной окружения, + /// если оно задано, считается уже эффективным ключом и этим методом не проходит. + /// + public static ReadOnlySpan Key => AesKey; + + private static byte[] BuildAesKey() + { + byte[] key = new byte[AesEncryptedKey.Length]; + for (int index = 0; index < key.Length; index++) + { + key[index] = (byte)(AesEncryptedKey[index] ^ KeyMask); + } + + return key; + } +} diff --git a/src/hardware/PeripheryController/PeripheryControllerSecurity.cs.uid b/src/hardware/PeripheryController/PeripheryControllerSecurity.cs.uid new file mode 100644 index 0000000..004bfb2 --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryControllerSecurity.cs.uid @@ -0,0 +1 @@ +uid://bvk175opq2w3o diff --git a/src/hardware/PeripheryController/PeripheryMachineController.cs b/src/hardware/PeripheryController/PeripheryMachineController.cs new file mode 100644 index 0000000..feb2535 --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryMachineController.cs @@ -0,0 +1,1223 @@ +using Exchanger.Core.Logging; +using Exchanger.Hardware.Abstractions; +using System; + +namespace Exchanger.Hardware.PeripheryController; + +public enum PeripheryDispenseMode +{ + Unsupported, + Hopper1Auto, + Hopper2Auto, + DualHopperAuto, +} + +/// +/// Типизированный адаптер универсального контроллера 2.3.5. Все обработчики +/// вызываются из главного потока через IHardwarePort.ProcessPendingEvents(). +/// +public sealed class PeripheryMachineController : IMachineController, ITokenRecountController, + IDualHopperMachineController, IDualHopperTokenRecountController, IDisposable +{ + private const ulong TokenRecountSilenceMilliseconds = 10_000; + private const ulong HopperCreditTimeoutMilliseconds = 3000; + private const ulong StartupBannerTimeoutMilliseconds = 20_000; + private const ulong StartupDelayMilliseconds = 2_000; + private const ulong ReadyTimeoutMilliseconds = 5_000; + + private readonly IHardwarePort _port; + private readonly ControllerAuthenticator _authenticator; + private readonly PeripheryDispenseMode _dispenseMode; + private readonly ulong _cashlessKeepAliveMilliseconds; + private readonly int _serviceButtonInputIndex; + private readonly bool _serviceButtonActiveHigh; + private readonly int _stockSensorInputIndex; + private readonly bool _stockLowWhenInputHigh; + private readonly int _hopper2StockSensorInputIndex; + private readonly bool _hopper2StockLowWhenInputHigh; + private readonly int _hopper1DispenseSensorInputIndex; + private readonly int _hopper2DispenseSensorInputIndex; + private readonly ulong _digitalInputPollMilliseconds; + private readonly ulong _handshakeTimeoutMilliseconds; + private bool _ready; + private bool _cashActive; + private bool _cardActive; + private bool _cashlessEnabled; + private int _cashBalance; + private int _requestedCardAmount; + private int _requestedDispenseCount; + private int _confirmedDispenseCount; + private int _remainingDispenseCount; + private int _currentDispenseChunkCount; + private int _currentDispenseChunkConfirmed; + private int _configuredHopper1Inventory; + private int _configuredHopper2Inventory; + private bool _inventoryAccountingEnabled = true; + private bool _purchaseLimitEnabled = true; + private int _plannedHopper1Remaining; + private int _plannedHopper2Remaining; + private int _confirmedHopper1Count; + private int _confirmedHopper2Count; + private HopperChannel _activeDispenseHopper = HopperChannel.Hopper1; + private bool _hopperErrorAwaitingCredit; + private ulong _hopperCreditDeadlineAt = ulong.MaxValue; + private ulong _nextCashlessKeepAliveAt; + private ulong _nextDigitalInputPollAt = ulong.MaxValue; + private ulong _authenticationStageDeadlineAt = ulong.MaxValue; + private string _lastHandshakeResponseKind = "None"; + private int? _lastDigitalInputMask; + private bool _disconnectingAfterHandshakeFailure; + private bool _disposed; + private bool _tokenRecountInProgress; + private int _tokenRecountCount; + private HopperChannel _tokenRecountHopper = HopperChannel.Hopper1; + private ulong _lastTokenRecountPulseAt; + private ulong _lastUpdateMilliseconds; + + public PeripheryMachineController( + IHardwarePort port, + ControllerAuthenticator authenticator, + PeripheryDispenseMode dispenseMode = PeripheryDispenseMode.Unsupported, + int cashlessKeepAliveSeconds = 120, + int stockSensorInputIndex = -1, + bool stockLowWhenInputHigh = false, + int stockPollSeconds = 5, + int handshakeTimeoutMilliseconds = 2000, + int serviceButtonInputIndex = -1, + bool serviceButtonActiveHigh = true, + int hopper1DispenseSensorInputIndex = -1, + bool hopper1DispenseSensorActiveHigh = false, + int hopper2DispenseSensorInputIndex = -1, + bool hopper2DispenseSensorActiveHigh = false, + int inputPollMilliseconds = 100, + int hopper2StockSensorInputIndex = -1, + bool hopper2StockLowWhenInputHigh = false) + { + _port = port ?? throw new ArgumentNullException(nameof(port)); + _authenticator = authenticator ?? throw new ArgumentNullException(nameof(authenticator)); + _dispenseMode = dispenseMode; + _cashlessKeepAliveMilliseconds = (ulong)Math.Clamp(cashlessKeepAliveSeconds, 30, 170) * 1000UL; + _serviceButtonInputIndex = Math.Clamp(serviceButtonInputIndex, -1, 25); + _serviceButtonActiveHigh = serviceButtonActiveHigh; + _stockSensorInputIndex = Math.Clamp(stockSensorInputIndex, -1, 25); + _stockLowWhenInputHigh = stockLowWhenInputHigh; + _hopper2StockSensorInputIndex = Math.Clamp(hopper2StockSensorInputIndex, -1, 25); + _hopper2StockLowWhenInputHigh = hopper2StockLowWhenInputHigh; + _hopper1DispenseSensorInputIndex = Math.Clamp(hopper1DispenseSensorInputIndex, -1, 25); + _hopper2DispenseSensorInputIndex = Math.Clamp(hopper2DispenseSensorInputIndex, -1, 25); + _digitalInputPollMilliseconds = HasFastDigitalInput + ? (ulong)Math.Clamp(inputPollMilliseconds, 50, 1000) + : (ulong)Math.Clamp(stockPollSeconds, 1, 60) * 1000UL; + int normalizedHandshakeTimeout = Math.Clamp(handshakeTimeoutMilliseconds, 1000, 60000); + _handshakeTimeoutMilliseconds = (ulong)normalizedHandshakeTimeout; + _port.OnDataReceived += OnDataReceived; + _port.ConnectionChanged += OnConnectionChanged; + AppLogger.Debug( + "PeripheryController", + $"Создан адаптер: dispenseMode={_dispenseMode}, handshakeTimeoutMs={_handshakeTimeoutMilliseconds}, " + + $"inputPollMs={_digitalInputPollMilliseconds}, configuredInputs={HasConfiguredDigitalInput}."); + } + + public MachineStockLevel StockLevel { get; private set; } = MachineStockLevel.Unknown; + + public MachineStockLevel Hopper1StockLevel { get; private set; } = MachineStockLevel.Unknown; + + public MachineStockLevel Hopper2StockLevel { get; private set; } = MachineStockLevel.Unknown; + + public MachineConnectionState ConnectionState { get; private set; } = MachineConnectionState.Disconnected; + + public bool IsReady => _ready; + + public bool IsTokenRecountInProgress => _tokenRecountInProgress; + + public bool CanStartTokenRecount => + _ready + && _port.IsConnected + && _dispenseMode is PeripheryDispenseMode.Hopper1Auto or PeripheryDispenseMode.DualHopperAuto + && !_cashActive + && !_cardActive + && !_cashlessEnabled + && _requestedDispenseCount == 0 + && !_tokenRecountInProgress; + + public ControllerAuthenticationState AuthenticationState => _authenticator.State; + + public event Action? ConnectionStateChanged; + + public event Action? StockChanged; + + public event Action? CashBalanceChanged; + + public event Action? CardPaymentFinished; + + public event Action? DispenseFinished; + + public event Action? FaultOccurred; + + public event Action? ServiceRequested; + + public event Action? TokenRecountProgressChanged; + + public event Action? TokenRecountFinished; + + public event Action? HopperStockChanged; + + public event Action? HopperDispenseAccounted; + + public event Action? DispenseProgressChanged; + + public event Action? HopperTokenRecountProgressChanged; + + public event Action? HopperTokenRecountFinished; + + private int ActiveDispenseSensorInputIndex => _dispenseMode switch + { + PeripheryDispenseMode.Hopper1Auto => _hopper1DispenseSensorInputIndex, + PeripheryDispenseMode.Hopper2Auto => _hopper2DispenseSensorInputIndex, + _ => -1, + }; + + private bool HasFastDigitalInput => + _serviceButtonInputIndex >= 0 || ActiveDispenseSensorInputIndex >= 0; + + private bool HasConfiguredDigitalInput => + HasFastDigitalInput || _stockSensorInputIndex >= 0 || _hopper2StockSensorInputIndex >= 0; + + public void Update(ulong nowMilliseconds) + { + _lastUpdateMilliseconds = nowMilliseconds; + UpdateHandshakeTimeout(nowMilliseconds); + UpdateDigitalInputPolling(nowMilliseconds); + UpdateTokenRecountTimeout(nowMilliseconds); + UpdateHopperCreditTimeout(nowMilliseconds); + if (!_ready + || _cashActive + || _tokenRecountInProgress + || _requestedDispenseCount > 0) + { + return; + } + + if (_nextCashlessKeepAliveAt == ulong.MaxValue) + { + _nextCashlessKeepAliveAt = nowMilliseconds + _cashlessKeepAliveMilliseconds; + return; + } + + if (nowMilliseconds < _nextCashlessKeepAliveAt) + { + return; + } + + Send(PeripheryProtocolCommands.EnableCashless); + _nextCashlessKeepAliveAt = nowMilliseconds + _cashlessKeepAliveMilliseconds; + } + + public void BeginCashAcceptance() + { + if (_tokenRecountInProgress) + { + FaultOccurred?.Invoke(MachineFault.Unavailable); + return; + } + + _cashBalance = 0; + CashBalanceChanged?.Invoke(0); + if (!RequireOperational()) + { + return; + } + + _cardActive = false; + _cashlessEnabled = false; + _requestedCardAmount = 0; + _nextCashlessKeepAliveAt = ulong.MaxValue; + Send(PeripheryProtocolCommands.DisableCashless); + Send(PeripheryProtocolCommands.EnableCoinSmartMode); + Send(PeripheryProtocolCommands.EnableBillAcceptor); + _cashActive = true; + } + + public void EndCashAcceptance() + { + bool wasActive = _cashActive; + _cashActive = false; + if (_ready && wasActive) + { + Send(PeripheryProtocolCommands.DisableCoinAcceptor); + Send(PeripheryProtocolCommands.DisableBillAcceptor); + _nextCashlessKeepAliveAt = 0; + } + } + + public void BeginCardPayment(int amountRubles) + { + if (_tokenRecountInProgress) + { + CardPaymentFinished?.Invoke(MachineCardResult.Declined); + return; + } + + if (!RequireOperational()) + { + return; + } + + string paymentCommand; + try + { + paymentCommand = PeripheryProtocolCommands.RequestCashlessPayment(amountRubles); + } + catch (ArgumentOutOfRangeException) + { + CardPaymentFinished?.Invoke(MachineCardResult.Declined); + return; + } + + _cashActive = false; + _cardActive = true; + _cashlessEnabled = true; + _requestedCardAmount = amountRubles; + Send(PeripheryProtocolCommands.DisableCoinAcceptor); + Send(PeripheryProtocolCommands.DisableBillAcceptor); + Send(PeripheryProtocolCommands.EnableCashless); + Send(paymentCommand); + + _nextCashlessKeepAliveAt = ulong.MaxValue; + } + + public void CancelActiveOperation() + { + CancelTokenRecount(); + bool cashWasActive = _cashActive; + bool cardWasActive = _cardActive || _cashlessEnabled; + _cashActive = false; + _cardActive = false; + _cashlessEnabled = false; + _requestedCardAmount = 0; + _nextCashlessKeepAliveAt = ulong.MaxValue; + if (!_ready) + { + return; + } + + if (cashWasActive) + { + Send(PeripheryProtocolCommands.DisableCoinAcceptor); + Send(PeripheryProtocolCommands.DisableBillAcceptor); + } + + if (cardWasActive) + { + Send(PeripheryProtocolCommands.DisableCashless); + } + } + + public void SetHopperInventory(int hopper1Count, int hopper2Count) + { + _configuredHopper1Inventory = Math.Max(0, hopper1Count); + _configuredHopper2Inventory = Math.Max(0, hopper2Count); + } + + public void SetInventoryAccountingEnabled(bool enabled) => + _inventoryAccountingEnabled = enabled; + + public void SetPurchaseLimitEnabled(bool enabled) => + _purchaseLimitEnabled = enabled; + + public void DispenseTokens(int tokenCount) + { + if (_tokenRecountInProgress) + { + DispenseFinished?.Invoke(false, 0, "TOKEN_RECOUNT_IN_PROGRESS"); + return; + } + + if (!RequireReady()) + { + DispenseFinished?.Invoke(false, 0, "CONTROLLER_NOT_READY"); + return; + } + + if (_dispenseMode == PeripheryDispenseMode.Unsupported) + { + AppLogger.Error("PeripheryController", "Выдача заблокирована: команды хопперов не настроены."); + DispenseFinished?.Invoke(false, 0, "DISPENSE_COMMAND_NOT_CONFIGURED"); + return; + } + + if (_requestedDispenseCount > 0) + { + AppLogger.Warning("PeripheryController", "Повторная команда выдачи проигнорирована: предыдущая выдача ещё не завершена."); + return; + } + + if (tokenCount <= 0) + { + DispenseFinished?.Invoke(false, 0, "DISPENSE_COUNT_OUT_OF_RANGE"); + return; + } + + if (!PrepareDispensePlan(tokenCount)) + { + DispenseFinished?.Invoke(false, 0, "INSUFFICIENT_ACCOUNTED_TOKENS"); + return; + } + + _requestedDispenseCount = tokenCount; + _confirmedDispenseCount = 0; + _remainingDispenseCount = tokenCount; + _confirmedHopper1Count = 0; + _confirmedHopper2Count = 0; + _currentDispenseChunkCount = 0; + _currentDispenseChunkConfirmed = 0; + Send(PeripheryProtocolCommands.DisableCashless); + _nextCashlessKeepAliveAt = ulong.MaxValue; + SendNextDispenseChunk(); + } + + public bool CanStartHopperTokenRecount(HopperChannel hopper) => + _ready + && _port.IsConnected + && (_dispenseMode == PeripheryDispenseMode.DualHopperAuto + || hopper == HopperChannel.Hopper1 && _dispenseMode == PeripheryDispenseMode.Hopper1Auto + || hopper == HopperChannel.Hopper2 && _dispenseMode == PeripheryDispenseMode.Hopper2Auto) + && !_cashActive + && !_cardActive + && !_cashlessEnabled + && _requestedDispenseCount == 0 + && !_tokenRecountInProgress; + + public bool TryStartTokenRecount(ulong nowMilliseconds) => + TryStartTokenRecount(HopperChannel.Hopper1, nowMilliseconds); + + public bool TryStartTokenRecount(HopperChannel hopper, ulong nowMilliseconds) + { + if (!CanStartHopperTokenRecount(hopper)) + { + return false; + } + + _tokenRecountInProgress = true; + _tokenRecountHopper = hopper; + _tokenRecountCount = 0; + _lastTokenRecountPulseAt = nowMilliseconds; + _lastUpdateMilliseconds = nowMilliseconds; + Send(PeripheryProtocolCommands.DisableCashless); + _nextCashlessKeepAliveAt = ulong.MaxValue; + Send(hopper == HopperChannel.Hopper1 + ? PeripheryProtocolCommands.EnableHopper1Motor + : PeripheryProtocolCommands.EnableHopper2Motor); + TokenRecountProgressChanged?.Invoke(0); + HopperTokenRecountProgressChanged?.Invoke(hopper, 0); + return true; + } + + public void CancelTokenRecount() + { + if (!_tokenRecountInProgress) + { + return; + } + + CompleteTokenRecount(false, "TOKEN_RECOUNT_CANCELLED", stopMotor: true); + } + + public void Dispose() + { + if (_disposed) + { + return; + } + + CancelTokenRecount(); + _port.OnDataReceived -= OnDataReceived; + _port.ConnectionChanged -= OnConnectionChanged; + _disposed = true; + } + + private void OnConnectionChanged(bool connected) + { + AppLogger.Debug( + "PeripheryController", + $"Событие транспорта: connected={connected}, state={ConnectionState}, " + + $"authState={_authenticator.State}, ready={_ready}."); + if (!connected) + { + bool handshakeFailureDisconnect = _disconnectingAfterHandshakeFailure; + _disconnectingAfterHandshakeFailure = false; + bool activeOperation = _cashActive || _cardActive || _requestedDispenseCount > 0 || _tokenRecountInProgress; + bool recountWasActive = _tokenRecountInProgress; + int recountCount = _tokenRecountCount; + HopperChannel recountHopper = _tokenRecountHopper; + int dispensedFromHopper1 = _confirmedHopper1Count; + int dispensedFromHopper2 = _confirmedHopper2Count; + ResetTokenRecountState(); + _ready = false; + _cashActive = false; + _cardActive = false; + _cashlessEnabled = false; + ResetDispenseState(); + if (dispensedFromHopper1 > 0 || dispensedFromHopper2 > 0) + { + HopperDispenseAccounted?.Invoke(dispensedFromHopper1, dispensedFromHopper2); + } + + _lastDigitalInputMask = null; + _nextDigitalInputPollAt = ulong.MaxValue; + ResetHandshakeTiming(); + Hopper1StockLevel = MachineStockLevel.Unknown; + Hopper2StockLevel = MachineStockLevel.Unknown; + StockLevel = MachineStockLevel.Unknown; + HopperStockChanged?.Invoke(HopperChannel.Hopper1, Hopper1StockLevel); + HopperStockChanged?.Invoke(HopperChannel.Hopper2, Hopper2StockLevel); + StockChanged?.Invoke(StockLevel); + if (recountWasActive) + { + TokenRecountFinished?.Invoke(false, recountCount, "CONNECTION_LOST"); + HopperTokenRecountFinished?.Invoke(recountHopper, false, recountCount, "CONNECTION_LOST"); + } + SetConnectionState(handshakeFailureDisconnect + ? MachineConnectionState.Faulted + : MachineConnectionState.Disconnected); + AppLogger.Debug( + "PeripheryController", + $"Состояние после отключения сброшено: handshakeFailure={handshakeFailureDisconnect}, " + + $"activeOperation={activeOperation}, confirmedH1={dispensedFromHopper1}, " + + $"confirmedH2={dispensedFromHopper2}."); + if (!handshakeFailureDisconnect) + { + _authenticator.Reset(); + FaultOccurred?.Invoke(activeOperation ? MachineFault.ConnectionLost : MachineFault.Unavailable); + } + return; + } + + _disconnectingAfterHandshakeFailure = false; + _lastDigitalInputMask = null; + SetConnectionState(MachineConnectionState.Authenticating); + if (!_authenticator.BeginStartup()) + { + SetConnectionState(MachineConnectionState.Faulted); + AppLogger.Error("PeripheryController", "Авторизация не настроена: отсутствует AES-ключ или выбран неподдерживаемый режим."); + FaultOccurred?.Invoke(MachineFault.Unavailable); + return; + } + + ResetHandshakeTiming(); + _lastHandshakeResponseKind = "None"; + AppLogger.Debug( + "ControllerAuth", + $"Авторизация запущена: state={_authenticator.State}; ожидание startup-banner до {StartupBannerTimeoutMilliseconds} мс."); + } + + private void OnDataReceived(string frame) + { + PeripheryMessage message = PeripheryProtocolParser.Parse(frame); + if (message.Kind is PeripheryMessageKind.StartupBanner + or PeripheryMessageKind.EncryptedResponse + or PeripheryMessageKind.Challenge + or PeripheryMessageKind.HostAuthorizationAccepted + or PeripheryMessageKind.AuthorizationConfirmed + or PeripheryMessageKind.Ready) + { + _lastHandshakeResponseKind = message.Kind.ToString(); + ControllerAuthenticationState previousState = _authenticator.State; + AppLogger.Debug( + "ControllerAuth", + $"Получен этап {message.Kind}: frameLength={frame.Length}, stateBefore={previousState}; payload скрыт."); + string? response = _authenticator.Handle(message); + if (response is not null) + { + AppLogger.Debug( + "ControllerAuth", + $"Сформирован ответ на этап {message.Kind}: responseLength={response.Length}; payload скрыт."); + Send(response); + } + + if (_authenticator.State != previousState) + { + _authenticationStageDeadlineAt = ulong.MaxValue; + AppLogger.Debug( + "ControllerAuth", + $"Переход авторизации: {previousState} -> {_authenticator.State}."); + } + + if (_authenticator.State == ControllerAuthenticationState.Ready && !_ready) + { + CompleteInitialization(); + } + else if (_authenticator.State == ControllerAuthenticationState.Failed) + { + FailHandshake("Контроллер не прошёл криптографическую проверку."); + } + + return; + } + + if (!_ready) + { + if (message.Kind == PeripheryMessageKind.TransportError) + { + FaultOccurred?.Invoke(MachineFault.Unavailable); + } + else + { + AppLogger.Warning("PeripheryController", "Неавторизованный протокольный кадр проигнорирован; содержимое скрыто."); + } + + return; + } + + switch (message.Kind) + { + case PeripheryMessageKind.MoneyCoins: + Send(PeripheryProtocolCommands.AcknowledgeCoins(message.NumericValue)); + AcceptCash(message.NumericValue); + break; + case PeripheryMessageKind.MoneyBill: + Send(PeripheryProtocolCommands.AcknowledgeBill(message.NumericValue)); + AcceptCash(message.NumericValue); + break; + case PeripheryMessageKind.MoneyCashless: + Send(PeripheryProtocolCommands.AcknowledgeCashless(message.NumericValue)); + AcceptCashless(message.NumericValue); + break; + case PeripheryMessageKind.CoinPulse: + Send(PeripheryProtocolCommands.AcknowledgeCoinPulse()); + AppLogger.Warning("PeripheryController", "Получен COIN без номинала; событие подтверждено, но не зачислено. Ожидался smart-режим."); + break; + case PeripheryMessageKind.Hopper1Ok: + if (_activeDispenseHopper == HopperChannel.Hopper1 + && !_tokenRecountInProgress + && !_hopperErrorAwaitingCredit) + { + ConfirmHopperPulse(); + } + break; + case PeripheryMessageKind.Hopper1Error: + if (_activeDispenseHopper == HopperChannel.Hopper1) + { + BeginHopperFailure(); + } + break; + case PeripheryMessageKind.Hopper1Append: + break; + case PeripheryMessageKind.Hopper1Credit: + if (_activeDispenseHopper == HopperChannel.Hopper1) + { + CompleteHopperFailureFromCredit(message.NumericValue); + } + break; + case PeripheryMessageKind.Hopper1Pulse: + if (_tokenRecountInProgress && _tokenRecountHopper == HopperChannel.Hopper1) + { + CountTokenRecountPulse(); + } + break; + case PeripheryMessageKind.Hopper2Ok: + if (_activeDispenseHopper == HopperChannel.Hopper2 + && !_tokenRecountInProgress + && !_hopperErrorAwaitingCredit) + { + ConfirmHopperPulse(); + } + break; + case PeripheryMessageKind.Hopper2Queued: + case PeripheryMessageKind.Hopper2Append: + break; + case PeripheryMessageKind.Hopper2Error: + if (_activeDispenseHopper == HopperChannel.Hopper2) + { + BeginHopperFailure(); + } + break; + case PeripheryMessageKind.Hopper2Credit: + if (_activeDispenseHopper == HopperChannel.Hopper2) + { + CompleteHopperFailureFromCredit(message.NumericValue); + } + break; + case PeripheryMessageKind.Hopper2Pulse: + if (_tokenRecountInProgress && _tokenRecountHopper == HopperChannel.Hopper2) + { + CountTokenRecountPulse(); + } + break; + case PeripheryMessageKind.Service: + if (_serviceButtonInputIndex < 0) + { + ServiceRequested?.Invoke(); + } + break; + case PeripheryMessageKind.DigitalInputs: + ApplyDigitalInputs(message.NumericValue); + break; + case PeripheryMessageKind.ControllerError: + case PeripheryMessageKind.TransportError: + FaultOccurred?.Invoke(MachineFault.Unavailable); + break; + case PeripheryMessageKind.Unknown: + AppLogger.Warning("PeripheryController", "Получен неизвестный или developer-кадр; содержимое скрыто."); + break; + } + } + + private void CompleteInitialization() + { + _ready = true; + SetConnectionState(MachineConnectionState.Ready); + ResetHandshakeTiming(); + Send(PeripheryProtocolCommands.EnableCoinSmartMode); + Send(PeripheryProtocolCommands.DisableCoinAcceptor); + Send(PeripheryProtocolCommands.DisableBillAcceptor); + Send(PeripheryProtocolCommands.DisableCashless); + Hopper1StockLevel = MachineStockLevel.Unknown; + Hopper2StockLevel = MachineStockLevel.Unknown; + StockLevel = MachineStockLevel.Unknown; + HopperStockChanged?.Invoke(HopperChannel.Hopper1, Hopper1StockLevel); + HopperStockChanged?.Invoke(HopperChannel.Hopper2, Hopper2StockLevel); + StockChanged?.Invoke(StockLevel); + if (HasConfiguredDigitalInput) + { + Send(PeripheryProtocolCommands.QueryDigitalInputs); + _nextDigitalInputPollAt = ulong.MaxValue; + } + AppLogger.Info("PeripheryController", "Контроллер авторизован и переведён в безопасное исходное состояние."); + AppLogger.Debug( + "ControllerAuth", + $"Инициализация завершена: state={_authenticator.State}, digitalInputPolling={HasConfiguredDigitalInput}, " + + $"connectionState={ConnectionState}."); + } + + private void UpdateHandshakeTimeout(ulong nowMilliseconds) + { + ControllerAuthenticationState state = _authenticator.State; + if (_ready + || state is ControllerAuthenticationState.NotStarted + or ControllerAuthenticationState.ConfigurationMissing + or ControllerAuthenticationState.Ready + or ControllerAuthenticationState.Failed) + { + return; + } + + if (_authenticationStageDeadlineAt == ulong.MaxValue) + { + ulong timeout = state switch + { + ControllerAuthenticationState.AwaitingStartupBanner => StartupBannerTimeoutMilliseconds, + ControllerAuthenticationState.StartupDelay => StartupDelayMilliseconds, + ControllerAuthenticationState.AwaitingReady => ReadyTimeoutMilliseconds, + _ => _handshakeTimeoutMilliseconds, + }; + _authenticationStageDeadlineAt = nowMilliseconds + timeout; + AppLogger.Debug( + "ControllerAuth", + $"Установлен таймаут этапа: state={state}, timeoutMs={timeout}."); + return; + } + + if (nowMilliseconds < _authenticationStageDeadlineAt) + { + return; + } + + if (state == ControllerAuthenticationState.StartupDelay) + { + string? command = _authenticator.StartHandshake(); + if (command is null) + { + FailHandshake("Не удалось начать криптографическую авторизацию после стартовой паузы."); + return; + } + + _authenticationStageDeadlineAt = ulong.MaxValue; + AppLogger.Debug( + "ControllerAuth", + "Стартовая пауза завершена; сформирован host challenge длиной 16 байт, содержимое скрыто."); + Send(command); + return; + } + + string reason = state switch + { + ControllerAuthenticationState.AwaitingStartupBanner => + "Контроллер не прислал загрузочную строку в пределах таймаута.", + ControllerAuthenticationState.AwaitingChallenge => + "Контроллер не прислал CHAL в пределах таймаута.", + ControllerAuthenticationState.AwaitingControllerProof => + "Контроллер не прислал RAES в пределах таймаута.", + ControllerAuthenticationState.AwaitingReady => + "Контроллер не прислал точную строку READY! после RAES.", + _ => "Истёк таймаут авторизации контроллера.", + }; + FailHandshake(reason); + } + + private void FailHandshake(string reason) + { + if (_disconnectingAfterHandshakeFailure) + { + return; + } + + if (_authenticator.State != ControllerAuthenticationState.Failed) + { + _authenticator.Fail(); + } + + ResetHandshakeTiming(); + SetConnectionState(MachineConnectionState.Faulted); + AppLogger.Error( + "PeripheryController", + $"{reason} Последний тип ответа платы: {_lastHandshakeResponseKind}."); + AppLogger.Debug( + "ControllerAuth", + $"Авторизация аварийно завершена: state={_authenticator.State}, lastKind={_lastHandshakeResponseKind}."); + FaultOccurred?.Invoke(MachineFault.Unavailable); + _disconnectingAfterHandshakeFailure = true; + _port.Disconnect(); + } + + private void ResetHandshakeTiming() + { + _authenticationStageDeadlineAt = ulong.MaxValue; + } + + private void AcceptCash(int amountRubles) + { + if (!_cashActive) + { + AppLogger.Warning("PeripheryController", "Платёж подтверждён контроллеру, но проигнорирован вне cash-сессии."); + return; + } + + _cashBalance = (int)Math.Min(int.MaxValue, (long)_cashBalance + amountRubles); + CashBalanceChanged?.Invoke(_cashBalance); + } + + private void AcceptCashless(int amountRubles) + { + if (!_cardActive) + { + AppLogger.Warning("PeripheryController", "Безналичный платёж подтверждён контроллеру, но проигнорирован вне card-сессии."); + return; + } + + _cardActive = false; + _cashlessEnabled = false; + Send(PeripheryProtocolCommands.DisableCashless); + CardPaymentFinished?.Invoke(amountRubles == _requestedCardAmount + ? MachineCardResult.Approved + : MachineCardResult.Declined); + } + + private bool PrepareDispensePlan(int tokenCount) + { + if (_dispenseMode == PeripheryDispenseMode.Hopper1Auto) + { + _plannedHopper1Remaining = tokenCount; + _plannedHopper2Remaining = 0; + return true; + } + + if (_dispenseMode == PeripheryDispenseMode.Hopper2Auto) + { + _plannedHopper1Remaining = 0; + _plannedHopper2Remaining = tokenCount; + return true; + } + + if (!_inventoryAccountingEnabled) + { + _plannedHopper1Remaining = tokenCount; + _plannedHopper2Remaining = 0; + return true; + } + + if (!_purchaseLimitEnabled) + { + _plannedHopper1Remaining = Math.Min(tokenCount, _configuredHopper1Inventory); + _plannedHopper2Remaining = tokenCount - _plannedHopper1Remaining; + return true; + } + + if (!DualHopperDispensePlanner.TryCreate( + tokenCount, + _configuredHopper1Inventory, + _configuredHopper2Inventory, + out DualHopperDispensePlan plan)) + { + return false; + } + + _plannedHopper1Remaining = plan.Hopper1Count; + _plannedHopper2Remaining = plan.Hopper2Count; + + return true; + } + + private void ConfirmHopperPulse() + { + if (_requestedDispenseCount <= 0 + || _currentDispenseChunkCount <= 0 + || _hopperErrorAwaitingCredit) + { + return; + } + + _currentDispenseChunkConfirmed++; + _confirmedDispenseCount++; + AddConfirmedForActiveHopper(1); + DispenseProgressChanged?.Invoke(_confirmedDispenseCount, _requestedDispenseCount); + if (_currentDispenseChunkConfirmed < _currentDispenseChunkCount) + { + return; + } + + if (_remainingDispenseCount > 0) + { + SendNextDispenseChunk(); + return; + } + + FinishDispense(true, _confirmedDispenseCount, null); + } + + private void BeginHopperFailure() + { + if (_requestedDispenseCount <= 0 || _hopperErrorAwaitingCredit) + { + return; + } + + _hopperErrorAwaitingCredit = true; + _hopperCreditDeadlineAt = _lastUpdateMilliseconds + HopperCreditTimeoutMilliseconds; + } + + private void CompleteHopperFailureFromCredit(int remainingCredit) + { + if (!_hopperErrorAwaitingCredit || _requestedDispenseCount <= 0) + { + return; + } + + int currentChunkDispensed = Math.Clamp( + _currentDispenseChunkCount - remainingCredit, + 0, + _currentDispenseChunkCount); + currentChunkDispensed = Math.Max(currentChunkDispensed, _currentDispenseChunkConfirmed); + int additionalConfirmed = currentChunkDispensed - _currentDispenseChunkConfirmed; + if (additionalConfirmed > 0) + { + _confirmedDispenseCount += additionalConfirmed; + AddConfirmedForActiveHopper(additionalConfirmed); + } + + string error = _activeDispenseHopper == HopperChannel.Hopper1 + ? "HOPPER1_ERROR" + : "HOPPER2_ERROR"; + FinishDispense(false, _confirmedDispenseCount, error); + } + + private void SendNextDispenseChunk() + { + int available = _plannedHopper1Remaining > 0 + ? _plannedHopper1Remaining + : _plannedHopper2Remaining; + _activeDispenseHopper = _plannedHopper1Remaining > 0 + ? HopperChannel.Hopper1 + : HopperChannel.Hopper2; + + int chunkCount = Math.Min( + PeripheryProtocolCommands.MaxHopperDispenseBatch, + available); + if (_activeDispenseHopper == HopperChannel.Hopper1) + { + _plannedHopper1Remaining -= chunkCount; + } + else + { + _plannedHopper2Remaining -= chunkCount; + } + + _remainingDispenseCount -= chunkCount; + _currentDispenseChunkCount = chunkCount; + _currentDispenseChunkConfirmed = 0; + Send(_activeDispenseHopper == HopperChannel.Hopper1 + ? PeripheryProtocolCommands.DispenseFromHopper1(chunkCount) + : PeripheryProtocolCommands.DispenseFromHopper2(chunkCount)); + } + + private void AddConfirmedForActiveHopper(int count) + { + if (_activeDispenseHopper == HopperChannel.Hopper1) + { + _confirmedHopper1Count += count; + } + else + { + _confirmedHopper2Count += count; + } + } + + private void FinishDispense(bool success, int dispensed, string? error) + { + int hopper1 = _confirmedHopper1Count; + int hopper2 = _confirmedHopper2Count; + ResetDispenseState(); + if (hopper1 > 0 || hopper2 > 0) + { + HopperDispenseAccounted?.Invoke(hopper1, hopper2); + } + + DispenseFinished?.Invoke(success, dispensed, error); + } + + private void ResetDispenseState() + { + _requestedDispenseCount = 0; + _confirmedDispenseCount = 0; + _remainingDispenseCount = 0; + _plannedHopper1Remaining = 0; + _plannedHopper2Remaining = 0; + _confirmedHopper1Count = 0; + _confirmedHopper2Count = 0; + _currentDispenseChunkCount = 0; + _currentDispenseChunkConfirmed = 0; + _hopperErrorAwaitingCredit = false; + _hopperCreditDeadlineAt = ulong.MaxValue; + if (_ready) + { + _nextCashlessKeepAliveAt = 0; + } + } + + private void UpdateDigitalInputPolling(ulong nowMilliseconds) + { + if (!_ready || !HasConfiguredDigitalInput) + { + return; + } + + if (_nextDigitalInputPollAt == ulong.MaxValue) + { + _nextDigitalInputPollAt = nowMilliseconds + _digitalInputPollMilliseconds; + return; + } + + if (nowMilliseconds < _nextDigitalInputPollAt) + { + return; + } + + Send(PeripheryProtocolCommands.QueryDigitalInputs); + _nextDigitalInputPollAt = nowMilliseconds + _digitalInputPollMilliseconds; + } + + private void ApplyDigitalInputs(int inputMask) + { + int? previousMask = _lastDigitalInputMask; + bool serviceActivated = _serviceButtonInputIndex >= 0 + && previousMask.HasValue + && IsInputActive(inputMask, _serviceButtonInputIndex, _serviceButtonActiveHigh) + && !IsInputActive(previousMask.Value, _serviceButtonInputIndex, _serviceButtonActiveHigh); + _lastDigitalInputMask = inputMask; + + if (_stockSensorInputIndex >= 0) + { + bool inputHigh = IsInputHigh(inputMask, _stockSensorInputIndex); + bool isLow = inputHigh == _stockLowWhenInputHigh; + SetHopperStockLevel( + HopperChannel.Hopper1, + isLow ? MachineStockLevel.Low : MachineStockLevel.Enough); + } + + if (_hopper2StockSensorInputIndex >= 0) + { + bool inputHigh = IsInputHigh(inputMask, _hopper2StockSensorInputIndex); + bool isLow = inputHigh == _hopper2StockLowWhenInputHigh; + SetHopperStockLevel( + HopperChannel.Hopper2, + isLow ? MachineStockLevel.Low : MachineStockLevel.Enough); + } + + if (serviceActivated) + { + ServiceRequested?.Invoke(); + } + + // IN24 остаётся документированным физическим датчиком первого хоппера, + // но новая прошивка сама передаёт надёжные HOPPER1 PULSE=1 при прямом моторе. + // Поэтому INPUT-фронты не участвуют ни в выдаче, ни в пересчёте и не дублируют строки платы. + } + + private void SetHopperStockLevel(HopperChannel hopper, MachineStockLevel level) + { + MachineStockLevel current = hopper == HopperChannel.Hopper1 + ? Hopper1StockLevel + : Hopper2StockLevel; + if (current == level) + { + return; + } + + if (hopper == HopperChannel.Hopper1) + { + Hopper1StockLevel = level; + } + else + { + Hopper2StockLevel = level; + } + + HopperStockChanged?.Invoke(hopper, level); + MachineStockLevel aggregate = _hopper2StockSensorInputIndex < 0 + ? Hopper1StockLevel + : _stockSensorInputIndex < 0 + ? Hopper2StockLevel + : Hopper1StockLevel == MachineStockLevel.Enough + || Hopper2StockLevel == MachineStockLevel.Enough + ? MachineStockLevel.Enough + : Hopper1StockLevel == MachineStockLevel.Low + && Hopper2StockLevel == MachineStockLevel.Low + ? MachineStockLevel.Low + : MachineStockLevel.Unknown; + if (aggregate != StockLevel) + { + StockLevel = aggregate; + StockChanged?.Invoke(aggregate); + } + } + + private void UpdateTokenRecountTimeout(ulong nowMilliseconds) + { + if (!_tokenRecountInProgress + || nowMilliseconds < _lastTokenRecountPulseAt + || nowMilliseconds - _lastTokenRecountPulseAt < TokenRecountSilenceMilliseconds) + { + return; + } + + CompleteTokenRecount(true, null, stopMotor: true); + } + + private void CountTokenRecountPulse() + { + _tokenRecountCount++; + _lastTokenRecountPulseAt = _lastUpdateMilliseconds; + TokenRecountProgressChanged?.Invoke(_tokenRecountCount); + HopperTokenRecountProgressChanged?.Invoke(_tokenRecountHopper, _tokenRecountCount); + } + + private void UpdateHopperCreditTimeout(ulong nowMilliseconds) + { + if (!_hopperErrorAwaitingCredit + || nowMilliseconds < _hopperCreditDeadlineAt) + { + return; + } + + int dispensed = _confirmedDispenseCount; + string error = _activeDispenseHopper == HopperChannel.Hopper1 + ? "HOPPER1_CREDIT_TIMEOUT" + : "HOPPER2_CREDIT_TIMEOUT"; + FinishDispense(false, dispensed, error); + } + + private void CompleteTokenRecount(bool success, string? errorCode, bool stopMotor) + { + if (!_tokenRecountInProgress) + { + return; + } + + int counted = _tokenRecountCount; + HopperChannel hopper = _tokenRecountHopper; + ResetTokenRecountState(); + if (stopMotor && _ready && _port.IsConnected) + { + Send(hopper == HopperChannel.Hopper1 + ? PeripheryProtocolCommands.DisableHopper1Motor + : PeripheryProtocolCommands.DisableHopper2Motor); + _nextCashlessKeepAliveAt = 0; + } + + TokenRecountFinished?.Invoke(success, counted, errorCode); + HopperTokenRecountFinished?.Invoke(hopper, success, counted, errorCode); + } + + private void ResetTokenRecountState() + { + _tokenRecountInProgress = false; + _tokenRecountCount = 0; + _lastTokenRecountPulseAt = 0; + } + + private static bool IsInputActive(int inputMask, int inputIndex, bool activeHigh) => + IsInputHigh(inputMask, inputIndex) == activeHigh; + + private static bool IsInputHigh(int inputMask, int inputIndex) => + (inputMask & (1 << inputIndex)) != 0; + + private bool RequireReady() + { + if (_ready && _port.IsConnected) + { + return true; + } + + FaultOccurred?.Invoke(MachineFault.Unavailable); + return false; + } + + private bool RequireOperational() + { + if (!RequireReady()) + { + return false; + } + + if (_dispenseMode != PeripheryDispenseMode.Unsupported) + { + return true; + } + + AppLogger.Error("PeripheryController", "Приём оплаты заблокирован: безопасная команда выдачи не настроена."); + FaultOccurred?.Invoke(MachineFault.Unavailable); + return false; + } + + private void Send(string command) + { + try + { + _port.SendCommand(command); + } + catch (InvalidOperationException) + { + AppLogger.Debug( + "PeripheryController", + $"Команда не поставлена в транспорт: connected={_port.IsConnected}, state={ConnectionState}, " + + $"authState={_authenticator.State}."); + SetConnectionState(MachineConnectionState.Disconnected); + FaultOccurred?.Invoke(MachineFault.ConnectionLost); + } + } + + private void SetConnectionState(MachineConnectionState state) + { + if (ConnectionState == state) + { + return; + } + + MachineConnectionState previous = ConnectionState; + ConnectionState = state; + AppLogger.Debug( + "PeripheryController", + $"Переход соединения: {previous} -> {state}; authState={_authenticator.State}, transportConnected={_port.IsConnected}."); + ConnectionStateChanged?.Invoke(state); + } +} diff --git a/src/hardware/PeripheryController/PeripheryMachineController.cs.uid b/src/hardware/PeripheryController/PeripheryMachineController.cs.uid new file mode 100644 index 0000000..5ca0821 --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryMachineController.cs.uid @@ -0,0 +1 @@ +uid://ctm0wevd3s7jh diff --git a/src/hardware/PeripheryController/PeripheryProtocol.cs b/src/hardware/PeripheryController/PeripheryProtocol.cs new file mode 100644 index 0000000..140290d --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryProtocol.cs @@ -0,0 +1,358 @@ +using System; +using System.Globalization; + +namespace Exchanger.Hardware.PeripheryController; + +public enum PeripheryMessageKind +{ + Unknown, + StartupBanner, + Ready, + HostAuthorizationAccepted, + AuthorizationConfirmed, + EncryptedResponse, + Challenge, + MoneyCoins, + MoneyBill, + MoneyCashless, + CoinPulse, + Hopper1Ok, + Hopper1Error, + Hopper1Append, + Hopper1Credit, + Hopper1Pulse, + Hopper2Queued, + Hopper2Ok, + Hopper2Error, + Hopper2Append, + Hopper2Credit, + Hopper2Pulse, + Service, + ControllerError, + TransportError, + DigitalInputs, +} + +public readonly record struct PeripheryMessage( + PeripheryMessageKind Kind, + int NumericValue = 0, + string Payload = ""); + +/// +/// Чистый парсер входных ASCII-кадров протокола универсального контроллера 2.3.5. +/// Не журналирует сырые данные и не зависит от Godot. +/// +public static class PeripheryProtocolParser +{ + public static PeripheryMessage Parse(string frame) + { + string value = (frame ?? string.Empty).Trim(); + const string startupBannerPrefix = "periphery controller ver_"; + if (value.StartsWith(startupBannerPrefix, StringComparison.Ordinal) + && !string.IsNullOrWhiteSpace(value[startupBannerPrefix.Length..])) + { + return new PeripheryMessage( + PeripheryMessageKind.StartupBanner, + Payload: value[startupBannerPrefix.Length..].Trim()); + } + + if (value.Equals("READY!", StringComparison.Ordinal)) + { + return new PeripheryMessage(PeripheryMessageKind.Ready); + } + + if (value.Equals("AUTH_PC_OK", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.HostAuthorizationAccepted); + } + + if (value.Equals("AUTH_CNT_OK", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.AuthorizationConfirmed); + } + + if (value.Equals("SERVICE", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.Service); + } + + if (value.Equals("COIN", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.CoinPulse); + } + + if (value.Equals("HOPPER1 OK", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper1Ok); + } + + if (value.Equals("HOPPER1 ERROR", StringComparison.OrdinalIgnoreCase) + || value.Equals("HOPPER ERROR", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper1Error); + } + + if (TryParseHopperValue(value, 1, "APPEND", minimum: 1, out int hopper1Append)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper1Append, hopper1Append); + } + + if (TryParseHopperValue(value, 1, "CREDIT", minimum: 0, out int hopper1Credit)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper1Credit, hopper1Credit); + } + + if (TryParseHopperValue(value, 1, "PULSE", minimum: 1, out int hopper1Pulse) + && hopper1Pulse == 1) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper1Pulse, hopper1Pulse); + } + + if (value.Equals("HOPPER2 OK", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper2Ok); + } + + if (value.Equals("HOPPER2 ERROR", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper2Error); + } + + if (TryParseHopperValue(value, 2, "APPEND", minimum: 1, out int hopper2Append)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper2Append, hopper2Append); + } + + if (TryParseHopperValue(value, 2, "CREDIT", minimum: 0, out int hopper2Credit)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper2Credit, hopper2Credit); + } + + if (TryParseHopperValue(value, 2, "PULSE", minimum: 1, out int hopper2Pulse) + && hopper2Pulse == 1) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper2Pulse, hopper2Pulse); + } + + if (TryParseHopper2Queued(value, out int queuedCount)) + { + return new PeripheryMessage(PeripheryMessageKind.Hopper2Queued, queuedCount); + } + + if (TryParseHexPayload(value, "RAES", out string encrypted)) + { + return new PeripheryMessage(PeripheryMessageKind.EncryptedResponse, Payload: encrypted); + } + + if (TryParseHexPayload(value, "CHAL", out string challenge)) + { + return new PeripheryMessage(PeripheryMessageKind.Challenge, Payload: challenge); + } + + if (TryParseMoney(value, "MONEY:COINS:", PeripheryMessageKind.MoneyCoins, out PeripheryMessage coins)) + { + return coins; + } + + if (TryParseMoney(value, "MONEY:BILL:", PeripheryMessageKind.MoneyBill, out PeripheryMessage bill)) + { + return bill; + } + + if (TryParseMoney(value, "MONEY:CASHLESS:", PeripheryMessageKind.MoneyCashless, out PeripheryMessage cashless)) + { + return cashless; + } + + if (value.StartsWith("TRANSPORT_ERROR:", StringComparison.Ordinal)) + { + return new PeripheryMessage(PeripheryMessageKind.TransportError); + } + + if (value.StartsWith("ERROR", StringComparison.OrdinalIgnoreCase)) + { + return new PeripheryMessage(PeripheryMessageKind.ControllerError); + } + + if (value.StartsWith("INPUT", StringComparison.OrdinalIgnoreCase) + && int.TryParse(value[5..].Trim(), NumberStyles.None, CultureInfo.InvariantCulture, out int inputMask) + && inputMask is >= 0 and <= 67_108_863) + { + return new PeripheryMessage(PeripheryMessageKind.DigitalInputs, inputMask); + } + + return new PeripheryMessage(PeripheryMessageKind.Unknown); + } + + private static bool TryParseMoney( + string value, + string prefix, + PeripheryMessageKind kind, + out PeripheryMessage message) + { + message = default; + if (!value.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)) + { + return false; + } + + string amountText = value[prefix.Length..]; + if (!int.TryParse(amountText, NumberStyles.None, CultureInfo.InvariantCulture, out int amount) + || amount <= 0) + { + return false; + } + + message = new PeripheryMessage(kind, amount); + return true; + } + + private static bool TryParseHopper2Queued(string value, out int count) + { + const string prefix = "HOPPER2 QUEUED "; + count = 0; + if (!value.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)) + { + return false; + } + + string remainder = value[prefix.Length..]; + int separatorIndex = remainder.IndexOf(' '); + if (separatorIndex <= 0 + || !int.TryParse( + remainder[..separatorIndex], + NumberStyles.None, + CultureInfo.InvariantCulture, + out count) + || count <= 0) + { + count = 0; + return false; + } + + string unit = remainder[(separatorIndex + 1)..]; + return unit.Equals("PRIZE", StringComparison.OrdinalIgnoreCase) + || unit.Equals("PRIZES", StringComparison.OrdinalIgnoreCase); + } + + private static bool TryParseHopperValue( + string value, + int hopperNumber, + string field, + int minimum, + out int number) + { + string prefix = $"HOPPER{hopperNumber.ToString(CultureInfo.InvariantCulture)} {field}="; + number = 0; + return value.StartsWith(prefix, StringComparison.OrdinalIgnoreCase) + && int.TryParse( + value[prefix.Length..], + NumberStyles.None, + CultureInfo.InvariantCulture, + out number) + && number >= minimum; + } + + private static bool TryParseHexPayload(string value, string prefix, out string payload) + { + payload = string.Empty; + if (!value.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)) + { + return false; + } + + // plate_config_app допускает как слитный формат CHAL/RAES, + // так и диагностические варианты с пробелом или двоеточием после префикса. + string candidate = value[prefix.Length..].Trim().TrimStart(':').Trim(); + if (candidate.Length != 32) + { + return false; + } + + foreach (char character in candidate) + { + if (!Uri.IsHexDigit(character)) + { + return false; + } + } + + payload = candidate.ToUpperInvariant(); + return true; + } +} + +public static class PeripheryProtocolCommands +{ + public const int MaxHopperDispenseBatch = 99; + public const string ResetController = "00"; + public const string ClearCommandQueue = "90"; + public const string QueryCoinAcceptorStatus = "140"; + public const string EnableCoinSmartMode = "141"; + public const string DisableCoinAcceptor = "142"; + public const string QueryBillAcceptorStatus = "150"; + public const string EnableBillAcceptor = "151"; + public const string DisableBillAcceptor = "152"; + public const string QueryCashlessStatus = "160"; + public const string EnableCashless = "161"; + public const string DisableCashless = "162"; + public const string DisableHopper1Motor = "300"; + public const string EnableHopper1Motor = "301"; + public const string QueryHopper1Credit = "3090"; + public const string QueryHopper1Queue = QueryHopper1Credit; + public const string DisableHopper2Motor = "400"; + public const string EnableHopper2Motor = "401"; + public const string QueryHopper2Credit = "4090"; + public const string QueryHopper2Queue = QueryHopper2Credit; + public const string DispenseOneFromHopper2 = "4091"; + public const string QueryDigitalInputs = "91"; + public const string QueryControllerStatus = "99"; + + public static string AcknowledgeCoinPulse() => "10"; + + public static string AcknowledgeCoins(int amountRubles) => MoneyAcknowledgement("COINS", amountRubles); + + public static string AcknowledgeBill(int amountRubles) => MoneyAcknowledgement("BILL", amountRubles); + + public static string AcknowledgeCashless(int amountRubles) => MoneyAcknowledgement("CASHLESS", amountRubles); + + public static string RequestCashlessPayment(int amountRubles) + { + if (amountRubles is < 1 or > 9999) + { + throw new ArgumentOutOfRangeException(nameof(amountRubles), "Протокол 163 допускает сумму от 1 до 9999 ₽."); + } + + return $"163{amountRubles.ToString(CultureInfo.InvariantCulture)}"; + } + + public static string DispenseFromHopper1(int tokenCount) + { + if (tokenCount is < 1 or > MaxHopperDispenseBatch) + { + throw new ArgumentOutOfRangeException(nameof(tokenCount), "Команда выдачи 309N допускает от 1 до 99 жетонов; 3090 зарезервирована для запроса CREDIT."); + } + + return $"309{tokenCount.ToString(CultureInfo.InvariantCulture)}"; + } + + public static string DispenseFromHopper2(int tokenCount) + { + if (tokenCount is < 1 or > MaxHopperDispenseBatch) + { + throw new ArgumentOutOfRangeException(nameof(tokenCount), "Команда 409zz допускает от 1 до 99 единиц."); + } + + return $"409{tokenCount.ToString(CultureInfo.InvariantCulture)}"; + } + + private static string MoneyAcknowledgement(string source, int amountRubles) + { + if (amountRubles <= 0) + { + throw new ArgumentOutOfRangeException(nameof(amountRubles)); + } + + return $"ASK:{source}:{amountRubles.ToString(CultureInfo.InvariantCulture)}"; + } +} diff --git a/src/hardware/PeripheryController/PeripheryProtocol.cs.uid b/src/hardware/PeripheryController/PeripheryProtocol.cs.uid new file mode 100644 index 0000000..0a29a6d --- /dev/null +++ b/src/hardware/PeripheryController/PeripheryProtocol.cs.uid @@ -0,0 +1 @@ +uid://crn2fbj5011l8 diff --git a/src/hardware/SerialPortHardware/SerialFrameDecoder.cs b/src/hardware/SerialPortHardware/SerialFrameDecoder.cs new file mode 100644 index 0000000..6a61b9a --- /dev/null +++ b/src/hardware/SerialPortHardware/SerialFrameDecoder.cs @@ -0,0 +1,128 @@ +using System; +using System.Collections.Generic; +using System.Text; + +namespace Exchanger.Hardware.SerialPortHardware; + +/// +/// Потоковый ASCII-фреймер протокола 2.3.5. CR и LF независимо завершают +/// кадр; пустая половина CRLF игнорируется. +/// +public sealed class SerialFrameDecoder +{ + private readonly int _maximumLength; + private readonly int _timeoutMilliseconds; + private readonly List _buffer = new(); + private long _lastByteAtMilliseconds = -1; + private bool _discardUntilTerminator; + + public SerialFrameDecoder(int maximumLength = 1024, int timeoutMilliseconds = 100) + { + _maximumLength = Math.Clamp(maximumLength, 2, 65536); + _timeoutMilliseconds = Math.Clamp(timeoutMilliseconds, 10, 5000); + } + + public int DroppedFrameCount { get; private set; } + + public IReadOnlyList Push(ReadOnlySpan bytes, long nowMilliseconds) + { + Expire(nowMilliseconds); + var frames = new List(); + + foreach (byte value in bytes) + { + if (value is 0x0D or 0x0A) + { + if (_discardUntilTerminator) + { + Reset(); + } + else + { + CompleteFrame(frames); + } + + continue; + } + + _lastByteAtMilliseconds = nowMilliseconds; + if (_discardUntilTerminator) + { + continue; + } + + if (value > 0x7F || _buffer.Count >= _maximumLength) + { + if (_buffer.Count == 0) + { + DroppedFrameCount++; + } + else + { + DropCurrentFrame(); + } + + _discardUntilTerminator = true; + _lastByteAtMilliseconds = nowMilliseconds; + continue; + } + + _buffer.Add(value); + } + + return frames; + } + + public void Expire(long nowMilliseconds) + { + if ((_buffer.Count == 0 && !_discardUntilTerminator) || _lastByteAtMilliseconds < 0) + { + return; + } + + if (nowMilliseconds - _lastByteAtMilliseconds >= _timeoutMilliseconds) + { + if (_discardUntilTerminator) + { + Reset(); + } + else + { + DropCurrentFrame(); + } + } + } + + public void Reset() + { + _buffer.Clear(); + _lastByteAtMilliseconds = -1; + _discardUntilTerminator = false; + } + + private void CompleteFrame(List frames) + { + if (_buffer.Count >= 2) + { + frames.Add(Encoding.ASCII.GetString(_buffer.ToArray())); + } + else if (_buffer.Count > 0) + { + DroppedFrameCount++; + } + + _buffer.Clear(); + _lastByteAtMilliseconds = -1; + } + + private void DropCurrentFrame() + { + if (_buffer.Count > 0) + { + DroppedFrameCount++; + } + + _buffer.Clear(); + _lastByteAtMilliseconds = -1; + } +} diff --git a/src/hardware/SerialPortHardware/SerialFrameDecoder.cs.uid b/src/hardware/SerialPortHardware/SerialFrameDecoder.cs.uid new file mode 100644 index 0000000..1f0db80 --- /dev/null +++ b/src/hardware/SerialPortHardware/SerialFrameDecoder.cs.uid @@ -0,0 +1 @@ +uid://brlo60xmn61yg diff --git a/src/hardware/SerialPortHardware/SerialPortHardware.cs b/src/hardware/SerialPortHardware/SerialPortHardware.cs new file mode 100644 index 0000000..876950c --- /dev/null +++ b/src/hardware/SerialPortHardware/SerialPortHardware.cs @@ -0,0 +1,320 @@ +using Exchanger.Core.Logging; +using Exchanger.Hardware.Abstractions; +using System; +using System.Collections.Concurrent; +using System.IO.Ports; +using System.Threading; + +namespace Exchanger.Hardware.SerialPortHardware; + +/// +/// Desktop serial-транспорт Windows/Linux: 8N1, без flow control, один worker для +/// последовательного чтения/записи и очередь доставки событий в главный поток. +/// +public sealed class SerialPortHardware : IHardwarePort, IDisposable +{ + private readonly ConcurrentQueue _outgoing = new(); + private readonly ConcurrentQueue _pendingEvents = new(); + private readonly object _lifecycleLock = new(); + private readonly int _maximumFrameLength; + private readonly int _frameTimeoutMilliseconds; + private SerialPort? _serialPort; + private CancellationTokenSource? _cancellation; + private Thread? _worker; + private volatile bool _isConnected; + private bool _disposed; + + public SerialPortHardware(int maximumFrameLength = 1024, int frameTimeoutMilliseconds = 100) + { + _maximumFrameLength = Math.Clamp(maximumFrameLength, 2, 65536); + _frameTimeoutMilliseconds = Math.Clamp(frameTimeoutMilliseconds, 10, 5000); + } + + public bool IsConnected => _isConnected; + + public event Action? OnDataReceived; + + public event Action? ConnectionChanged; + + public void Connect(string portName, int baudRate) + { + ObjectDisposedException.ThrowIf(_disposed, this); + if (string.IsNullOrWhiteSpace(portName)) + { + throw new ArgumentException("Имя последовательного порта не задано.", nameof(portName)); + } + + lock (_lifecycleLock) + { + AppLogger.Debug( + "SerialPort", + $"Запрошено открытие: platform={GetPlatformName()}, port={portName.Trim()}, " + + $"baud={baudRate}, frameTimeoutMs={_frameTimeoutMilliseconds}, " + + $"maxFrameLength={_maximumFrameLength}."); + DisconnectUnsafe(); + + var port = new SerialPort(portName.Trim(), baudRate, Parity.None, 8, StopBits.One) + { + Handshake = Handshake.None, + Encoding = System.Text.Encoding.ASCII, + NewLine = "\r\n", + ReadTimeout = 25, + WriteTimeout = 500, + }; + + try + { + AppLogger.Debug("SerialPort", "Вызвано системное открытие последовательного устройства."); + port.Open(); + AppLogger.Debug("SerialPort", "Устройство открыто; начинается аппаратный reset контроллера."); + ResetControllerForStartup(port); + } + catch (Exception exception) when (exception is UnauthorizedAccessException or ArgumentException or InvalidOperationException or System.IO.IOException) + { + port.Dispose(); + _pendingEvents.Enqueue(PortEvent.Disconnected); + AppLogger.Debug( + "SerialPort", + $"Открытие завершилось ошибкой: reason={DescribeConnectionFailure(exception)}, " + + $"exception={exception.GetType().Name}, hresult=0x{exception.HResult:X8}."); + AppLogger.Error("SerialPort", $"Не удалось открыть {portName}: {exception.GetType().Name}."); + return; + } + + _serialPort = port; + _cancellation = new CancellationTokenSource(); + _isConnected = true; + _pendingEvents.Enqueue(PortEvent.Connected); + _worker = new Thread(() => WorkerLoop(port, _cancellation.Token)) + { + IsBackground = true, + Name = "Exchanger.SerialPort", + }; + _worker.Start(); + AppLogger.Debug( + "SerialPort", + $"Worker запущен: managedThreadId={_worker.ManagedThreadId}, background={_worker.IsBackground}."); + AppLogger.Info("SerialPort", $"Открыт {port.PortName} @ {port.BaudRate}, 8N1, flow control None."); + } + } + + public void Disconnect() + { + lock (_lifecycleLock) + { + DisconnectUnsafe(); + } + } + + public void SendCommand(string command) + { + ObjectDisposedException.ThrowIf(_disposed, this); + string normalized = (command ?? string.Empty).TrimEnd('\r', '\n'); + if (normalized.Length < 2) + { + throw new ArgumentException("Команда контроллера должна содержать минимум два символа.", nameof(command)); + } + + if (!_isConnected) + { + throw new InvalidOperationException("Последовательный порт не подключён."); + } + + _outgoing.Enqueue(normalized); + } + + public void ProcessPendingEvents() + { + while (_pendingEvents.TryDequeue(out PortEvent portEvent)) + { + if (portEvent.ConnectionState.HasValue) + { + ConnectionChanged?.Invoke(portEvent.ConnectionState.Value); + } + else if (portEvent.Frame is not null) + { + OnDataReceived?.Invoke(portEvent.Frame); + } + } + } + + public void Dispose() + { + if (_disposed) + { + return; + } + + Disconnect(); + _disposed = true; + } + + private void WorkerLoop(SerialPort port, CancellationToken cancellationToken) + { + var decoder = new SerialFrameDecoder(_maximumFrameLength, _frameTimeoutMilliseconds); + var buffer = new byte[256]; + long receivedBytes = 0; + long decodedFrames = 0; + long sentCommands = 0; + + try + { + AppLogger.Debug("SerialPort", "Worker вошёл в цикл чтения и записи."); + while (!cancellationToken.IsCancellationRequested) + { + while (_outgoing.TryDequeue(out string? command)) + { + port.Write(command + "\r\n"); + sentCommands++; + if (command.StartsWith("07", StringComparison.Ordinal) + || command.StartsWith("08", StringComparison.Ordinal)) + { + AppLogger.Debug( + "SerialPort", + $"Отправлен скрытый кадр авторизации: kind={DescribeAuthenticationCommand(command)}, " + + $"length={command.Length}."); + } + } + + try + { + int read = port.Read(buffer, 0, buffer.Length); + receivedBytes += read; + long now = Environment.TickCount64; + foreach (string frame in decoder.Push(buffer.AsSpan(0, read), now)) + { + decodedFrames++; + _pendingEvents.Enqueue(PortEvent.Data(frame)); + } + } + catch (TimeoutException) + { + decoder.Expire(Environment.TickCount64); + } + } + } + catch (Exception exception) when (IsWorkerTerminationException(exception)) + { + if (!cancellationToken.IsCancellationRequested) + { + AppLogger.Debug( + "SerialPort", + $"Worker остановлен транспортной ошибкой: reason={DescribeConnectionFailure(exception)}, " + + $"exception={exception.GetType().Name}, hresult=0x{exception.HResult:X8}."); + } + } + finally + { + AppLogger.Debug( + "SerialPort", + $"Worker завершён: cancelled={cancellationToken.IsCancellationRequested}, " + + $"sentCommands={sentCommands}, receivedBytes={receivedBytes}, decodedFrames={decodedFrames}."); + _isConnected = false; + _pendingEvents.Enqueue(PortEvent.Disconnected); + } + } + + internal static bool IsWorkerTerminationException(Exception exception) => + exception is OperationCanceledException + or InvalidOperationException + or UnauthorizedAccessException + or System.IO.IOException; + + private static void ResetControllerForStartup(SerialPort port) + { + // Актуальная прошивка публикует обязательный startup-banner только после + // перезагрузки. Последовательность совпадает с Plate Config App: + // очистить старый ввод, DTR=0, импульс RTS и затем начать чтение. + port.DiscardInBuffer(); + port.DtrEnable = false; + port.RtsEnable = true; + AppLogger.Debug("SerialPort", "Reset: входной буфер очищен, DTR=0, RTS=1 на 100 мс."); + try + { + Thread.Sleep(100); + } + finally + { + port.RtsEnable = false; + AppLogger.Debug("SerialPort", "Reset: RTS=0; транспорт готов принимать startup-banner."); + } + } + + private void DisconnectUnsafe() + { + CancellationTokenSource? cancellation = _cancellation; + Thread? worker = _worker; + SerialPort? port = _serialPort; + bool hadTransport = cancellation is not null || worker is not null || port is not null; + + if (hadTransport) + { + AppLogger.Debug( + "SerialPort", + $"Начато отключение: isOpen={port?.IsOpen == true}, workerAlive={worker?.IsAlive == true}."); + } + + _cancellation = null; + _worker = null; + _serialPort = null; + _isConnected = false; + cancellation?.Cancel(); + + try + { + port?.Close(); + } + catch (Exception exception) when (exception is InvalidOperationException or System.IO.IOException) + { + AppLogger.Warning("SerialPort", $"Ошибка закрытия последовательного порта: {exception.GetType().Name}."); + } + + if (worker is not null && worker.IsAlive && !worker.Join(2000)) + { + AppLogger.Warning("SerialPort", "Worker последовательного порта не завершился за 2 секунды."); + } + + port?.Dispose(); + cancellation?.Dispose(); + while (_outgoing.TryDequeue(out _)) + { + } + + if (hadTransport) + { + AppLogger.Debug("SerialPort", "Отключение завершено; очередь исходящих команд очищена."); + } + } + + private static string GetPlatformName() => + OperatingSystem.IsWindows() + ? "Windows" + : OperatingSystem.IsLinux() + ? "Linux" + : "Unsupported"; + + private static string DescribeAuthenticationCommand(string command) => + command.StartsWith("07", StringComparison.Ordinal) + ? "HostChallenge" + : "ControllerChallengeResponse"; + + private static string DescribeConnectionFailure(Exception exception) => exception switch + { + UnauthorizedAccessException => "AccessDeniedOrPortBusy", + ArgumentException => "InvalidPortOrParameters", + InvalidOperationException => "InvalidTransportState", + System.IO.IOException => "DeviceMissingOrIoFailure", + OperationCanceledException => "Cancelled", + _ => "Unknown", + }; + + private readonly record struct PortEvent(string? Frame, bool? ConnectionState) + { + public static PortEvent Connected { get; } = new(null, true); + + public static PortEvent Disconnected { get; } = new(null, false); + + public static PortEvent Data(string frame) => new(frame, null); + + } +} diff --git a/src/hardware/SerialPortHardware/SerialPortHardware.cs.uid b/src/hardware/SerialPortHardware/SerialPortHardware.cs.uid new file mode 100644 index 0000000..e02bc6e --- /dev/null +++ b/src/hardware/SerialPortHardware/SerialPortHardware.cs.uid @@ -0,0 +1 @@ +uid://5wuqmtrac6h3 diff --git a/src/hardware/UsbSerialHardware/UsbSerialHardware.cs b/src/hardware/UsbSerialHardware/UsbSerialHardware.cs new file mode 100644 index 0000000..f8d584b --- /dev/null +++ b/src/hardware/UsbSerialHardware/UsbSerialHardware.cs @@ -0,0 +1,38 @@ +using Exchanger.Core.Logging; +using Exchanger.Hardware.Abstractions; +using System; + +namespace Exchanger.Hardware.UsbSerialHardware; + +/// +/// Android-заглушка, сохраняющая платформенную границу до выбора USB-Serial плагина. +/// +public sealed class UsbSerialHardware : IHardwarePort +{ + public bool IsConnected => false; + + public event Action? OnDataReceived; + + public event Action? ConnectionChanged; + + public void Connect(string portName, int baudRate) + { + AppLogger.Warning("UsbSerial", "Android USB-Serial пока не поддерживается."); + ConnectionChanged?.Invoke(false); + } + + public void Disconnect() + { + AppLogger.Info("UsbSerial", "Запрошено отключение Android-заглушки."); + } + + public void SendCommand(string command) + { + AppLogger.Warning("UsbSerial", $"Команда не отправлена Android-заглушкой: {command.Trim()}"); + OnDataReceived?.Invoke("ERROR:USB_SERIAL_NOT_IMPLEMENTED"); + } + + public void ProcessPendingEvents() + { + } +} diff --git a/src/hardware/UsbSerialHardware/UsbSerialHardware.cs.uid b/src/hardware/UsbSerialHardware/UsbSerialHardware.cs.uid new file mode 100644 index 0000000..4a7706a --- /dev/null +++ b/src/hardware/UsbSerialHardware/UsbSerialHardware.cs.uid @@ -0,0 +1 @@ +uid://dvfi6hxhk3gpk diff --git a/src/images/icon.icns b/src/images/icon.icns new file mode 100644 index 0000000..68b7cf5 Binary files /dev/null and b/src/images/icon.icns differ diff --git a/src/images/icon.ico b/src/images/icon.ico new file mode 100644 index 0000000..32c7ac7 Binary files /dev/null and b/src/images/icon.ico differ diff --git a/src/images/icon.svg b/src/images/icon.svg new file mode 100644 index 0000000..b12bd15 --- /dev/null +++ b/src/images/icon.svg @@ -0,0 +1,69 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/images/icon.svg.import b/src/images/icon.svg.import new file mode 100644 index 0000000..38989ee --- /dev/null +++ b/src/images/icon.svg.import @@ -0,0 +1,43 @@ +[remap] + +importer="texture" +type="CompressedTexture2D" +uid="uid://bexp3q7mygd6c" +path="res://.godot/imported/icon.svg-2faf59513e9e1d465e0f22adeeaee1db.ctex" +metadata={ +"vram_texture": false +} + +[deps] + +source_file="res://src/images/icon.svg" +dest_files=["res://.godot/imported/icon.svg-2faf59513e9e1d465e0f22adeeaee1db.ctex"] + +[params] + +compress/mode=0 +compress/high_quality=false +compress/lossy_quality=0.7 +compress/uastc_level=0 +compress/rdo_quality_loss=0.0 +compress/hdr_compression=1 +compress/normal_map=0 +compress/channel_pack=0 +mipmaps/generate=false +mipmaps/limit=-1 +roughness/mode=0 +roughness/src_normal="" +process/channel_remap/red=0 +process/channel_remap/green=1 +process/channel_remap/blue=2 +process/channel_remap/alpha=3 +process/fix_alpha_border=true +process/premult_alpha=false +process/normal_map_invert_y=false +process/hdr_as_srgb=false +process/hdr_clamp_exposure=false +process/size_limit=0 +detect_3d/compress_to=1 +svg/scale=1.0 +editor/scale_with_editor_scale=false +editor/convert_colors_with_editor_theme=false diff --git a/src/images/logo.png b/src/images/logo.png new file mode 100644 index 0000000..ebbfea7 Binary files /dev/null and b/src/images/logo.png differ diff --git a/src/images/logo.png.import b/src/images/logo.png.import new file mode 100644 index 0000000..04e40cf --- /dev/null +++ b/src/images/logo.png.import @@ -0,0 +1,40 @@ +[remap] + +importer="texture" +type="CompressedTexture2D" +uid="uid://bkcx4v1p6ajo3" +path="res://.godot/imported/logo.png-feb30b4ee05c5098f24a5b07b4f83dcc.ctex" +metadata={ +"vram_texture": false +} + +[deps] + +source_file="res://src/images/logo.png" +dest_files=["res://.godot/imported/logo.png-feb30b4ee05c5098f24a5b07b4f83dcc.ctex"] + +[params] + +compress/mode=0 +compress/high_quality=false +compress/lossy_quality=0.7 +compress/uastc_level=0 +compress/rdo_quality_loss=0.0 +compress/hdr_compression=1 +compress/normal_map=0 +compress/channel_pack=0 +mipmaps/generate=false +mipmaps/limit=-1 +roughness/mode=0 +roughness/src_normal="" +process/channel_remap/red=0 +process/channel_remap/green=1 +process/channel_remap/blue=2 +process/channel_remap/alpha=3 +process/fix_alpha_border=true +process/premult_alpha=false +process/normal_map_invert_y=false +process/hdr_as_srgb=false +process/hdr_clamp_exposure=false +process/size_limit=0 +detect_3d/compress_to=1 diff --git a/src/images/logo.svg b/src/images/logo.svg new file mode 100644 index 0000000..b512c19 --- /dev/null +++ b/src/images/logo.svg @@ -0,0 +1,44 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/images/logo.svg.import b/src/images/logo.svg.import new file mode 100644 index 0000000..0a5bffa --- /dev/null +++ b/src/images/logo.svg.import @@ -0,0 +1,43 @@ +[remap] + +importer="texture" +type="CompressedTexture2D" +uid="uid://cacvqce35twhw" +path="res://.godot/imported/logo.svg-167fad1f97f144e774384fe4943e27d4.ctex" +metadata={ +"vram_texture": false +} + +[deps] + +source_file="res://src/images/logo.svg" +dest_files=["res://.godot/imported/logo.svg-167fad1f97f144e774384fe4943e27d4.ctex"] + +[params] + +compress/mode=0 +compress/high_quality=false +compress/lossy_quality=0.7 +compress/uastc_level=0 +compress/rdo_quality_loss=0.0 +compress/hdr_compression=1 +compress/normal_map=0 +compress/channel_pack=0 +mipmaps/generate=false +mipmaps/limit=-1 +roughness/mode=0 +roughness/src_normal="" +process/channel_remap/red=0 +process/channel_remap/green=1 +process/channel_remap/blue=2 +process/channel_remap/alpha=3 +process/fix_alpha_border=true +process/premult_alpha=false +process/normal_map_invert_y=false +process/hdr_as_srgb=false +process/hdr_clamp_exposure=false +process/size_limit=0 +detect_3d/compress_to=1 +svg/scale=1.0 +editor/scale_with_editor_scale=false +editor/convert_colors_with_editor_theme=false diff --git a/src/scenes/App/App.cs b/src/scenes/App/App.cs new file mode 100644 index 0000000..86c6d9b --- /dev/null +++ b/src/scenes/App/App.cs @@ -0,0 +1,1319 @@ +using Exchanger.Core.Audio; +using Exchanger.Core.Configuration; +using Exchanger.Core.Inventory; +using Exchanger.Core.Logging; +using Exchanger.Core.Navigation; +using Exchanger.Core.Session; +using Exchanger.Core.Theming; +using Exchanger.Core.TechnicalConfiguration; +using Exchanger.Hardware.Abstractions; +using Exchanger.Hardware.MockHardware; +using Exchanger.Hardware.MockMachine; +using Exchanger.Hardware.PeripheryController; +using Exchanger.Hardware.SerialPortHardware; +using Godot; +using System; +using System.Collections.Generic; +using CardAmountScreenControl = Exchanger.Scenes.CardAmountScreen.CardAmountScreen; +using CardCustomAmountScreenControl = Exchanger.Scenes.CardCustomAmountScreen.CardCustomAmountScreen; +using CardTerminalScreenControl = Exchanger.Scenes.CardTerminalScreen.CardTerminalScreen; +using CashPaymentScreenControl = Exchanger.Scenes.CashPaymentScreen.CashPaymentScreen; +using ErrorScreenControl = Exchanger.Scenes.ErrorScreen.ErrorScreen; +using HomeScreenControl = Exchanger.Scenes.HomeScreen.HomeScreen; +using SettingsScreenControl = Exchanger.Scenes.SettingsScreen.SettingsScreen; +using ServiceAccessScreenControl = Exchanger.Scenes.ServiceAccessScreen.ServiceAccessScreen; +using SuccessScreenControl = Exchanger.Scenes.SuccessScreen.SuccessScreen; +using InteractivePetHostControl = Exchanger.UI.InteractivePet.InteractivePetHost; +using KioskFooterControl = Exchanger.UI.KioskFooter.KioskFooter; + +namespace Exchanger.Scenes.App; + +/// +/// Композиционный корень приложения: конфигурация, экраны, сессия и +/// выбранные реализации аппаратных границ. +/// +public partial class App : Node +{ + private SettingsService _settingsService = null!; + private AppSettings _settings = null!; + private TokenInventoryStore _tokenInventoryStore = null!; + private TokenInventorySnapshot _tokenInventory = null!; + private IHardwarePort? _hardwarePort; + private IMachineController _machineController = null!; + private ITokenRecountController? _tokenRecountController; + private IDualHopperMachineController? _dualHopperController; + private IDualHopperTokenRecountController? _dualHopperRecountController; + private MockMachineController? _mockMachine; + private PeripheryMachineController? _peripheryController; + private IDisposable? _controllerCipher; + private SessionController _sessionController = null!; + private ScreenManager _screenManager = null!; + private HomeScreenControl _homeScreen = null!; + private CashPaymentScreenControl _cashPaymentScreen = null!; + private CardAmountScreenControl _cardAmountScreen = null!; + private CardCustomAmountScreenControl _cardCustomAmountScreen = null!; + private CardTerminalScreenControl _cardTerminalScreen = null!; + private SuccessScreenControl _successScreen = null!; + private ErrorScreenControl _errorScreen = null!; + private SettingsScreenControl _settingsScreen = null!; + private ServiceAccessScreenControl _serviceAccessScreen = null!; + private InteractivePetHostControl _interactivePetHost = null!; + private ServiceAccessPolicy _serviceAccessPolicy = null!; + private bool _serviceDispenseInProgress; + private (bool Hopper1Enabled, bool Hopper2Enabled) _configuredHoppers; + private bool _shutdownCompleted; + private HardwareReconnectScheduler _hardwareReconnectScheduler = null!; + private IReadOnlyList _automaticPortCandidates = Array.Empty(); + private int _nextAutomaticPortCandidateIndex; + private bool _automaticPortAttemptInProgress; + private string? _activeHardwarePortName; + private bool _productionKioskMode; + private ulong _nextKioskWindowCheckAt; + private ulong _nextTokenRecountAvailabilityRefreshAt; + private int _lastScreenCount; + private Vector2I _lastScreenSize; + + public override void _EnterTree() + { + _settingsService = AppSettingsLoader.CreateService(); + _settings = AppSettingsLoader.Load(_settingsService); + _configuredHoppers = TechnicalSettings.ResolveConfiguredHoppers(_settings.Hardware.DispenseMode); + AppLogger.Initialize(_settings.Logging); + AppLogger.Debug( + "Application", + $"Старт DEBUG runtime: os={OS.GetName()}, mock={_settings.Hardware.UseMock}, " + + $"port={_settings.Hardware.PortName}, baud={_settings.Hardware.BaudRate}."); + _tokenInventoryStore = TokenInventoryLoader.CreateStore(); + _tokenInventory = _tokenInventoryStore.Load(); + OperationJournal.Initialize(_settings.Logging); + ConfigurationAuditJournal.Initialize(_settings.Logging); + _serviceAccessPolicy = new ServiceAccessPolicy(_settings.Security); + ConfigureWindow(_settings.Window); + AudioSettingsApplier.Apply(_settings.Audio); + + ThemeManager themeManager = GetNode("/root/ThemeManager"); + themeManager.Configure(_settings.Themes); + } + + public override void _Ready() + { + _sessionController = GetNode("SessionController"); + + ConfigureHardware(); + _tokenRecountController = _machineController as ITokenRecountController; + _dualHopperController = _machineController as IDualHopperMachineController; + _dualHopperRecountController = _machineController as IDualHopperTokenRecountController; + _dualHopperController?.SetInventoryAccountingEnabled(_settings.TokenInventory.Enabled); + _dualHopperController?.SetPurchaseLimitEnabled(_settings.TokenInventory.PurchaseLimitEnabled); + (int hopper1Inventory, int hopper2Inventory) = GetConfiguredInventoryCounts(); + _dualHopperController?.SetHopperInventory( + hopper1Inventory, + hopper2Inventory); + + ConfigureScreens(); + SubscribeSession(); + SubscribeMachine(); + _sessionController.Configure(_settings, _machineController, GetTokenPurchaseLimit()); + _homeScreen.SetConnectionState(_machineController.ConnectionState); + RefreshInventoryState(); + OnSessionStateChanged(SessionState.Home); + AppLogger.Debug( + "Application", + $"Первичное подключение: reconnectSeconds={_settings.Hardware.ReconnectIntervalSeconds}, " + + $"handshakeTimeoutMs={_settings.Hardware.HandshakeTimeoutMilliseconds}."); + _hardwareReconnectScheduler = new HardwareReconnectScheduler( + _settings.Hardware.ReconnectIntervalSeconds); + _hardwareReconnectScheduler.ScheduleFrom(Time.GetTicksMsec()); + ConnectConfiguredHardwarePort(refreshAutomaticCandidates: true, attemptKind: "первичное подключение"); + + if (_settings.Hardware.UseMock) + { + _hardwarePort!.SendCommand("PING\n"); + AppLogger.Info("Application", "Mock-сценарий Exchanger запущен."); + } + else + { + AppLogger.Info("Application", "Запущена интеграция универсального периферийного контроллера 2.3.5."); + } + } + + public override void _Process(double delta) + { + _hardwarePort?.ProcessPendingEvents(); + ulong now = Time.GetTicksMsec(); + _peripheryController?.Update(now); + bool transportConnected = _hardwarePort?.IsConnected == true; + if (!_settings.Hardware.UseMock + && _hardwareReconnectScheduler.ObserveConnection(transportConnected, now)) + { + AppLogger.Debug( + "Application", + $"Обнаружен обрыв транспорта; следующая попытка подключения через " + + $"{_settings.Hardware.ReconnectIntervalSeconds} с."); + } + + if (!_settings.Hardware.UseMock + && _hardwarePort is not null + && !transportConnected + && _hardwareReconnectScheduler.TryBeginAttempt(now)) + { + ConnectConfiguredHardwarePort(refreshAutomaticCandidates: true, attemptKind: "reconnect"); + } + + if (_productionKioskMode && now >= _nextKioskWindowCheckAt) + { + _nextKioskWindowCheckAt = now + 2000UL; + EnsureKioskWindowState(); + } + + if (_screenManager is not null + && _screenManager.CurrentScreenId == ScreenId.Settings + && _tokenRecountController?.IsTokenRecountInProgress != true + && now >= _nextTokenRecountAvailabilityRefreshAt) + { + _nextTokenRecountAvailabilityRefreshAt = now + 500UL; + RefreshTokenInventoryControls(preserveStatus: true); + } + } + + public override void _UnhandledInput(InputEvent @event) + { + if (!OS.IsDebugBuild() + || !@event.IsActionPressed("debug_service_settings") + || _sessionController.State != SessionState.Home + || _screenManager.TransitionInProgress + || _screenManager.CurrentScreenId is not (ScreenId.Home or ScreenId.Settings)) + { + return; + } + + OnPhysicalServiceRequested(); + GetViewport().SetInputAsHandled(); + } + + public override void _ExitTree() + { + Shutdown(); + } + + public override void _Notification(int what) + { + if (what == NotificationWMCloseRequest) + { + Shutdown(); + } + else if (what == NotificationApplicationFocusOut) + { + AppLogger.Info("Application", "Окно потеряло фокус; таймауты используют монотонное реальное время."); + } + else if (what == NotificationApplicationFocusIn) + { + AppLogger.Info("Application", "Фокус окна восстановлен."); + EnsureKioskWindowState(); + } + } + + private void ConfigureWindow(WindowSettings settings) + { + Engine.MaxFps = settings.TargetFps; + + bool useDebugWindow = OS.IsDebugBuild() && settings.DebugWindowInDebugBuild; + _productionKioskMode = !OS.IsDebugBuild() && settings.Fullscreen; + if (useDebugWindow || !settings.Fullscreen) + { + Input.MouseMode = Input.MouseModeEnum.Visible; + DisplayServer.WindowSetMode(DisplayServer.WindowMode.Windowed); + DisplayServer.WindowSetFlag(DisplayServer.WindowFlags.Borderless, false); + + var windowSize = new Vector2I(settings.DebugWindowWidth, settings.DebugWindowHeight); + DisplayServer.WindowSetSize(windowSize); + Vector2I screenSize = DisplayServer.ScreenGetSize(); + DisplayServer.WindowSetPosition((screenSize - windowSize) / 2); + return; + } + + Input.MouseMode = Input.MouseModeEnum.Hidden; + DisplayServer.WindowSetFlag(DisplayServer.WindowFlags.Borderless, settings.Borderless); + DisplayServer.WindowSetMode(DisplayServer.WindowMode.Fullscreen); + _lastScreenCount = DisplayServer.GetScreenCount(); + _lastScreenSize = DisplayServer.ScreenGetSize(); + _nextKioskWindowCheckAt = Time.GetTicksMsec() + 2000UL; + } + + private void EnsureKioskWindowState() + { + if (!_productionKioskMode) + { + return; + } + + int screenCount = Math.Max(1, DisplayServer.GetScreenCount()); + int currentScreen = Math.Clamp(DisplayServer.WindowGetCurrentScreen(), 0, screenCount - 1); + if (DisplayServer.WindowGetCurrentScreen() != currentScreen) + { + DisplayServer.WindowSetCurrentScreen(currentScreen); + } + + Vector2I screenSize = DisplayServer.ScreenGetSize(currentScreen); + if (screenCount != _lastScreenCount || screenSize != _lastScreenSize) + { + AppLogger.Info( + "Display", + $"Конфигурация дисплея изменилась: screens={screenCount}, size={screenSize.X}x{screenSize.Y}."); + _lastScreenCount = screenCount; + _lastScreenSize = screenSize; + } + + Input.MouseMode = Input.MouseModeEnum.Hidden; + DisplayServer.WindowSetFlag(DisplayServer.WindowFlags.Borderless, _settings.Window.Borderless); + if (DisplayServer.WindowGetMode() != DisplayServer.WindowMode.Fullscreen) + { + DisplayServer.WindowSetMode(DisplayServer.WindowMode.Fullscreen); + AppLogger.Warning("Display", "Полноэкранный киоск-режим восстановлен автоматически."); + } + } + + private void ConfigureScreens() + { + _screenManager = GetNode("/root/ScreenManager"); + Control screenHost = GetNode("UiLayer/ScreenHost"); + ThemeManager themeManager = GetNode("/root/ThemeManager"); + _screenManager.Initialize( + screenHost, + ScreenRegistry.LoadDefault(), + themeManager.CurrentTheme?.ScreenScenes, + themeManager.CurrentTheme?.ScreenBindingContracts); + + _homeScreen = _screenManager.GetScreen(ScreenId.Home); + _cashPaymentScreen = _screenManager.GetScreen(ScreenId.CashPayment); + _cardAmountScreen = _screenManager.GetScreen(ScreenId.CardAmount); + _cardCustomAmountScreen = _screenManager.GetScreen(ScreenId.CardCustomAmount); + _cardTerminalScreen = _screenManager.GetScreen(ScreenId.CardTerminal); + _successScreen = _screenManager.GetScreen(ScreenId.Success); + _errorScreen = _screenManager.GetScreen(ScreenId.Error); + _serviceAccessScreen = _screenManager.GetScreen(ScreenId.ServiceAccess); + _settingsScreen = _screenManager.GetScreen(ScreenId.Settings); + + _homeScreen.Configure(_settings); + _interactivePetHost = GetNode("InteractivePetHost"); + _interactivePetHost.Configure(themeManager, _screenManager); + _interactivePetHost.SetEnabled(_settings.MenuVisibility.ShowInteractivePet); + _interactivePetHost.PetInteracted += OnInteractivePetInteracted; + int? tokenPurchaseLimit = GetTokenPurchaseLimit(); + _cashPaymentScreen.Configure(_settings.Pricing, tokenPurchaseLimit, _settings.AnimatedBannerTexts); + _cardAmountScreen.Configure(_settings.Pricing, tokenPurchaseLimit, _settings.AnimatedBannerTexts); + _cardCustomAmountScreen.Configure(_settings.Pricing, tokenPurchaseLimit, _settings.AnimatedBannerTexts); + _cardTerminalScreen.Configure(_settings.AnimatedBannerTexts); + ConfigureFooters(); + _cashPaymentScreen.SetDebugControlsVisible(_settings.Hardware.UseMock); + _cardTerminalScreen.SetDebugControlsVisible(_settings.Hardware.UseMock); + _settingsScreen.Configure( + _settingsService, + BuildRuntimeSummary, + () => AppLogger.GetRecentSafeEntries(5)); + _settingsScreen.SetConfiguredHoppers( + _configuredHoppers.Hopper1Enabled, + _configuredHoppers.Hopper2Enabled); + + _homeScreen.CashRequested += OnCashRequested; + _homeScreen.CardRequested += OnCardRequested; + _cashPaymentScreen.BackRequested += OnCancelRequested; + _cashPaymentScreen.HomeRequested += OnCancelRequested; + _cashPaymentScreen.MockCashRequested += OnMockCashRequested; + _cashPaymentScreen.DispenseRequested += OnCashDispenseRequested; + _cardAmountScreen.BackRequested += OnCancelRequested; + _cardAmountScreen.HomeRequested += OnCancelRequested; + _cardAmountScreen.AmountSelected += OnCardAmountSelected; + _cardAmountScreen.OtherAmountRequested += OnOtherCardAmountRequested; + _cardCustomAmountScreen.BackRequested += OnCustomAmountBackRequested; + _cardCustomAmountScreen.HomeRequested += OnCancelRequested; + _cardCustomAmountScreen.AmountConfirmed += OnCardAmountSelected; + _cardTerminalScreen.BackRequested += OnTerminalBackRequested; + _cardTerminalScreen.HomeRequested += OnCancelRequested; + _cardTerminalScreen.CancelRequested += OnCancelRequested; + _cardTerminalScreen.DebugApproveRequested += OnDebugCardApproved; + _cardTerminalScreen.DebugDeclineRequested += OnDebugCardDeclined; + _cardTerminalScreen.DebugDispenseFailureRequested += OnDebugDispenseFailure; + _cardTerminalScreen.DebugPartialDispenseRequested += OnDebugPartialDispense; + _cardTerminalScreen.DebugConnectionLossRequested += OnDebugConnectionLoss; + _successScreen.HomeRequested += OnReturnHomeRequested; + _errorScreen.HomeRequested += OnReturnHomeRequested; + _serviceAccessScreen.Authorized += OnServiceAuthorized; + _serviceAccessScreen.PinCreated += OnServicePinCreated; + _serviceAccessScreen.Cancelled += OnServiceAccessCancelled; + _settingsScreen.Saved += OnSettingsSaved; + _settingsScreen.SaveAndExitRequested += OnSettingsSaveAndExitRequested; + _settingsScreen.TestDispenseRequested += OnServiceTestDispenseRequested; + _settingsScreen.TokenRecountRequested += OnTokenRecountRequested; + _settingsScreen.ManualTokenAdditionConfirmed += OnManualTokenAdditionConfirmed; + } + + private void SubscribeSession() + { + _sessionController.StateChanged += OnSessionStateChanged; + _sessionController.CashBalanceChanged += OnCashBalanceChanged; + _sessionController.StockChanged += OnStockChanged; + _sessionController.CountdownChanged += OnCountdownChanged; + } + + private void SubscribeMachine() + { + _machineController.ConnectionStateChanged += OnConnectionStateChanged; + _machineController.DispenseFinished += OnMachineDispenseFinished; + if (_dualHopperController is not null) + { + _dualHopperController.HopperStockChanged += OnHopperStockChanged; + _dualHopperController.HopperDispenseAccounted += OnHopperDispenseAccounted; + _dualHopperController.DispenseProgressChanged += OnDispenseProgressChanged; + } + + if (_dualHopperRecountController is not null) + { + _dualHopperRecountController.HopperTokenRecountProgressChanged += OnHopperTokenRecountProgressChanged; + _dualHopperRecountController.HopperTokenRecountFinished += OnHopperTokenRecountFinished; + } + else if (_tokenRecountController is not null) + { + _tokenRecountController.TokenRecountProgressChanged += OnTokenRecountProgressChanged; + _tokenRecountController.TokenRecountFinished += OnTokenRecountFinished; + } + + if (_peripheryController is not null) + { + _peripheryController.ServiceRequested += OnPhysicalServiceRequested; + } + } + + private void OnSessionStateChanged(SessionState state) + { + switch (state) + { + case SessionState.Home: + RefreshHomeAvailability(); + _screenManager.Show(ScreenId.Home, animate: _screenManager.CurrentScreenId is not null); + break; + case SessionState.CashAccepting: + _cashPaymentScreen.SetBalance(_sessionController.CashBalanceRubles); + _screenManager.Show(ScreenId.CashPayment); + break; + case SessionState.CardAmountSelection: + _screenManager.Show(ScreenId.CardAmount); + break; + case SessionState.CardCustomAmount: + _cardCustomAmountScreen.ResetInput(); + _screenManager.Show(ScreenId.CardCustomAmount); + break; + case SessionState.CardTerminalWait: + _cardTerminalScreen.ShowPayment( + _sessionController.SelectedAmountRubles, + _sessionController.BaseTokens, + _sessionController.BonusTokens); + _screenManager.Show(ScreenId.CardTerminal); + break; + case SessionState.Dispensing: + _successScreen.ShowDispensing(_sessionController.TotalTokens); + _screenManager.Show(ScreenId.Success); + _interactivePetHost.RequestDispenseCelebration(4); + break; + case SessionState.Completed: + _successScreen.ShowCompleted(_sessionController.BaseTokens, _sessionController.BonusTokens); + _screenManager.Show(ScreenId.Success); + break; + case SessionState.PaymentDeclined: + case SessionState.Error: + _errorScreen.ShowError(_sessionController.ErrorTitle, _sessionController.ErrorMessage); + _screenManager.Show(ScreenId.Error); + break; + case SessionState.Cancelled: + break; + default: + AppLogger.Error("Application", $"Неизвестное состояние сессии: {state}. Выполняется безопасный возврат домой."); + _sessionController.ReturnHome(); + break; + } + } + + private void OnCashRequested() => _sessionController.BeginCash(); + + private void OnCardRequested() => _sessionController.BeginCard(); + + private void OnCancelRequested() => _sessionController.Cancel(); + + private void OnReturnHomeRequested() => _sessionController.ReturnHome(); + + private void OnInteractivePetInteracted() => _sessionController.NotifyUserActivity(); + + private void OnSettingsSaved( + AppSettings savedSettings, + SettingsChangeSummary changeSummary, + ServiceAccessLevel accessLevel) + { + _settings = savedSettings; + _serviceAccessPolicy = new ServiceAccessPolicy(_settings.Security); + AppLogger.Initialize(_settings.Logging); + OperationJournal.Initialize(_settings.Logging); + ConfigurationAuditJournal.Initialize(_settings.Logging); + ConfigurationAuditJournal.Record(changeSummary, accessLevel); + GetNode("/root/ThemeManager").SetReducedEffects(_settings.Themes.ReducedEffects); + _interactivePetHost.SetEnabled(_settings.MenuVisibility.ShowInteractivePet); + _homeScreen.Configure(_settings); + _dualHopperController?.SetInventoryAccountingEnabled(_settings.TokenInventory.Enabled); + _dualHopperController?.SetPurchaseLimitEnabled(_settings.TokenInventory.PurchaseLimitEnabled); + int? tokenPurchaseLimit = GetTokenPurchaseLimit(); + _cashPaymentScreen.Configure(_settings.Pricing, tokenPurchaseLimit, _settings.AnimatedBannerTexts); + _cardAmountScreen.Configure(_settings.Pricing, tokenPurchaseLimit, _settings.AnimatedBannerTexts); + _cardCustomAmountScreen.Configure(_settings.Pricing, tokenPurchaseLimit, _settings.AnimatedBannerTexts); + _cardTerminalScreen.Configure(_settings.AnimatedBannerTexts); + ConfigureFooters(); + _sessionController.Configure(_settings, _machineController, tokenPurchaseLimit); + RefreshInventoryState(); + _homeScreen.SetConnectionState(_machineController.ConnectionState); + RefreshServiceTestAvailability(); + } + + private void OnSettingsSaveAndExitRequested() + { + _screenManager.Show(ScreenId.Home); + AppLogger.Info("Service", "Настройки сохранены и закрыты экранной кнопкой."); + } + + private void ConfigureFooters() + { + Control[] screens = + { + _cashPaymentScreen, + _cardAmountScreen, + _cardCustomAmountScreen, + _cardTerminalScreen, + _successScreen, + _errorScreen, + _serviceAccessScreen, + }; + + foreach (Control screen in screens) + { + if (screen.FindChild("Footer", recursive: true, owned: false) is not Control footer) + { + continue; + } + + if (footer is KioskFooterControl builtInFooter) + { + builtInFooter.Configure(_settings.Branding); + continue; + } + + // Внешняя тема владеет готовой сценой footer. Меняем только уже существующую + // текстовую точку компонента, не добавляя и не перестраивая её визуальные узлы. + if (footer.FindChild("Support", recursive: true, owned: false) is Label supportLabel) + { + supportLabel.Text = $"ТЕХПОДДЕРЖКА:\n{_settings.Branding.SupportPhone}"; + } + } + } + + private void OnPhysicalServiceRequested() + { + if (_screenManager.TransitionInProgress) + { + AppLogger.Warning("Service", "Запрос SERVICE отклонён: выполняется переход между экранами."); + return; + } + + if (_screenManager.CurrentScreenId == ScreenId.Settings) + { + if (_settingsScreen.TryFinishEditing()) + { + _screenManager.Show(ScreenId.Home); + AppLogger.Info("Service", "Настройки закрыты повторным нажатием сервисной кнопки."); + } + else + { + AppLogger.Warning("Service", "Выход из настроек отложен: автосохранение не завершено."); + } + + return; + } + + if (_sessionController.State != SessionState.Home + || _screenManager.CurrentScreenId != ScreenId.Home) + { + AppLogger.Warning("Service", "Запрос SERVICE отклонён: приложение занято пользовательской операцией."); + return; + } + + if (!_settings.Security.ServicePinEnabled) + { + OpenSettingsWithoutPin(); + AppLogger.Info("Service", "Настройки открыты напрямую: защита сервисным PIN выключена."); + return; + } + + _serviceAccessScreen.Begin(_serviceAccessPolicy); + _screenManager.Show(ScreenId.ServiceAccess); + AppLogger.Info("Service", "Открыт защищённый сервисный вход по физическому запросу."); + } + + private void OpenSettingsWithoutPin() + { + ServiceAccessLevel accessLevel = OS.IsDebugBuild() + ? ServiceAccessLevel.Debug + : ServiceAccessLevel.Engineer; + _settingsScreen.BeginEdit(accessLevel); + _screenManager.Show(ScreenId.Settings); + RefreshServiceTestAvailability(); + RefreshTokenInventoryControls(); + } + + private void OnServicePinCreated(string pin) + { + try + { + AppSettings previous = _settingsService.Current; + AppSettings candidate = _settingsService.CreateWorkingCopy(); + ServiceAccessPolicy.SetPin(candidate.Security, pin); + AppSettings saved = _settingsService.Save(candidate); + SettingsChangeSummary summary = SettingsChangeDetector.Compare(previous, saved); + OnSettingsSaved(saved, summary, ServiceAccessLevel.Engineer); + AppLogger.Info("Service", "Новый сервисный PIN настроен внутри приложения."); + OnServiceAuthorized(ServiceAccessLevel.Engineer); + } + catch (Exception exception) + { + AppLogger.Error("Service", $"Не удалось сохранить сервисный PIN: {exception.GetType().Name}."); + _serviceAccessScreen.ShowPersistenceError(); + } + } + + private void OnServiceAuthorized(ServiceAccessLevel accessLevel) + { + if (accessLevel is not (ServiceAccessLevel.Operator or ServiceAccessLevel.Engineer)) + { + return; + } + + _settingsScreen.BeginEdit(accessLevel); + _screenManager.Show(ScreenId.Settings); + RefreshServiceTestAvailability(); + RefreshTokenInventoryControls(); + AppLogger.Info("Service", $"Сервисный доступ подтверждён: role={accessLevel}."); + } + + private void OnServiceAccessCancelled() => _screenManager.Show(ScreenId.Home); + + private void OnServiceTestDispenseRequested() + { + if (_serviceDispenseInProgress || !CanRunServiceDispense()) + { + _settingsScreen.SetServiceTestAvailability(false, "Тест отклонён: контроллер не готов или приложение занято."); + return; + } + + _serviceDispenseInProgress = true; + _settingsScreen.SetServiceTestAvailability(false, "Команда отправлена; ожидается подтверждение выдачи."); + AppLogger.Warning("Service", "Запущена подтверждённая сервисная выдача одного жетона."); + _machineController.DispenseTokens(1); + } + + private void OnMachineDispenseFinished(bool success, int dispensedTokens, string? error) + { + if (_settings.TokenInventory.Enabled + && _dualHopperController is null + && dispensedTokens > 0) + { + try + { + _tokenInventory = _tokenInventoryStore.RemoveDispensed(dispensedTokens); + RefreshInventoryState(); + } + catch (Exception exception) + { + AppLogger.Error("TokenInventory", $"Не удалось списать выданные жетоны: {exception.GetType().Name}."); + } + } + + if (!_serviceDispenseInProgress) + { + return; + } + + _serviceDispenseInProgress = false; + _settingsScreen.SetServiceTestResult(success, dispensedTokens, CanRunServiceDispense()); + AppLogger.Info( + "Service", + $"Сервисная выдача завершена: success={success}, confirmed={dispensedTokens}."); + } + + private void OnHopperDispenseAccounted(int hopper1Count, int hopper2Count) + { + if (!_settings.TokenInventory.Enabled) + { + return; + } + + try + { + _tokenInventory = _tokenInventoryStore.SetCounts( + Math.Max(0, _tokenInventory.Hopper1Count - hopper1Count), + Math.Max(0, _tokenInventory.Hopper2Count - hopper2Count)); + RefreshInventoryState(); + AppLogger.Info( + "TokenInventory", + $"Списана подтверждённая выдача: hopper1={hopper1Count}, hopper2={hopper2Count}, total={_tokenInventory.Count}."); + } + catch (Exception exception) + { + AppLogger.Error("TokenInventory", $"Не удалось списать выдачу по хопперам: {exception.GetType().Name}."); + } + } + + private void OnDispenseProgressChanged(int confirmedTokens, int requestedTokens) + { + if (_sessionController.State == SessionState.Dispensing) + { + _successScreen.ShowDispenseProgress(confirmedTokens, requestedTokens); + } + } + + private void OnTokenRecountRequested(int hopperNumber) + { + if (!_settings.TokenInventory.Enabled) + { + RefreshTokenInventoryControls(); + return; + } + + HopperChannel hopper = ToHopperChannel(hopperNumber); + bool started = _dualHopperRecountController is not null + ? CanRunTokenRecount(hopper) + && _dualHopperRecountController.TryStartTokenRecount(hopper, Time.GetTicksMsec()) + : hopper == HopperChannel.Hopper1 + && CanRunTokenRecount(hopper) + && _tokenRecountController!.TryStartTokenRecount(Time.GetTicksMsec()); + if (!started) + { + RefreshTokenInventoryControls(); + _settingsScreen.SetTokenRecountFailure("Пересчёт сейчас недоступен. Проверьте подключение контроллера."); + return; + } + + _settingsScreen.SetTokenRecountProgress((int)hopper, 0); + AppLogger.Warning("TokenInventory", $"Запущен автоматический пересчёт хоппера {(int)hopper}."); + } + + private void OnTokenRecountProgressChanged(int count) => + OnHopperTokenRecountProgressChanged(HopperChannel.Hopper1, count); + + private void OnHopperTokenRecountProgressChanged(HopperChannel hopper, int count) + { + if (GodotObject.IsInstanceValid(_settingsScreen)) + { + _settingsScreen.SetTokenRecountProgress((int)hopper, count); + } + } + + private void OnTokenRecountFinished(bool success, int countedTokens, string? errorCode) => + OnHopperTokenRecountFinished(HopperChannel.Hopper1, success, countedTokens, errorCode); + + private void OnHopperTokenRecountFinished( + HopperChannel hopper, + bool success, + int countedTokens, + string? errorCode) + { + if (!GodotObject.IsInstanceValid(_settingsScreen)) + { + return; + } + + if (!success) + { + AppLogger.Warning( + "TokenInventory", + $"Пересчёт хоппера {(int)hopper} прерван: code={errorCode ?? "UNKNOWN"}, counted={countedTokens}."); + RefreshTokenInventoryControls(); + _settingsScreen.SetTokenRecountFailure("Пересчёт остановлен. Старый учтённый остаток не изменён."); + return; + } + + try + { + _tokenInventory = _tokenInventoryStore.SetHopperCount(ToTokenHopper(hopper), countedTokens); + RefreshInventoryState(); + _settingsScreen.SetTokenRecountCompleted((int)hopper, countedTokens); + AppLogger.Info( + "TokenInventory", + $"Хоппер {(int)hopper} пересчитан автоматически: {countedTokens}; общий остаток {_tokenInventory.Count}."); + } + catch (Exception exception) + { + AppLogger.Error("TokenInventory", $"Не удалось записать остаток после пересчёта: {exception.GetType().Name}."); + _settingsScreen.SetTokenRecountFailure("Пересчёт завершён, но не удалось записать результат. Повторите операцию."); + } + } + + private void OnManualTokenAdditionConfirmed(int hopperNumber, int count) + { + HopperChannel channel = ToHopperChannel(hopperNumber); + if (!_settings.TokenInventory.Enabled || !IsHopperConfigured(channel)) + { + AppLogger.Warning("TokenInventory", $"Пополнение отключённого хоппера {hopperNumber} проигнорировано."); + RefreshTokenInventoryControls(); + return; + } + + TokenHopper hopper = hopperNumber == 2 ? TokenHopper.Hopper2 : TokenHopper.Hopper1; + try + { + _tokenInventory = _tokenInventoryStore.Add(hopper, count); + RefreshInventoryState(); + AppLogger.Info( + "TokenInventory", + $"В хоппер {hopperNumber} вручную добавлено {count}; общий остаток {_tokenInventory.Count}."); + } + catch (Exception exception) + { + AppLogger.Error("TokenInventory", $"Не удалось добавить жетоны вручную: {exception.GetType().Name}."); + _settingsScreen.SetTokenRecountFailure("Не удалось записать новый остаток. Проверьте количество и повторите."); + } + } + + private bool CanRunTokenRecount(HopperChannel hopper) + { + if (!_settings.TokenInventory.Enabled || !IsHopperConfigured(hopper)) + { + return false; + } + + bool controllerReady = _dualHopperRecountController is not null + ? _dualHopperRecountController.CanStartHopperTokenRecount(hopper) + : hopper == HopperChannel.Hopper1 + && _tokenRecountController?.CanStartTokenRecount == true; + return controllerReady + && _sessionController.State == SessionState.Home + && _screenManager.CurrentScreenId == ScreenId.Settings; + } + + private void RefreshTokenInventoryControls(bool preserveStatus = false) + { + if (!GodotObject.IsInstanceValid(_settingsScreen)) + { + return; + } + + _settingsScreen.SetTokenInventoryCounts( + _tokenInventory.Hopper1Count, + _tokenInventory.Hopper2Count); + if (!_settings.TokenInventory.Enabled) + { + _settingsScreen.SetTokenRecountAvailability( + false, + false, + preserveStatus ? string.Empty : "Учёт жетонов отключён."); + return; + } + + bool hopper1Available = CanRunTokenRecount(HopperChannel.Hopper1); + bool hopper2Available = CanRunTokenRecount(HopperChannel.Hopper2); + bool singleConfiguredHopper = _configuredHoppers.Hopper1Enabled + != _configuredHoppers.Hopper2Enabled; + string status = preserveStatus + ? string.Empty + : !_configuredHoppers.Hopper1Enabled && !_configuredHoppers.Hopper2Enabled + ? "Хопперы отключены в технической конфигурации." + : hopper1Available || hopper2Available + ? singleConfiguredHopper + ? "Подключённый хоппер можно пересчитать или пополнить." + : "Выберите хоппер: его можно пересчитать или пополнить отдельно." + : "Пересчёт станет доступен после подключения контроллера. Жетоны можно добавить вручную."; + _settingsScreen.SetTokenRecountAvailability(hopper1Available, hopper2Available, status); + } + + private void RefreshInventoryState() + { + _dualHopperController?.SetInventoryAccountingEnabled(_settings.TokenInventory.Enabled); + _dualHopperController?.SetPurchaseLimitEnabled(_settings.TokenInventory.PurchaseLimitEnabled); + (int hopper1Inventory, int hopper2Inventory) = GetConfiguredInventoryCounts(); + _dualHopperController?.SetHopperInventory( + hopper1Inventory, + hopper2Inventory); + if (GodotObject.IsInstanceValid(_settingsScreen)) + { + _settingsScreen.SetTokenInventoryCounts( + _tokenInventory.Hopper1Count, + _tokenInventory.Hopper2Count); + } + + RefreshTokenPurchaseLimits(); + RefreshHomeAvailability(); + } + + private void RefreshHomeAvailability() + { + MachineStockLevel hopper1 = _dualHopperController?.Hopper1StockLevel ?? _machineController.StockLevel; + MachineStockLevel hopper2 = _dualHopperController?.Hopper2StockLevel ?? _machineController.StockLevel; + (int hopper1Inventory, int hopper2Inventory) = GetConfiguredInventoryCounts(); + int configuredInventory = hopper1Inventory + hopper2Inventory; + if (_configuredHoppers.Hopper1Enabled && !_configuredHoppers.Hopper2Enabled) + { + hopper2 = hopper1; + } + else if (!_configuredHoppers.Hopper1Enabled && _configuredHoppers.Hopper2Enabled) + { + hopper1 = hopper2; + } + + TokenAvailabilityLevel level = IsPurchaseLimitActive() + ? TokenInventoryPolicy.ResolveAvailability(configuredInventory, hopper1, hopper2) + : TokenInventoryPolicy.ResolveWithoutInventory( + hopper1, + hopper2, + _configuredHoppers.Hopper1Enabled, + _configuredHoppers.Hopper2Enabled); + _homeScreen.SetTokenAvailability(level, configuredInventory); + } + + private int? GetTokenPurchaseLimit() + { + if (!IsPurchaseLimitActive()) + { + return null; + } + + (int Hopper1, int Hopper2) inventory = GetConfiguredInventoryCounts(); + return inventory.Hopper1 + inventory.Hopper2; + } + + private bool IsPurchaseLimitActive() => + _settings.TokenInventory.Enabled && _settings.TokenInventory.PurchaseLimitEnabled; + + private void RefreshTokenPurchaseLimits() + { + if (!GodotObject.IsInstanceValid(_cashPaymentScreen)) + { + return; + } + + int? limit = GetTokenPurchaseLimit(); + _sessionController.SetMaximumAvailableTokens(limit); + _cashPaymentScreen.SetTokenPurchaseLimit(limit); + _cardAmountScreen.SetTokenPurchaseLimit(limit); + _cardCustomAmountScreen.SetTokenPurchaseLimit(limit); + } + + private (int Hopper1, int Hopper2) GetConfiguredInventoryCounts() => + ( + _configuredHoppers.Hopper1Enabled ? _tokenInventory.Hopper1Count : 0, + _configuredHoppers.Hopper2Enabled ? _tokenInventory.Hopper2Count : 0 + ); + + private bool IsHopperConfigured(HopperChannel hopper) => + hopper == HopperChannel.Hopper1 + ? _configuredHoppers.Hopper1Enabled + : _configuredHoppers.Hopper2Enabled; + + private static HopperChannel ToHopperChannel(int hopperNumber) => + hopperNumber == 2 ? HopperChannel.Hopper2 : HopperChannel.Hopper1; + + private static TokenHopper ToTokenHopper(HopperChannel hopper) => + hopper == HopperChannel.Hopper2 ? TokenHopper.Hopper2 : TokenHopper.Hopper1; + + private bool CanRunServiceDispense() + { + bool supportedProfile = _settings.Hardware.UseMock + || _settings.Hardware.DispenseMode.Equals("Hopper1Auto", StringComparison.OrdinalIgnoreCase) + || _settings.Hardware.DispenseMode.Equals("Hopper2Auto", StringComparison.OrdinalIgnoreCase) + || _settings.Hardware.DispenseMode.Equals("DualHopperAuto", StringComparison.OrdinalIgnoreCase); + return !_serviceDispenseInProgress + && supportedProfile + && (!IsPurchaseLimitActive() + || GetConfiguredInventoryCounts() is var configuredInventory + && configuredInventory.Hopper1 + configuredInventory.Hopper2 > 0) + && _sessionController.State == SessionState.Home + && _machineController.ConnectionState == MachineConnectionState.Ready + && _machineController.StockLevel is MachineStockLevel.Enough or MachineStockLevel.Low + && _screenManager.CurrentScreenId == ScreenId.Settings; + } + + private void RefreshServiceTestAvailability() + { + if (!GodotObject.IsInstanceValid(_settingsScreen)) + { + return; + } + + bool available = CanRunServiceDispense(); + string status = available + ? "Контроллер готов. Для запуска потребуется двойное подтверждение." + : "Тест недоступен: требуется Home, готовое соединение и настроенная команда выдачи."; + _settingsScreen.SetServiceTestAvailability(available, status); + } + + private string BuildRuntimeSummary() + { + string version = ProjectSettings.GetSetting("application/config/version", "не указана").AsString(); + ThemeManager themeManager = GetNode("/root/ThemeManager"); + string theme = themeManager.CurrentTheme?.DisplayName ?? "встроенная fallback"; + string port = _settings.Hardware.UseMock ? "имитация оборудования" : _settings.Hardware.PortName; + string summary = $"Версия: {version}\nТема: {theme}\nПорт: {port}\nСоединение: {_machineController.ConnectionState}\nЗапас: {_machineController.StockLevel}"; + if (!OS.IsDebugBuild()) + { + return summary; + } + + string transport = _hardwarePort?.IsConnected == true ? "Connected" : "Disconnected"; + string authentication = _peripheryController?.AuthenticationState.ToString() + ?? (_settings.Hardware.UseMock ? "Mock" : "NotCreated"); + return $"{summary}\nПлатформа: {OS.GetName()}\nТранспорт: {transport}\nАвторизация: {authentication}\n" + + $"UART: {_settings.Hardware.BaudRate} 8N1, reconnect {_settings.Hardware.ReconnectIntervalSeconds} с"; + } + + private void OnCustomAmountBackRequested() => _sessionController.ReturnToCardAmounts(); + + private void OnTerminalBackRequested() => _sessionController.ReturnToCardAmounts(); + + private void OnCardAmountSelected(int amountRubles) => _sessionController.SelectCardAmount(amountRubles); + + private void OnOtherCardAmountRequested() => _sessionController.OpenCustomCardAmount(); + + private void OnCashDispenseRequested() => _sessionController.ConfirmCashDispense(); + + private void OnMockCashRequested(int amountRubles) + { + _sessionController.NotifyUserActivity(); + _mockMachine?.AddCash(amountRubles); + } + + private void OnDebugCardApproved() => _mockMachine?.SimulateCardResult(MachineCardResult.Approved); + + private void OnDebugCardDeclined() => _mockMachine?.SimulateCardResult(MachineCardResult.Declined); + + private void OnDebugDispenseFailure() + { + _mockMachine?.SimulateNextDispenseFailure(); + _mockMachine?.SimulateCardResult(MachineCardResult.Approved); + } + + private void OnDebugPartialDispense() + { + int partialCount = Math.Max(1, _sessionController.TotalTokens / 2); + _mockMachine?.SimulateNextPartialDispense(partialCount); + _mockMachine?.SimulateCardResult(MachineCardResult.Approved); + } + + private void OnDebugConnectionLoss() => _mockMachine?.SimulateConnectionLoss(); + + private void OnCashBalanceChanged(int balanceRubles) => _cashPaymentScreen.SetBalance(balanceRubles); + + private void OnStockChanged(MachineStockLevel stockLevel) + { + RefreshHomeAvailability(); + RefreshServiceTestAvailability(); + } + + private void OnHopperStockChanged(HopperChannel hopper, MachineStockLevel stockLevel) + { + RefreshHomeAvailability(); + RefreshServiceTestAvailability(); + } + + private void OnConnectionStateChanged(MachineConnectionState state) + { + if (state == MachineConnectionState.Ready + && IsAutomaticPortSearch() + && !string.IsNullOrWhiteSpace(_activeHardwarePortName)) + { + _automaticPortAttemptInProgress = false; + AppLogger.Info("Application", $"Контроллер авторизован через автоматически найденный порт {_activeHardwarePortName}."); + } + + _homeScreen.SetConnectionState(state); + RefreshHomeAvailability(); + RefreshServiceTestAvailability(); + RefreshTokenInventoryControls(); + } + + private void OnCountdownChanged(int seconds) + { + _cardTerminalScreen.SetCountdown(seconds); + _successScreen.SetCountdown(seconds); + _errorScreen.SetCountdown(seconds); + } + + private void Shutdown() + { + if (_shutdownCompleted) + { + return; + } + + _shutdownCompleted = true; + UnsubscribeScreens(); + UnsubscribeSession(); + UnsubscribeMachine(); + if (GodotObject.IsInstanceValid(_sessionController)) + { + _sessionController.Shutdown(); + } + + if (_hardwarePort is not null) + { + _peripheryController?.Dispose(); + _peripheryController = null; + _hardwarePort.Disconnect(); + if (_hardwarePort is IDisposable disposablePort) + { + disposablePort.Dispose(); + } + + _hardwarePort = null; + } + + _controllerCipher?.Dispose(); + _controllerCipher = null; + + OperationJournal.Shutdown(); + ConfigurationAuditJournal.Shutdown(); + AppLogger.Shutdown(); + } + + private void UnsubscribeScreens() + { + if (!GodotObject.IsInstanceValid(_homeScreen)) + { + return; + } + + _homeScreen.CashRequested -= OnCashRequested; + _homeScreen.CardRequested -= OnCardRequested; + _cashPaymentScreen.BackRequested -= OnCancelRequested; + _cashPaymentScreen.HomeRequested -= OnCancelRequested; + _cashPaymentScreen.MockCashRequested -= OnMockCashRequested; + _cashPaymentScreen.DispenseRequested -= OnCashDispenseRequested; + _cardAmountScreen.BackRequested -= OnCancelRequested; + _cardAmountScreen.HomeRequested -= OnCancelRequested; + _cardAmountScreen.AmountSelected -= OnCardAmountSelected; + _cardAmountScreen.OtherAmountRequested -= OnOtherCardAmountRequested; + _cardCustomAmountScreen.BackRequested -= OnCustomAmountBackRequested; + _cardCustomAmountScreen.HomeRequested -= OnCancelRequested; + _cardCustomAmountScreen.AmountConfirmed -= OnCardAmountSelected; + _cardTerminalScreen.BackRequested -= OnTerminalBackRequested; + _cardTerminalScreen.HomeRequested -= OnCancelRequested; + _cardTerminalScreen.CancelRequested -= OnCancelRequested; + _cardTerminalScreen.DebugApproveRequested -= OnDebugCardApproved; + _cardTerminalScreen.DebugDeclineRequested -= OnDebugCardDeclined; + _cardTerminalScreen.DebugDispenseFailureRequested -= OnDebugDispenseFailure; + _cardTerminalScreen.DebugPartialDispenseRequested -= OnDebugPartialDispense; + _cardTerminalScreen.DebugConnectionLossRequested -= OnDebugConnectionLoss; + _successScreen.HomeRequested -= OnReturnHomeRequested; + _errorScreen.HomeRequested -= OnReturnHomeRequested; + _serviceAccessScreen.Authorized -= OnServiceAuthorized; + _serviceAccessScreen.PinCreated -= OnServicePinCreated; + _serviceAccessScreen.Cancelled -= OnServiceAccessCancelled; + _settingsScreen.Saved -= OnSettingsSaved; + _settingsScreen.SaveAndExitRequested -= OnSettingsSaveAndExitRequested; + _settingsScreen.TestDispenseRequested -= OnServiceTestDispenseRequested; + _settingsScreen.TokenRecountRequested -= OnTokenRecountRequested; + _settingsScreen.ManualTokenAdditionConfirmed -= OnManualTokenAdditionConfirmed; + if (GodotObject.IsInstanceValid(_interactivePetHost)) + { + _interactivePetHost.PetInteracted -= OnInteractivePetInteracted; + } + } + + private void UnsubscribeSession() + { + if (!GodotObject.IsInstanceValid(_sessionController)) + { + return; + } + + _sessionController.StateChanged -= OnSessionStateChanged; + _sessionController.CashBalanceChanged -= OnCashBalanceChanged; + _sessionController.StockChanged -= OnStockChanged; + _sessionController.CountdownChanged -= OnCountdownChanged; + } + + private void UnsubscribeMachine() + { + if (_hardwarePort is not null) + { + _hardwarePort.ConnectionChanged -= OnHardwareTransportConnectionChanged; + } + + if (_machineController is not null) + { + _machineController.ConnectionStateChanged -= OnConnectionStateChanged; + _machineController.DispenseFinished -= OnMachineDispenseFinished; + } + + if (_dualHopperController is not null) + { + _dualHopperController.HopperStockChanged -= OnHopperStockChanged; + _dualHopperController.HopperDispenseAccounted -= OnHopperDispenseAccounted; + _dualHopperController.DispenseProgressChanged -= OnDispenseProgressChanged; + } + + if (_dualHopperRecountController is not null) + { + _dualHopperRecountController.HopperTokenRecountProgressChanged -= OnHopperTokenRecountProgressChanged; + _dualHopperRecountController.HopperTokenRecountFinished -= OnHopperTokenRecountFinished; + } + else if (_tokenRecountController is not null) + { + _tokenRecountController.TokenRecountProgressChanged -= OnTokenRecountProgressChanged; + _tokenRecountController.TokenRecountFinished -= OnTokenRecountFinished; + } + + if (_peripheryController is not null) + { + _peripheryController.ServiceRequested -= OnPhysicalServiceRequested; + } + } + + private void ConfigureHardware() + { + if (_settings.Hardware.UseMock) + { + _hardwarePort = new MockHardwarePort(); + _mockMachine = new MockMachineController { Name = "MockMachineController" }; + AddChild(_mockMachine); + MachineStockLevel initialStockLevel = Enum.TryParse( + _settings.Hardware.MockStockLevel, + ignoreCase: true, + out MachineStockLevel parsedStockLevel) + ? parsedStockLevel + : MachineStockLevel.Enough; + _mockMachine.Configure(initialStockLevel); + _machineController = _mockMachine; + return; + } + + _hardwarePort = new SerialPortHardware( + _settings.Hardware.MaximumFrameLength, + _settings.Hardware.FrameTimeoutMilliseconds); + _hardwarePort.ConnectionChanged += OnHardwareTransportConnectionChanged; + AppLogger.Debug( + "Application", + $"Создаётся реальный serial-транспорт: frameTimeoutMs={_settings.Hardware.FrameTimeoutMilliseconds}, " + + $"maxFrameLength={_settings.Hardware.MaximumFrameLength}."); + IControllerBlockCipher? cipher = CreateControllerCipher(_settings.Hardware); + _controllerCipher = cipher as IDisposable; + var authenticator = new ControllerAuthenticator(cipher); + PeripheryDispenseMode dispenseMode = Enum.TryParse( + _settings.Hardware.DispenseMode, + ignoreCase: true, + out PeripheryDispenseMode parsedMode) + ? parsedMode + : PeripheryDispenseMode.Unsupported; + _peripheryController = new PeripheryMachineController( + _hardwarePort, + authenticator, + dispenseMode, + _settings.Hardware.CashlessKeepAliveSeconds, + _settings.Hardware.StockSensorInputIndex, + _settings.Hardware.StockLowWhenInputHigh, + _settings.Hardware.StockPollSeconds, + _settings.Hardware.HandshakeTimeoutMilliseconds, + _settings.Hardware.ServiceButtonInputIndex, + _settings.Hardware.ServiceButtonActiveHigh, + _settings.Hardware.Hopper1DispenseSensorInputIndex, + _settings.Hardware.Hopper1DispenseSensorActiveHigh, + _settings.Hardware.Hopper2DispenseSensorInputIndex, + _settings.Hardware.Hopper2DispenseSensorActiveHigh, + _settings.Hardware.InputPollMilliseconds, + _settings.Hardware.Hopper2StockSensorInputIndex, + _settings.Hardware.Hopper2StockLowWhenInputHigh); + _machineController = _peripheryController; + } + + private void ConnectConfiguredHardwarePort(bool refreshAutomaticCandidates, string attemptKind) + { + if (_hardwarePort is null) return; + if (_settings.Hardware.UseMock || !IsAutomaticPortSearch()) + { + _activeHardwarePortName = SerialPortCandidateResolver.NormalizePortName( + _settings.Hardware.PortName, + SerialPortNameValidator.CurrentPlatform); + AppLogger.Debug("Application", $"Запущено {attemptKind}: port={_activeHardwarePortName}, nextAttemptInSeconds={_settings.Hardware.ReconnectIntervalSeconds}."); + _hardwarePort.Connect(_activeHardwarePortName, _settings.Hardware.BaudRate); + return; + } + if (refreshAutomaticCandidates) + { + _automaticPortCandidates = DiscoverAutomaticPortCandidates(); + _nextAutomaticPortCandidateIndex = 0; + AppLogger.Debug("Application", $"Запущен {attemptKind} автоматического поиска: prefix={_settings.Hardware.PortName}, candidates={_automaticPortCandidates.Count}, nextAttemptInSeconds={_settings.Hardware.ReconnectIntervalSeconds}."); + } + TryConnectNextAutomaticPortCandidate(); + } + + private void OnHardwareTransportConnectionChanged(bool connected) + { + if (_shutdownCompleted || _settings.Hardware.UseMock || !IsAutomaticPortSearch()) return; + if (connected) return; + bool authenticationFailed = _peripheryController?.ConnectionState == MachineConnectionState.Faulted; + if (!_automaticPortAttemptInProgress && !authenticationFailed) return; + _automaticPortAttemptInProgress = false; + AppLogger.Debug("Application", authenticationFailed ? "Порт не прошёл авторизацию; продолжается автоматический поиск контроллера." : "Порт не удалось открыть; продолжается автоматический поиск контроллера."); + TryConnectNextAutomaticPortCandidate(); + } + + private IReadOnlyList DiscoverAutomaticPortCandidates() + { + try + { + return SerialPortCandidateResolver.ResolveCandidates(_settings.Hardware.PortName, SerialPortNameValidator.CurrentPlatform, System.IO.Ports.SerialPort.GetPortNames()); + } + catch (Exception exception) when (exception is System.IO.IOException or UnauthorizedAccessException) + { + AppLogger.Warning("Application", $"Не удалось получить список последовательных портов для автоматического поиска: {exception.GetType().Name}."); + return Array.Empty(); + } + } + + private void TryConnectNextAutomaticPortCandidate() + { + if (_hardwarePort is null) return; + if (_nextAutomaticPortCandidateIndex >= _automaticPortCandidates.Count) + { + AppLogger.Debug("Application", "Автоматический поиск не нашёл подходящих последовательных портов в этом цикле."); + return; + } + _activeHardwarePortName = _automaticPortCandidates[_nextAutomaticPortCandidateIndex++]; + _automaticPortAttemptInProgress = true; + AppLogger.Debug("Application", $"Автоматический поиск пробует {_activeHardwarePortName}: candidate={_nextAutomaticPortCandidateIndex}/{_automaticPortCandidates.Count}."); + _hardwarePort.Connect(_activeHardwarePortName, _settings.Hardware.BaudRate); + } + + private bool IsAutomaticPortSearch() => + SerialPortCandidateResolver.IsAutomaticSearchPrefix(_settings.Hardware.PortName, SerialPortNameValidator.CurrentPlatform); + + private static IControllerBlockCipher? CreateControllerCipher(HardwareSettings settings) + { + if (!settings.ControllerAesMode.Equals("ECB", StringComparison.OrdinalIgnoreCase)) + { + AppLogger.Warning("Application", "Настроен неподдерживаемый AES-режим; handshake останется заблокированным."); + return null; + } + + try + { + string? keyHex = System.Environment.GetEnvironmentVariable(settings.ControllerAesKeyEnvironmentVariable); + byte[] key = string.IsNullOrWhiteSpace(keyHex) + ? PeripheryControllerSecurity.Key.ToArray() + : Convert.FromHexString(keyHex.Trim()); + return new Aes256EcbBlockCipher(key); + } + catch (FormatException) + { + AppLogger.Error("Application", "Ключ контроллера имеет неверный HEX-формат."); + return null; + } + catch (ArgumentException) + { + AppLogger.Error("Application", "Ключ контроллера должен содержать 32 байта."); + return null; + } + } +} diff --git a/src/scenes/App/App.cs.uid b/src/scenes/App/App.cs.uid new file mode 100644 index 0000000..2a7fe29 --- /dev/null +++ b/src/scenes/App/App.cs.uid @@ -0,0 +1 @@ +uid://dj3e07cirb8b8 diff --git a/src/scenes/App/App.tscn b/src/scenes/App/App.tscn new file mode 100644 index 0000000..ae26923 --- /dev/null +++ b/src/scenes/App/App.tscn @@ -0,0 +1,34 @@ +[gd_scene format=3 uid="uid://61elxchmh0e6"] + +[ext_resource type="Script" uid="uid://dj3e07cirb8b8" path="res://src/scenes/App/App.cs" id="1_app"] +[ext_resource type="PackedScene" path="res://src/ui/StaticBackground/StaticBackground.tscn" id="2_background"] +[ext_resource type="Script" uid="uid://b3ffmrp6u1rqu" path="res://src/ui/TouchInputGuard/TouchInputGuard.cs" id="4_touch"] +[ext_resource type="Script" uid="uid://dwvtpapqjcjth" path="res://src/core/Session/SessionController.cs" id="5_session"] +[ext_resource type="PackedScene" path="res://src/ui/InteractivePet/InteractivePetHost.tscn" id="6_pet"] + +[node name="App" type="Node" unique_id=1460949439] +script = ExtResource("1_app") + +[node name="TouchInputGuard" type="Node" parent="." unique_id=1951725665] +process_mode = 3 +script = ExtResource("4_touch") + +[node name="SessionController" type="Node" parent="." unique_id=395661133] +script = ExtResource("5_session") + +[node name="BackgroundLayer" type="CanvasLayer" parent="." unique_id=572407905] +layer = 0 + +[node name="StaticBackground" parent="BackgroundLayer" unique_id=1842090366 instance=ExtResource("2_background")] + +[node name="UiLayer" type="CanvasLayer" parent="." unique_id=1814861110] + +[node name="ScreenHost" type="Control" parent="UiLayer" unique_id=635764758] +layout_mode = 3 +anchors_preset = 15 +anchor_right = 1.0 +anchor_bottom = 1.0 +grow_horizontal = 2 +grow_vertical = 2 + +[node name="InteractivePetHost" parent="." unique_id=1226827678 instance=ExtResource("6_pet")] diff --git a/src/scenes/CardAmountScreen/CardAmountScreen.cs b/src/scenes/CardAmountScreen/CardAmountScreen.cs new file mode 100644 index 0000000..2ad5ff3 --- /dev/null +++ b/src/scenes/CardAmountScreen/CardAmountScreen.cs @@ -0,0 +1,271 @@ +using Exchanger.Core.Configuration; +using Exchanger.Core.Session; +using Exchanger.Core.Theming; +using Godot; +using System; +using System.Collections.Generic; +using System.Linq; + +namespace Exchanger.Scenes.CardAmountScreen; + +public partial class CardAmountScreen : ThemeBindableScreen +{ + protected override string ThemeScreenKey => "card_amount"; + private const int MaximumThemePresetSlots = 16; + + private Button _backButton = null!; + private Button _homeNavigationButton = null!; + private Button _otherAmountButton = null!; + private GridContainer _presetGrid = null!; + private Label _selectionLabel = null!; + private Label _rewardLabel = null!; + private Label _rewardBonusLabel = null!; + private Button _confirmButton = null!; + private ThemeManager _themeManager = null!; + private readonly List<(Button Button, Action Handler)> _themePresetSlots = new(); + private PricingSettings _pricing = new(); + private AnimatedBannerTextSettings _bannerTexts = new(); + private int? _selectedAmount; + private int? _maximumAvailableTokens; + + public event Action? BackRequested; + + public event Action? HomeRequested; + + public event Action? OtherAmountRequested; + + public event Action? AmountSelected; + + public override void _Ready() + { + _backButton = GetNode