Настройки gitignore для .deps — прочитайте внимательно!

Конфигурация ИИ-агента для Defold

Пример конфигурации AGENTS.md и набор скиллов (.agents/) для разработки игр с помощью ИИ на движке Defold. Это в первую очередь исследовательский проект, но вы можете свободно использовать конфигурацию и скиллы в своих проектах.

Папка .deps/ используется скиллом defold-project-setup для загрузки исходников зависимостей проекта и встроенных модулей Defold (builtins), давая вашему ИИ-агенту простой доступ к API и типам зависимостей (только для чтения). Для обновления после изменения зависимостей в game.project запустите скилл defold-project-setup.

Переводы: English

Поддерживаемые ИИ-агенты

Конфигурация использует формат директории .agents/, который поддерживается:

• Amp
• Claude Code (требует переименования .agents/ в .claude/)
• Codex CLI
• Cursor
• Factory Droid
• GitHub Copilot (требует переименования .agents/ в .github/)
• Kilo Code
• OpenCode
• Warp
• Windsurf (требует переименования .agents/ в .windsurf/)
• и многими другими

Требования

• Defold >= 1.12.2
• Python >= 3.11 — необходим для скриптов скиллов.
  • Windows: winget install Python.Python.3
  • macOS: brew install python3
  • Linux: sudo apt-get install python3

Установка

1. Скопируйте AGENTS.md, папку .agents/ и файл .defignore в корень вашего Defold-проекта.

Примечание: Некоторые ИИ-агенты используют собственные директории:

• Claude Code: Переименуйте .agents/ в .claude/ и выполните поиск-замену во всех .md файлах: .agents/ → .claude/
• GitHub Copilot: Переименуйте .agents/ в .github/ и выполните поиск-замену во всех .md файлах: .agents/skills/ → .github/skills/
• Windsurf: Переименуйте .agents/ в .windsurf/ и выполните поиск-замену во всех .md файлах: .agents/ → .windsurf/

2. Попросите вашего ИИ-агента: Запусти скилл defold-project-setup, чтобы скачать зависимости в .deps/
3. Попросите вашего ИИ-агента: Обнови AGENTS.md на основе структуры моего проекта, зависимостей и папок

Готово — агент автоматически подхватит инструкции и скиллы.

Настройки gitignore для .deps — прочитайте внимательно!

Если вы добавите .deps/ в .gitignore (чтобы не коммитить загруженные зависимости), ИИ-агенты по умолчанию будут его игнорировать — их внутренние инструменты (Glob, Grep, file picker) учитывают .gitignore. Иронично, что во многих агентах node_modules в JS-проектах обрабатывается особым образом и всё равно индексируется, а .deps в Defold-проектах такой привилегии не получает. Чтобы агенты видели .deps, но он не попадал в git, добавьте эти файлы:

1. .gitignore — используйте .deps/** (не /.deps), чтобы negation-правила работали корректно:

.deps/**

2. .cursorignore (только Cursor) — negation, чтобы индексация включала .deps:

!.deps
!.deps/**

3. .ignore (для ripgrep/Grep) — тот же negation, чтобы поиск находил файлы в .deps:

!.deps
!.deps/**

Claude Code не имеет .cursorignore. Добавьте в .claude/settings.json:

{
  "permissions": {
    "allow": ["Read(./.deps/**)"]
  }
}

Для других агентов ищите обходные пути в их документации (ignore-файлы, настройки индексации, правила доступа).

Самопроверка: Попросите агента: «Найди все файлы input_binding». Он должен вернуть .deps/builtins/input/all.input_binding. Если нет — агент по-прежнему не видит .deps, перепроверьте настройки выше.

Установил... а что дальше-то?

Откройте проект в Defold Editor и ИИ-агент рядом. Вот что можно делать:

• "Создай новый экран main_menu с двумя кнопками: Играть и Настройки" — агент использует monarch-screen-setup для создания коллекции, GUI и скрипта экрана.
• "Добавь игровой объект игрока со спрайтом и коллизией" — агент использует defold-proto-file-editing для создания файлов .go, .sprite и .collisionobject.
• "Напиши скрипт, который двигает игрока влево-вправо стрелками" — агент найдёт API ввода Defold и напишет .script по соглашениям проекта.
• "Собери и запусти игру" — агент использует defold-project-build для компиляции через запущенный Defold Editor и сообщит об ошибках.
• "Как работает go.animate?" — агент загрузит документацию API через defold-api-fetch и объяснит с примерами.
• "Я добавил новую зависимость в game.project, обнови .deps" — агент запустит defold-project-setup для повторной загрузки зависимостей.
• "Реализуй изолированный Lua-модуль аркадной 2D-коллизии на базе quad-tree, с тестами" — агент напишет самодостаточный модуль по соглашениям проекта и создаст юнит-тесты.
• "Изолируй этот код в локальную Lua-функцию и создай её вариант в C++ native extension" — агент выделит выбранный код в Lua-функцию, а затем использует defold-native-extension-editing для создания C++ реализации.

Просто опишите, что вам нужно, на любом языке — агент знает структуру проекта, API Defold и все соглашения из AGENTS.md.

Лучшие практики

• Сначала планируйте, потом реализуйте — попросите агента составить план перед реализацией. В некоторых агентах есть даже специальный режим "plan". Сохраните план в файл (например, PLAN.md) и отдельными этапами просите агента реализовать его в отдельных беседах.
• Одна задача — одна беседа — небольшие, сфокусированные запросы дают лучший результат, чем длинные многошаговые сессии.
• Держите контекст ниже ~65% — когда беседа становится слишком длинной, агент теряет фокус. Начинайте новую сессию до того, как это случится.
• Начинайте с готового проекта — создать полноценную игру с нуля силами одного ИИ-агента пока вряд ли получится. Лучший подход — добавить файлы агента (AGENTS.md, .agents/) в уже работающий Defold-проект и развивать его.
• Добавляйте как можно больше логов — чем больше вызовов print() в ваших скриптах, тем проще ИИ-агенту отлаживать проблемы по выводу. Например, вызовите monarch.debug() для логирования переключений экранов. В этом проекте также есть полезная функция fail_on_error() в main/main.script — она немедленно закрывает игру при первой ошибке, чтобы вы сразу видели, ГДЕ произошла проблема, а не отматывали тысячи строк журнала.

Скиллы

В .agents/skills/ включены следующие скиллы:

Поддерживаемые модули Defold

Конфигурация AGENTS.md включает встроенную поддержку этих библиотек Defold при их наличии в проекте:

• Monarch — Управление экранами и попапами
• Object Interpolation — Плавное движение объектов с фиксированным шагом времени
• Sharp Sprite — Пиксельно-точный рендеринг спрайтов с материалами RGSS
• Xmath — Математические операции без аллокаций для векторов, кватернионов и матриц

Roadmap - and can the community help with that?...

1. Обкатка на реальных проектах — использовать эту конфигурацию в рабочих Defold-проектах и дорабатывать в процессе. Кстати, вы всегда можете попросить вашего ИИ-агента "доработать этот скилл на основе нашего диалога" — и он сам обновит файлы скилла.
2. Новые скиллы на основе лучших практик — добавлять скиллы для вещей, которые сразу не пришли в голову авторам: как писать шейдеры, как создавать высокопроизводительные игры, как разделять логику и отображение, и так далее.
3. Скиллы для популярных библиотек — создавать скиллы для популярных библиотек Defold, которые активируются автоматически при наличии библиотеки в проекте пользователя.
4. MCP-сервер для Defold — попробовать сделать MCP-сервер на базе HTTP-сервера Defold Editor, чтобы ИИ-агенты могли взаимодействовать с запущенным редактором напрямую (выполнять editor-скрипты, читать структуру проекта и т.д.).
5. Понять, чего не хватает Defold — определить, что нужно движку и редактору Defold, чтобы достичь уровня ИИ-разработки, который уже существует для веб-сайтов и мобильных приложений.

Участие в проекте

Мы рады любым контрибуциям! Открывайте issues и pull requests.

• 🌍 Issues можно писать на любом языке — ИИ всё переведёт и поймёт.
• 🐍 Все скрипты в проекте должны быть написаны на Python или нативном шелле платформы (bash, PowerShell), чтобы не плодить зависимости и не требовать дополнительного ПО.

Лицензия

Проект передан в общественное достояние по лицензии CC0 1.0 Universal.