Unity и Codex: официальный плагин, Unity CLI, тесты и правки

Откройте корень проекта Unity в Codex, установите официальный плагин Unity для Unity 6 и новее, а для работы с открытым редактором подключите Unity CLI. Поручайте агенту C# скрипты, тесты, настройки и текстовые ассеты, затем проверяйте diff и тесты; сцены и визуальный результат смотрите в Editor. Безопасный процесс начинается с Git, сохранённых .meta файлов и небольшой задачи.

Что понадобится до запуска Codex

Для работы нужен локальный проект Codex с доступом к корню Unity проекта; его можно открыть в десктопном приложении ChatGPT. CLI или расширение IDE удобны, если вы уже работаете в терминале или редакторе. Codex использует выбранную папку проекта для Git и автоматически ищет AGENTS.md в основном корне.

• Рабочий Unity проект открывается без ошибок до правки.
• Корень проекта содержит Assets, Packages и ProjectSettings.
• Проект добавлен в Git, исходное состояние закоммичено.
• Есть команда теста или короткий ручной сценарий проверки.
• Для задачи создана отдельная ветка или worktree.

Перед крупной задачей сделайте коммит: навыки плагина меняют скрипты, сцены и ассеты напрямую, и не каждое изменение можно отменить из Editor.

Если Codex ещё не установлен, сначала используйте пошаговую установку Codex. Для Unity не требуется отдельная версия приложения.

Для Codex из России включайте VPN для всей системы в режиме TUN и держите одну страну подключения: иначе CLI и плагины могут не достучаться до сервера; регистрацию и оплату смотрите в инструкции Codex в России, настройку VPN в Codex и VPN.

Не давайте агенту задачу «сделай игру» в существующем проекте. Сначала ограничьте одну механику, одну сцену и измеримый результат.

Как подключить Codex к Unity

Подключите официальный плагин к Codex, затем Unity CLI к открытому Editor. Unity выпустила плагин 16 сентября 2026 года с 31 навыком от своих команд: UI Toolkit и uGUI, 2D и тайлмапы, URP и Shader Graph, звук, навигация и физика, IAP и LevelPlay, мультиплеер, веб и локализация. Для простой правки файлов плагин не обязателен: остаётся работа с корнем проекта под контролем Git. В приложении ChatGPT он устанавливается из каталога плагинов в один клик, без отдельной настройки в каждом проекте.

Плагин работает с Unity 6.0 и новее; он не относится к пакетам Asset Store и не устанавливается через Package Manager. Для проектов на Unity 2021-2022 используйте базовую схему этой статьи: правка файлов, Git и тесты.

Установка плагина, проверка и обновление выполняются командами Codex:

1. Откройте корень Unity проекта в Codex.
2. В терминале выполните codex plugin marketplace add Unity-Technologies/unity-agent-plugin, затем codex plugin add unity@unity-agent-plugin.
3. Начните новую сессию Codex и введите /unity:: навыки должны появиться в меню. Команда codex plugin list должна показывать unity со статусами installed и enabled.
4. Когда потребуется обновление, выполните codex plugin marketplace upgrade unity-agent-plugin.

Многие навыки работают с открытым редактором через Unity CLI: создают GameObject, меняют настройки импорта, выполняют C# в Editor и проверяют результат. Если задача требует CLI, агент проверяет, установлен ли он, и может поставить его вместе с пакетом связи с редактором; Unity Hub сейчас устанавливает CLI автоматически.

Для самостоятельной установки Unity CLI выберите команду под свою систему и после установки закройте и снова откройте терминал. Связь с открытым редактором даёт пакет Pipeline: откройте проект в Unity Editor, войдите командой unity auth login и в папке проекта выполните unity pipeline install, после перекомпиляции проекта проверьте установку командой unity pipeline list: в выводе должна появиться строка Pipeline: Installed.

# macOS или Linux
curl -fsSL https://unity.com/install.sh | bash
# Windows
winget install Unity.CLI
# macOS или Linux через Homebrew
brew install --cask unity-cli

Для управления открытым Editor через Pipeline нужен Unity 6.0 LTS или новее. Unity CLI бесплатен, работает отдельно от Unity AI и не требует подписки Unity AI; с локальным редактором он работает без интернета, а сервер принимает подключения только с localhost.

Unity CLI пока в статусе бета: в журнале выпусков последней указана версия 1.0.0-beta.12 от 30.09.2026. Если песочница Codex не пропускает команды к Editor через localhost, выполните unity mcp configure codex: команда добавляет сервер Unity в config.toml Codex и ослабляет сетевую политику песочницы, чтобы вызовы unity mcp и прямые команды unity доходили до редактора.

MCP-сервер из пакета Unity AI Assistant объявлен устаревшим, Unity рекомендует перейти на Unity CLI.

Если хотите работать с Codex внутри Editor, AI gateway в Unity AI Assistant позволяет выбрать его в окне Assistant.

По теме: Unity и Claude Code: как настроить проект и проверить код

Какую папку открыть

Открывайте корень Unity проекта, а не только папку Assets. Unity хранит исходники и ассеты в Assets, список пакетов в Packages, настройки в ProjectSettings, а локальный кэш импорта в Library.

Храните в Git Assets, Packages и ProjectSettings, включая связанные .meta файлы. Папку Library исключайте из системы контроля версий: Unity использует её как восстанавливаемый локальный кэш импорта.

Файл .meta должен оставаться рядом со своим ассетом. При перемещении ассета вне Unity переносите вместе с ним .meta, чтобы сохранить эту пару.

• Разрешайте изменения в Assets/Scripts и тестах, если задача касается логики.
• Не просите вручную редактировать Library, Temp или импортированные кэши.
• При создании или перемещении ассета проверяйте его .meta файл.
• Сцены и prefab меняйте маленькими порциями: их текстовый diff труднее проверить, чем C# код.

Какие инструкции положить в проект

Создайте в корне короткий AGENTS.md. В нём укажите версию Unity, разрешённые каталоги, команду тестов, запрет на обновление пакетов без отдельной задачи и правило сохранять пары ассет плюс .meta. Codex читает AGENTS.md перед работой: от корня проекта, обычно корня Git, до текущей папки; файлы ближе к рабочей папке дополняют и переопределяют общие правила. По умолчанию учитывается до 32 КиБ инструкций.

# Unity project rules
- Change only Assets/Scripts and Assets/Tests for this task.
- Do not edit Library, Temp, Logs or package versions.
- Keep every asset with its .meta file.
- Run EditMode tests before reporting completion.
- Report changed files and remaining manual checks.

AGENTS.md задаёт правила и снижает риск широкой правки, но технические границы записи устанавливает песочница Codex. Нарушение правил видно в diff отслеживаемых файлов; игнорируемые через .gitignore файлы в diff не видны, поэтому список разрешённых путей сверяйте отдельно.

Перед задачей на интерфейс назовите UI-систему проекта: для новых проектов Unity рекомендует UI Toolkit, а для существующего проекта на Unity UI укажите uGUI. Так агенту не придётся угадывать, с какой системой вы работаете.

По теме: Codex в VS Code: установка, первый запрос и проверка

Первая задача для Codex

Выберите механику без сложного визуального ассета, например счётчик очков, ограничение здоровья или таймер, и укажите существующий компонент, ожидаемое поведение, крайний случай и тест или ручной сценарий.

1. Откройте корень Unity проекта в Codex.
2. Попросите сначала найти связанные скрипты и предложить план без изменений.
3. Подтвердите точные файлы, которые можно менять.
4. Попросите добавить или обновить EditMode тест для чистой C# логики.
5. Разрешите реализацию только после согласования границ.
6. Проверьте diff, затем откройте проект в Unity и дождитесь окончания импорта.
7. Запустите тесты и короткий сценарий в Play Mode.

Безопасный пример: «В ScoreCounter.cs добавь метод увеличения счёта только на положительное значение. Ноль и отрицательное значение должны оставлять счёт без изменений. Не меняй сцену и пакеты. Добавь EditMode тесты на три случая».

Как запускать тесты

Запускайте EditMode и PlayMode тесты через Test Runner или из терминала. Unity Test Framework поддерживает оба режима: EditMode подходит для чистой логики и редакторских функций, PlayMode для поведения объектов во время запуска сцены.

Unity находит тесты в тестовой сборке: выберите Assets, откройте Window > General > Test Runner и нажмите Create a new Test Assembly Folder in the active path либо выберите Assets > Create > Testing > Test Assembly Folder. Появится папка Tests с файлом .asmdef и нужными ссылками на NUnit.

Для запуска из терминала Unity поддерживает -runTests, -testPlatform и -testResults; значения платформы указывайте как EditMode или PlayMode. Аргумент -quit не поддерживается при выполнении тестов и может закрыть Editor до их завершения. Точный путь к Editor зависит от системы и установленной версии, поэтому сначала получите рабочую команду вручную, затем запишите её в инструкции проекта. В примерах замените /path/to/Unity и /path/to/project на свои пути, сохранив кавычки.

"/path/to/Unity" -batchmode -projectPath "/path/to/project" -runTests -testPlatform EditMode -testResults "/tmp/editmode-results.xml"
"/path/to/Unity" -batchmode -projectPath "/path/to/project" -runTests -testPlatform PlayMode -testResults "/tmp/playmode-results.xml"

Не считайте нулевой вывод доказательством успеха. Проверьте код завершения, XML с результатами и лог Unity. В CI указывайте точный исполняемый файл версии Editor, которой пользуется проект.

Можно использовать команду unity test из Unity CLI: она запускает EditMode и PlayMode тесты в batch mode и пишет отчёт NUnit. Режим задаётся через --mode, путь отчёта через --output; по умолчанию создаётся test-results.xml.

По теме: Codex Chrome: как подключить расширение и проверить доступ

Что проверить перед коммитом

Проверяйте три уровня: код, импорт и поведение сцены. После C# компиляции отдельно проверьте ссылки сцены, а крайние случаи подтвердите тестами, даже если сцена запускается без ошибок.

• Diff содержит только согласованные файлы.
• Новый ассет добавлен вместе с .meta.
• Unity завершила импорт без красных ошибок Console.
• EditMode тесты прошли.
• PlayMode тесты или ручной сценарий прошли.
• Ссылки в Inspector не стали Missing.
• Проект повторно открывается после закрытия Editor.

Перед коммитом попросите Codex провести независимое ревью. Официальная документация code review описывает команду /review для сравнения с базовой веткой или проверки незакоммиченных изменений без модификации рабочего дерева.

Диагностика частых проблем

• Unity показывает Missing Script: проверьте имя класса, имя файла, пространство имён и ошибки компиляции выше по Console.
• Пропали ссылки на ассет: найдите удалённый или изменённый .meta и восстановите пару из Git.
• Появился огромный diff в Library: остановитесь, исправьте ignore и удалите кэш из индекса Git.
• Тесты не запускаются из терминала: сверьте путь к Editor, версию проекта, кавычки в -projectPath и файл результатов.
• Сцена изменилась сильнее задачи: откатите сцену и перенесите логику в отдельный компонент с минимальной ручной привязкой.
• После обновления пакета появились ошибки: верните Packages/manifest.json и lock-файл к контрольному состоянию.

Если Codex внёс слишком широкие изменения, вернитесь к ветке до правки и сократите задачу. Не просите агента исправлять собственный большой diff без новой границы, иначе область изменения продолжит расти.

Когда Codex не заменяет Unity Editor

Визуальную оценку сцены делаете вы в Unity Editor: текстовый diff не показывает, как она выглядит и ведёт себя. Расстановку объектов и предпросмотр света смотрите в Scene view, а анимационные клипы в окне Animation; физику, игровую логику и ощущения управления проверяйте в Play Mode. Бинарные ассеты также нельзя надёжно оценить по текстовому diff.

С Unity CLI агент может пересобрать скрипты открытого Editor и получить ошибки компиляции командой unity recompile, а unity status покажет, какие редакторы подключены. Скриншоты, логи и автоматические тесты помогают ему оценить результат, но визуальную оценку сцены и ощущения управления всё равно делаете вы.

Для первой игры полезна отдельная схема из статьи вайбкодинг игр. Если нужен другой агент, есть смежный материал Unity и Claude Code, но одновременно править одну сцену двумя инструментами не следует.

Частые вопросы

Есть ли официальный плагин Codex для Unity?

Да. 16 сентября 2026 года Unity выпустила официальный плагин для Codex (unity@unity-agent-plugin) с навыками от инженеров Unity. Для простой правки файлов он не обязателен: Codex и без него открывает корень проекта и меняет файлы под контролем Git.

Можно ли поручить Codex создать сцену?

Можно подготовить скрипты и текстовые изменения, но сцену нужно открыть в Unity, проверить ссылки, импорт и поведение в Play Mode.

Нужно ли добавлять Library в Git?

Нет. Unity описывает Library как локальный кэш, который восстанавливается из исходных папок проекта.

Что проверять первым после правки?

Сначала diff и пары ассет плюс .meta, затем импорт без ошибок, EditMode тесты и короткий Play Mode сценарий.