CLAUDE.md

Заметки для агентов, работающих с этим репозиторием.

Что это за проект

Двумерная игра с видом сбоку на Godot 4.7. Референс — Fallout Shelter: разрез убежища, комнаты в сетке, жители. Игра полностью 2D. Новые игровые сцены — на Node2D/Control; 3D-узлам в проекте места нет. Рендерер при этом Forward+ — так решил владелец проекта, не переключайте его без явной просьбы.

Работа через MCP, а не через файлы

В проекте включён плагин addons/godot_ai, редактор Godot обычно запущен и подключён. Сцены и ресурсы правьте инструментами MCP (scene_manage, ui_manage, node_create, theme_manage, resource_manage), а не редактированием .tscn руками — иначе открытый редактор перезапишет изменения при сохранении.

Скрипты — через script_create / script_patch: они возвращают диагностику парсера сразу.

Проверять результат — project_run + editor_screenshot(source="game"). Ввод в запущенную игру шлётся через game_manage(op="input_key"); input_action не двигает фокус Control-ов, для навигации по UI нужны настоящие события клавиш.

Известные особенности

node_set_property не принимает целочисленный 0 — используйте batch_execute с командой set_property.
Правка скрипта, который зарегистрирован автозагрузкой, даёт в ответе GDScript reload failed with error code 43. Это неудачная горячая перезагрузка в редакторе, а не ошибка разбора: проверяйте logs_read(source="editor"), игра при этом запускается чисто.
project_manage(op="settings_set") отказывается менять application/run/main_scene.
Большие ui_manage(op="build_layout") иногда не доезжают целиком — стройте дерево несколькими вызовами поменьше.
Запуск из редактора отдаёт встроенное окно: Embedded window can't be resized в логе — норма.

Конвенции кода

Отступы — табы (см. .editorconfig), статическая типизация везде, где возможно.
Комментарии и весь UI-текст — по-русски; имена узлов, файлов, методов, сигналов — по-английски.
Комментарий объясняет почему, а не пересказывает код.
Приватные члены — с подчёркиванием: _card, _focus_first_button().
Документирующие комментарии ## — на классах, сигналах и неочевидных методах.

Архитектура UI

Единая тема themes/main_menu.theme.tres на корне каждого экрана. Цвета в узлах не хардкодим.
Экран = сцена со своим скриптом, наружу торчат open() / close() и сигнал closed.
Оверлеи центрируются CenterContainer, а не пресетом center: пресет ставит левый верхний угол карточки в центр экрана. Та же ловушка у bottom_wide — он прижимает к нижнему краю верх панели, и она уезжает за экран; для нижней панели используйте MarginContainer во весь экран + HBoxContainer с size_flags_vertical = SIZE_SHRINK_END у содержимого.
Контейнеры не раскладывают скрытые узлы — после visible = true нужен await get_tree().process_frame, прежде чем читать size (например, для pivot_offset).
Наведение мышью делается фокусом (mouse_entered → grab_focus), чтобы у мыши и клавиатуры была одна подсветка.

Игровой слой

Три файла в scripts/game/, разделены намеренно:

vault_grid.gd — только данные и правила (RefCounted, без узлов). Сюда идут изменения логики: типы комнат, размещение, ресурсы.
vault_view.gd — только _draw(). Сюда идут изменения картинки. Когда появится графика, переписывается этот файл, остальные не трогаются.
vault_scene.gd — связка модели, вида, камеры и HUD плюс контракт сохранения.

Новый тип комнаты добавляется одной записью в VaultGrid.KINDS: кнопка в панели строительства и подсчёт ресурсов подхватятся сами.

Автозагрузки

GameSettings (GameSettingsService) и SaveManager (SaveManagerService). У обеих есть class_name: константы, перечисления и типы берём через него, экземпляр — через get_node("/root/..."). Имя автозагрузки редактор не резолвит без перезапуска проекта.

Контракт сохранения игровой сцены описан в README.md.

Проверка

Изменения в UI считаются сделанными только после запуска и скриншота. Логи смотреть в обоих источниках: logs_read(source="game") и logs_read(source="editor") — ошибки загрузки скриптов попадают только во второй.

6.4 KiB Raw Blame History Unescape Escape