server-deploy/windows-dev-stack/godot-mcp-pro-v1.14.1/addons/godot_mcp/skills.ru.md

Language: English | 日本語 | Português (BR) | Español | Русский | 简体中文 | हिन्दी

Godot MCP Pro — Навыки для ИИ-ассистентов

Скопируйте этот файл в .claude/skills.md в корне вашего проекта Godot, чтобы дать Claude Code полный контекст по эффективному использованию Godot MCP Pro.

Что такое Godot MCP Pro?

Вам доступны 169 MCP-инструмента, которые напрямую подключаются к редактору Godot 4. Вы можете создавать сцены, писать скрипты, симулировать ввод игрока, инспектировать запущенные игры и многое другое — всё это без выхода пользователя из данного разговора. Все изменения проходят через систему UndoRedo Godot, поэтому пользователь всегда может нажать Ctrl+Z.

Основные рабочие процессы

1. Изучение проекта

Всегда начинайте с понимания проекта перед внесением изменений:

get_project_info          → название проекта, версия Godot, рендерер, размер viewport
get_filesystem_tree       → структура директорий (используйте filter: "*.tscn" или "*.gd")
get_scene_tree            → иерархия нод текущей открытой сцены
read_script               → прочитать любой файл GDScript
get_project_settings      → проверить конфигурацию проекта

2. Создание 2D-сцены

create_scene   → создать файл .tscn с указанием типа корневой ноды
add_node       → добавить дочерние ноды со свойствами
create_script  → написать GDScript для игровой логики
attach_script  → прикрепить скрипт к ноде
update_property → установить position, scale, modulate и т.д.
save_scene     → сохранить на диск

Пример — создание игрока:

1. create_scene с root_type CharacterBody2D, path res://scenes/player.tscn
2. add_node типа Sprite2D со свойством texture
3. add_node типа CollisionShape2D
4. add_resource для назначения формы (например, RectangleShape2D) на CollisionShape2D
5. create_script с логикой движения
6. attach_script на корневую ноду
7. save_scene

3. Создание 3D-сцены

create_scene         → root_type: Node3D
add_mesh_instance    → добавить примитивы (box, sphere, cylinder, plane) или импортировать .glb/.gltf
setup_lighting       → добавить DirectionalLight3D, OmniLight3D или SpotLight3D
setup_environment    → небо, окружающий свет, туман, tonemap
setup_camera_3d      → камера с опциональным SpringArm3D для вида от третьего лица
set_material_3d      → PBR-материалы (albedo, metallic, roughness, emission)
setup_collision      → добавить формы столкновений к физическим телам
setup_physics_body   → настроить массу, трение, гравитацию

4. Написание и редактирование скриптов

create_script  → создать новый файл .gd (укажите полное содержимое)
edit_script    → изменить существующие скрипты
  - Используйте `replacements: [{search: "old code", replace: "new code"}]` для точечных правок
  - Используйте `content` для полной замены файла
  - Используйте `insert_at_line` + `text` для вставки кода
validate_script → проверить синтаксические ошибки без запуска
read_script    → прочитать текущее содержимое перед редактированием

5. Тестирование и отладка

play_scene             → запустить игру (mode: "current", "main" или путь к файлу)
get_game_screenshot    → увидеть, как игра выглядит прямо сейчас
capture_frames         → захватить несколько кадров для наблюдения за движением/анимацией
get_game_scene_tree    → инспектировать дерево сцены в runtime
get_game_node_properties → прочитать значения в runtime (position, health, state и т.д.)
set_game_node_property → изменить значения в запущенной игре
simulate_key           → нажать клавиши (WASD, SPACE и т.д.) с указанием длительности
simulate_mouse_click   → кликнуть по координатам viewport
simulate_action        → вызвать действия InputMap (move_left, jump и т.д.)
get_editor_errors      → проверить ошибки выполнения
stop_scene             → остановить игру

Цикл плейтестинга:

1. play_scene → запустить игру
2. get_game_screenshot → увидеть текущее состояние
3. simulate_key / simulate_action → взаимодействовать с игрой
4. capture_frames → наблюдать поведение во времени
5. get_game_node_properties → проверить конкретные значения
6. stop_scene → остановить по завершении
7. Исправить проблемы в скриптах → повторить

6. Анимации

# Убедитесь, что в сцене есть нода AnimationPlayer
create_animation       → новая анимация с длительностью и режимом зацикливания
add_animation_track    → добавить треки property/transform/method
set_animation_keyframe → вставить ключевые кадры в определённые моменты
get_animation_info     → просмотреть существующие анимации

Пример — прыгающий спрайт:

1. create_animation name bounce, length 1.0, loop_mode 1 (линейный цикл)
2. add_animation_track track_path Sprite2D:position, track_type value
3. set_animation_keyframe time 0.0, value Vector2(0, 0)
4. set_animation_keyframe time 0.5, value Vector2(0, -50)
5. set_animation_keyframe time 1.0, value Vector2(0, 0)

7. UI / HUD

add_node          → Control, Label, Button, TextureRect и т.д.
set_anchor_preset → позиционирование Controls (full_rect, center, bottom_wide и т.д.)
set_theme_color   → изменить font_color и т.д.
set_theme_font_size → настроить размер текста
set_theme_stylebox  → фоны, рамки, скруглённые углы
connect_signal    → подключить pressed кнопки, value_changed и т.д.

8. TileMap

tilemap_get_info      → проверить источники набора тайлов и раскладку атласа
tilemap_set_cell      → разместить отдельные тайлы
tilemap_fill_rect     → заполнить прямоугольные области
tilemap_get_used_cells → посмотреть, что уже размещено
tilemap_clear         → очистить все ячейки

9. Аудио

add_audio_bus        → создать аудио-шины (SFX, Music, UI)
set_audio_bus        → настроить громкость, соло, заглушение
add_audio_bus_effect → добавить реверберацию, задержку, компрессор и т.д.
add_audio_player     → добавить ноды AudioStreamPlayer(2D/3D)

10. Конфигурация проекта

set_project_setting  → изменить размер viewport, настройки физики и т.д.
set_input_action     → определить маппинг ввода (move_left → KEY_A и т.д.)
add_autoload         → зарегистрировать синглтоны autoload
set_physics_layers   → именовать слои столкновений (player, enemy, world и т.д.)

Важные правила и подводные камни

Значения свойств

Свойства автоматически парсятся из строк. Используйте следующие форматы:

• Vector2: "Vector2(100, 200)"
• Vector3: "Vector3(1, 2, 3)"
• Color: "Color(1, 0, 0, 1)" или "#ff0000"
• Bool: "true" / "false"
• Числа: "42", "3.14"
• Enum: Используйте целочисленные значения (например, 0 для первого значения enum)

Никогда не редактируйте project.godot напрямую

Редактор Godot постоянно перезаписывает project.godot. Всегда используйте set_project_setting для изменения настроек проекта.

Аннотации типов в GDScript

При написании GDScript с циклами for по нетипизированным массивам используйте явные аннотации типов:

# ПЛОХО — приведёт к ошибкам
for item in some_untyped_array:
    var x := item.value  # вывод типов не работает

# ХОРОШО
for i in range(some_untyped_array.size()):
    var item: Dictionary = some_untyped_array[i]
    var x: int = item.value

Изменения скриптов требуют перезагрузки

После создания или значительного изменения скриптов используйте reload_project, чтобы Godot подхватил изменения. Особенно важно после create_script.

Советы по simulate_key

• Используйте короткие длительности (0.3–0.5 секунд) для точного перемещения
• Длинные длительности (1+ секунда) приводят к промахам
• Для тестирования геймплея предпочитайте simulate_action вместо simulate_key, когда определены действия InputMap

simulate_mouse_click

• По умолчанию auto_release: true отправляет press и release — необходимо для UI-кнопок
• UI-кнопки срабатывают на release, поэтому нужны оба события

Ограничения execute_game_script

• Нельзя использовать вложенные функции (func внутри func) — вызывает ошибку компиляции
• Используйте .get("property") вместо .property для динамического доступа
• Ошибки выполнения приостанавливают отладчик (автоматически продолжается, но лучше избегать)

Коллизии и области подбора

• Для собираемых предметов используйте Area3D/Area2D с радиусом >= 1.5
• Меньшие радиусы почти невозможно активировать симулированным вводом

Сохраняйте часто

Вызывайте save_scene после значительных изменений. Несохранённые изменения могут быть потеряны при перезагрузке редактора.

Инструменты анализа и отладки

Когда что-то пошло не так, используйте эти инструменты для расследования:

get_editor_errors          → проверить ошибки скриптов и исключения runtime
get_output_log             → прочитать вывод print() и предупреждения
analyze_scene_complexity   → найти узкие места производительности
analyze_signal_flow        → визуализировать соединения сигналов
detect_circular_dependencies → найти циклические ссылки скриптов/сцен
find_unused_resources      → очистить неиспользуемые файлы
get_performance_monitors   → FPS, память, draw calls, статистика физики

Тестирование и QA

run_test_scenario   → определить и запустить автоматизированные тестовые сценарии
assert_node_state   → проверить, что свойства нод соответствуют ожидаемым значениям
assert_screen_text  → проверить, что текст отображается на экране
compare_screenshots → визуальное регрессионное тестирование (используйте пути к файлам, не base64)
run_stress_test     → создать множество нод для тестирования производительности

Продвинутые паттерны

Операции между сценами

cross_scene_set_property → изменить ноды в сценах, которые сейчас не открыты
find_node_references     → найти все файлы, ссылающиеся на паттерн
batch_set_property       → установить свойство для всех нод определённого типа

Работа с шейдерами

create_shader        → написать шейдерный код в стиле GLSL
assign_shader_material → применить к ноде
set_shader_param     → настроить uniform-параметры в runtime
get_shader_params    → просмотреть текущие значения

Навигация (3D)

setup_navigation_region → определить проходимую область
bake_navigation_mesh   → сгенерировать навигационную сетку
setup_navigation_agent → добавить поиск пути для персонажей

AnimationTree и конечные автоматы

create_animation_tree           → настроить AnimationTree с конечным автоматом или деревом смешивания
add_state_machine_state         → добавить состояния (idle, walk, run, jump)
add_state_machine_transition    → определить переходы между состояниями
set_tree_parameter              → управлять параметрами смешивания

Рекомендуемый порядок работы

При создании новой игры с нуля:

1. Настройка проекта — get_project_info, set_project_setting (viewport, физика)
2. Маппинг ввода — set_input_action для всех управлений игрока
3. Главная сцена — create_scene, установить как главную сцену
4. Игрок — создать сцену игрока со спрайтом, коллизией, скриптом
5. Уровень/Мир — построить окружение (TileMap, 3D-меши и т.д.)
6. Игровая логика — скрипты для врагов, предметов, UI
7. Аудио — настроить шины, добавить аудиоплееры
8. Плейтестинг — play_scene, тест с симулированным вводом, исправление багов
9. Полировка — анимации, частицы, шейдеры, темы
10. Экспорт — list_export_presets, export_project