A beginner’s guide to Unity CLI and the Pipeline package

Недавно мы запустили Unity CLI , и отзывы были исключительно положительными, при этом появляется все больше вдохновляющих примеров его использования. Однако, если вы, как и многие другие, считаете инструменты командной строки несколько пугающими, чувствуете себя скорее дизайнером, чем программистом, или просто еще не имели времени поэкспериментировать с ними, это руководство создано для вас.

Что такое Unity CLI?

Одно из главных преимуществ редактора Unity — это GUI пользователя (GUI), который упрощает визуальное управление сложными проектами. Проверка готового объекта, настройка параметров материала, запуск тестов, запекание освещения или поиск ошибок в консоли — все это можно сделать всего несколькими щелчками мыши в редакторе. Этот рабочий процесс служил пользователям почти два десятилетия, но стал узким местом для повторяющихся задач, автоматизации и рабочих процессов, управляемых искусственным интеллектом (агентными процессами). Агент ИИ может обрабатывать клики и интерфейсы, состоящие только из визуальных элементов, но это требует дополнительного, неродного для него уровня визуальной интерпретации, что замедляет процесс и создает ненужные накладные расходы, которые быстро расходуют токены.

Здесь на помощь приходят новый интерфейс командной строки Unity CLI и экспериментальный пакет Unity Pipeline.

Unity CLI, как следует из названия, — это интерфейс командной строки для управления Unity. Благодаря отсутствию графического пользовательского интерфейса, он исключительно хорошо подходит для автоматизации и рабочих процессов с участием агентов. Это самодостаточный исполняемый файл (приложение), содержащий все необходимое для запуска, управления и взаимодействия с Unity. Иными словами, вы можете запускать команды из терминала, которые напрямую взаимодействуют с Unity, заменяя слой щелчков мыши и целые рабочие процессы в Hub или Editor.

Примечание. Новые функции и улучшения добавляются регулярно. На момент написания статьи наиболее актуальной конфигурацией является версия Unity CLI 1.0.0-beta.6 в сочетании с пакетом 0.5.0-exp.1 com.unity.pipeline и Unity 6000.6.0b9. Если у вас возникнут проблемы, ознакомьтесь с документацией Unity CLI: https://docs.unity.com/en-us/unity-cli/use-unity-cli

Как Unity CLI и пакет Pipeline взаимодействуют друг с другом.

Хотя автономный исполняемый файл Unity CLI управляет настройкой вашей среды (например, установкой редакторов, модулей и управлением лицензиями), настоящая ценность проявляется при его использовании в паре с пакетом Unity Pipeline ( com.unity.pipeline ).

Этот пакет Unity Pipeline, по сути, превращает работающий редактор в локальный HTTP-сервер. Поскольку редактор работает в фоновом режиме, загруженные сцены и база данных ресурсов остаются «в рабочем состоянии» в системной памяти. Благодаря предварительной загрузке всех необходимых компонентов, вы полностью избегаете досадных затрат на запуск двигателя в холодном состоянии. Теперь ваш терминал (или агент ИИ) может мгновенно управлять редактором для запуска тестов, загрузки сцен или изменения GameObjects.

Система также решает печально известную проблему «узкого места» перезагрузки домена. До появления пакета Pipeline, при внесении вами или вашим ИИ-агентом прямых изменений в скрипт C# на диске, вам приходилось ждать, пока Unity пересоберет проект и перезагрузит домен. Для выполнения некоторых действий вам даже потребуется сфокусироваться на чем-либо или щелкнуть мышью в редакторе, прежде чем они смогут продолжиться.

Однако локальный сервер пакета Pipeline обрабатывает этот процесс компиляции полностью асинхронно. Соединение остается стабильным и активным на протяжении всей компиляции, гарантируя, что ваша терминальная сессия никогда не прервется и не закончится по истечении времени ожидания, пока редактор перезагружается в фоновом режиме.

Скорость работы значительно повышается при динамическом выполнении кода с помощью команды `eval` . В данном случае пакет Pipeline в редакторе действует как мгновенный транслятор, компилируя ваш фрагмент кода на C# на лету и напрямую внедряя его в основной поток Unity. Поскольку это динамическое выполнение полностью автономно, оно полностью обходит процесс перекомпиляции и перезагрузки домена в масштабах всего проекта. Вы полностью избегаете утомительного ожидания и получаете результаты за миллисекунды.

Это означает, что ваши ресурсоемкие скрипты автоматизации не будут зависать или терять соединение только потому, что в фоновом режиме происходит масштабная компиляция проекта, а ваши быстрые команды в терминале будут выполняться практически без задержек. Вы получаете стабильность и скорость в одном и том же инструменте.

Переход с MCP на Unity CLI

Возможно, вас интересует вопрос: «А что насчёт официального сервера Unity Model Context Protocol (MCP)?» Почему бы мне просто не использовать это или не придерживаться этого?

Коротко говоря, мы не прекращаем поддержку MCP. Однако Unity CLI и пакет Pipeline справляются со всеми теми же задачами, что и MCP, и даже больше, но делают это гораздо лучше и быстрее.

Более развернутый ответ сводится к архитектуре. В традиционных конфигурациях MCP требуется активный клиентский модуль (например, Claude Desktop или Cursor), который будет выступать в качестве переводчика между вашим ИИ-агентом и Unity. Однако современные агенты, изначально предназначенные для работы в терминале, такие как Claude Code, уже невероятно хорошо справляются с непосредственным выполнением стандартных команд оболочки. Используя прямые команды командной строки, такие как unity command или unity eval , вы полностью обходите стороной накладные расходы на настройку и обслуживание сервера MCP. Ваш агент может напрямую взаимодействовать с Unity через единый, сверхбыстрый локальный HTTP-сервер. Это означает, что вы будете писать более чистые конфигурации, тратить меньше времени на отладку сокетов подключения и сможете позволить своему ИИ работать с той же скоростью, что и нативный терминал.

Кроме того, устаревший сервер MCP работал непосредственно внутри процесса редактора в виде пакета C#. Это означало, что сам соединительный мост был привязан к основному потоку Unity и его памяти. В тот момент, когда вы компилировали код или запускали перезагрузку домена, Unity очищала свою память, что часто приводило к разрыву соединения, возникновению исключений null или зависанию агента в середине цикла.

Текущий пакет com.unity.pipeline также является пакетом C#, работающим внутри редактора, но он предоставляет HTTP-сервер и REST API (а не мост сокетов), поэтому он более устойчив к перезагрузке домена. Благодаря асинхронной обработке команд этим локальным сервером, ваше терминальное соединение остается полностью стабильным и активным даже во время ресурсоемких компиляций и перезагрузки домена.

В итоге, переход на Unity CLI позволяет полностью избежать разрывов соединений и потери токенов. Наконец, интерфейс командной строки также предлагает режим MCP, если у вас есть конкретный сценарий использования, для которого вы хотите использовать MCP.

Установка пакетов CLI и Pipeline.

В последних версиях установка пакетов CLI и Pipeline выполняется автоматически с помощью Unity Hub . На момент написания этой статьи существует несколько способов установки Unity CLI, поэтому обязательно обратитесь к документации , чтобы получить самую актуальную информацию.

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

Для установки Unity CLI достаточно выполнить следующие команды в терминале (в зависимости от используемой платформы):

# macOS или Linux

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

# Windows

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

Следующий шаг — установка пакета Unity Pipeline:

установка конвейера Unity

После установки обеих программ вы можете проверить, работают ли они.

Проверка установленных систем

Для подтверждения установки просто выполните следующую команду:

статус единства

В результате должно получиться что-то подобное:

Редактор Unity (порт 7800): readyProject: /Users/thomaskr/Github/UnityProjects/MyAwesomeProjectVersion: 6000.6.0b7PID: 85009

Если рядом с первой строкой отображается статус «готово» , это означает, что редактор активен и доступен. Также подтверждается, на каком порту работает редактор, путь к проекту, версия редактора и идентификатор процесса (PID).

Далее, чтобы убедиться в аутентификации вашего доступа, выполните следующую команду:

вход через Unity Auth

Это откроет ваш браузер для входа в учетную запись Unity через OAuth. После аутентификации CLI сохраняет ваши учетные данные в системном хранилище ключей, поэтому будущие команды, требующие аутентификации (например, список проектов Unity, сборка Unity, лицензия Unity, облако Unity ), будут выполняться автоматически без повторного запроса.

Выполнение нескольких основных команд

После установки пакетов CLI и Pipeline пришло время попробовать выполнить еще несколько команд. Начнём с команды ` unity --help` , которая даёт краткий обзор всех доступных функций.

единство --помощь

Команда `unity --help` выводит список всех основных доступных команд с обзором и доступными параметрами для каждой из них.

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

Давайте воспользуемся командой, которую мы только что использовали в качестве примера, но на этот раз с опцией:

unity auth login --non-interactive

Слева направо:

• Команда `unity` активирует интерфейс командной строки Unity и, следовательно, является основной командой.
• Подкоманды `auth login` и `login` являются подкомандами. Их можно рассматривать как глаголы, которые точно указывают основной программе, какое действие следует предпринять. Здесь команда `auth` направляет интерфейс командной строки к системе аутентификации, а команда `login` указывает ей выполнить вход в систему.
• --non-interactive — это опция. Представьте, что опционы похожи на параметры. Это модификаторы, которые указывают команде, как она должна себя вести. В этом случае это указывает интерфейсу командной строки выполнить вход напрямую через терминал, а не открывать окно браузера. В контексте опций «включено/выключено» опции иногда также называют «флагами».

Также существует однобуквенная комбинация клавиш, предназначенная для быстрого набора текста в вашей повседневной работе с терминалом.

Возвращаясь к опции справки ( --help ), вместо запуска команды unity --help вы можете просто использовать unity -h , и обе команды дадут вам один и тот же ответ.

единство --помощь # Длинная версия с флагом (улучшенная читаемость) unity -h # Короткая версия с флагом (более быстрая в повседневной работе)

В коротких заголовках используется одинарный дефис (-) и они предназначены для сокращения, тогда как в длинных заголовках используется двойной дефис (--) и представляют собой эквивалентные полные описания, предназначенные для удобства чтения.

Команда `--help` — это важнейший инструмент в вашем арсенале; вы можете добавить её буквально к любому уровню вложенной команды, чтобы быстро получить документацию. Вот несколько примеров команды аутентификации, которую мы только что рассмотрели:

# Справка по командам аутентификации

unity auth --help

# Справка по команде входа в систему

unity auth login --help

На каждом экране справки мгновенно отобразится точное описание того, что делает команда, какие параметры доступны и какие аргументы она ожидает. Если сомневаетесь, просто спросите у самого командования!

Давайте в качестве еще одного примера попробуем команды releases :

Unity выпускает

Это дает мне хороший обзор всех версий Unity , доступных на момент написания статьи.

Теперь добавим опцию --help :

unity releases --help

Команда ` unity releases --help` предоставляет объяснение всех различных параметров, которые можно добавить для сужения поиска версий Unity .

Например, на момент написания этой статьи мы используем бета-версию Unity 6.6b7 и хотим установить последнюю бета-версию. Мы можем использовать базовую команду `unity install` , которая предоставит нам простой визуальный интерфейс, где мы сможем выбрать нужную нам версию.

установка Unity

Давайте выберем версию b9, которая запустит установщик в фоновом режиме (и на его завершение потребуется несколько минут).

Вместо использования мастера установки вы также можете просто воспользоваться командой --help , чтобы получить обзор всех команд:

unity install --help

В результате вы получаете обзор, который выглядит примерно так:

Из списка видно, что вы можете передать в качестве аргумента версию Unity , которую хотите установить. Это означает, что если бы вам нужно было установить конкретную версию, вы могли бы сделать это одной командой, используя:

Просто замените версию на ту, которую вы хотите использовать.

unity install 6000.5.9f1

Тем временем, новая версия нашего редактора уже установлена, поэтому теперь нам нужно обновить проект. Для этого укажите конкретную версию, в которой вы хотите открыть проект. Это будет то же самое, что если бы вы зашли в Центр и выбрали другую версию редактора для открытия проекта, чтобы запустить обновление проекта.

unity open --version 6000.6.0b9

Как мы уже упоминали ранее, пакет Pipeline открывает огромный набор инструментов, содержащий практически все, что можно сделать в редакторе Unity (и по мере развития бета-версии постоянно добавляются новые команды).

Чтобы посмотреть, какие команды доступны в вашем текущем проекте, выполните следующую команду:

список единства

Эта команда выводит таблицу высокого уровня, в которой отображается имя, группа и краткое описание каждой команды. Это отлично подходит в качестве отправной точки для быстрого просмотра сотен встроенных команд, таких как eval , add_animator_layer , build и find_assets .

Когда вам нужно точно знать, как отформатировать введенные данные. Вы можете запустить:

команда единства

Запуск этой команды без аргументов предоставляет подробный «шаблон» команд Unity с документацией для каждой зарегистрированной команды, включая параметры (точные флаги и типы данных, которые ожидает команда).

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

В заключение рассмотрим команду eval и как запустить простой тест Debug.Log ( «Hello World» ) в консоли Unity . eval — это команда пакета Pipeline (и, пожалуй, самая интересная из более чем 140 встроенных команд), которая динамически компилирует и выполняет код C# в процессе работы редактора. Попробуйте выполнить следующую команду:

Команда unity eval --code 'Debug.Log("hello from unity cli");'

В результате вы получите следующий JSON-объект с параметром "success": true, если операция прошла успешно.

Теперь в редакторе вы можете убедиться, что все сработало, в окне консоли .

Давайте разберем эту команду:

Команда unity eval --code 'Debug.Log("hello from unity cli");'

Читать слева направо:

1. Unity запускает инструмент командной строки Unity .
2. Команда `command` — это подкоманда, которая дает указание «обратиться к подключенному редактору».
3. Команда `eval` является подкомандой, которая выводит команду `eval`, `eval`, `run ...
4. --code — это опция (или флаг), указывающая на необходимость выполнения кода.
5. 'Debug.Log("hello from unity cli");' — это значение параметра --code ; фактический код для выполнения.

Связь с программой магистра права (LLM)

Освоение нескольких основных команд может ускорить некоторые процессы обслуживания ваших установок Unity , но настоящий эффект проявляется, когда вы начинаете автоматизировать и интегрировать рабочие процессы ваших агентов.

С помощью Unity CLI и пакета Pipeline вы можете подключить выбранного вами агента. Это означает, что независимо от того, используете ли вы Claude, Codex, Copilot или локальные модели и т. д., интерфейс командной строки разработан для интеграции с вашей существующей, предпочтительной конфигурацией и должен подключаться без необходимости какой-либо дополнительной настройки.

Просто откройте терминал, перейдите (используя команду cd) непосредственно в каталог вашего проекта Unity и запустите агента, введя «claude» (или команду вашего агента). Вы можете подтвердить соединение, просто задав агенту примерно следующий вопрос:

Запустите команду `unity command` в оболочке bash и скажите, что она умеет, а затем протестируйте простую команду `eval`.

Подключение LLM с помощью MCP

В Unity отказались от использования встроенного в редактор MCP-сервера из пакета com.unity.ai.assistant . Его заменил встроенный в Unity CLI сервер MCP ( unity mcp ), работающий на основе пакета Unity Pipeline. Используется тот же протокол, поэтому клиенты подключаются без проблем. Режим MCP по-прежнему полностью поддерживается для агентов, которые не могут выполнять произвольные команды оболочки или испытывают трудности с составлением командной строки.

Для использования MCP выполните следующую команду:

юнит mcp конфигурировать

Эта команда автоматически внедряет конфигурацию непосредственно в настройки вашего агента. Чтобы проверить подключение LLM, выполните небольшой тест, попросив инструмент LLM запустить что-то подобное следующему:

Я хочу, чтобы вы создали куб размером 2 × 2 × 2 в центре открытой мной сцены. Затем создайте скрипт, который заставит его непрерывно вращаться вокруг всех трех осей со скоростью 45 градусов в секунду.

Вот что ответил Клод Код:

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

Расширьте функционал, добавив собственные пользовательские команды.

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

Создать собственную команду очень просто. Всё, что вам нужно сделать, это написать стандартный статический метод на C# и добавить к нему атрибуты [CliCommand] и [CliArg] .

Пакет Pipeline автоматически обнаруживает эти атрибуты во время компиляции, а это значит, что он не требует ручной настройки или регистрации файлов. При запуске команды unity без аргументов интерфейс командной строки динамически отображает все доступные пользовательские команды наряду со встроенными.

Примечание. Атрибут [CliCommand] позволяет обнаруживать и вызывать команды через интерфейс командной строки. Для параметризованного выполнения метод вызывается напрямую с помощью команды Unity `eval` с синтаксисом C#, а не путем передачи флагов в стиле командной строки.

Давайте посмотрим, как работает простая пользовательская команда "Hello World".

Создайте новый скрипт на C# с именем HelloWorldCommand.cs . Убедитесь, что класс и метод являются статическими и включают пространство имен Unity.Pipeline.Commands :

с использованием UnityEngine;

using Unity.Pipeline.Commands;

public static class HelloWorldCommand

{

[CliCommand("hello-world", "Простая команда "hello world")]

public static void SayHello()

{

Debug.Log("Hello, World!") Это пользовательская команда командной строки.

}

}

Чтобы выполнить новую команду, откройте терминал и выполните следующую команду:

команда unity hello-world

В терминале должно отображаться примерно следующее:

В консоли должно получиться примерно следующее:

Вы также можете расширить эту функцию, если вам необходимо передавать параметры с помощью атрибута [CliArg] .

с использованием UnityEngine;

using Unity.Pipeline.Commands;

public static class HelloWorldCommand

{

[CliCommand("hello-world", "Простая команда "hello world")]

public static void SayHello(

[CliArg("name", "Кого приветствовать")] string name)

{

Debug.Log($"Привет, {имя}!") Это пользовательская команда командной строки.

}

}

Чтобы выполнить новую команду, откройте терминал и выполните:

Команда Unity hello-world --name "thomas"

Установка плагина Unity Agent

Unity также предлагает официальный плагин для разработки игр , который на момент написания статьи доступен для Claude Code, Codex и Grok. Он предоставляет тщательно отобранные навыки для разработки игр и оптимизации производительности. После установки навыки автоматически загружаются при работе над проектом Unity в любом из вышеперечисленных приложений. Чтобы установить его для Клода, просто выполните эту команду:

claude plugin marketplace add Unity-Technologies/unity-agent-plugin

github.com/Unity-Technologies/unity-agent-plugin

Еще один полезный совет для пользователей Claude Code, начинающих новый проект: запустите этап инициализации, который настраивает Claude, предоставляя базовую информацию о вашем проекте путем создания файла claude.md . Это файл Markdown, который находится в корневой папке вашего проекта и который Claude Code считывает в начале каждой сессии.

/init # Выполните эту команду внутри кода Клода

Таким образом, вы сможете использовать это, чтобы сообщить Клоду о предпочитаемом вами технологическом стеке, например, что вы предпочитаете uGUI вместо UI Toolkit в качестве пользовательского интерфейса, новую Input System вместо старого менеджера ввода и т. д. Его также можно использовать для принятия архитектурных решений, например, для применения шаблона Service Locator вместо синглтонов, для создания MVP (минимально жизнеспособного продукта) для дизайна пользовательского интерфейса и т. д.

Хотя Claude также автоматически формирует память в процессе работы, сохраняя полученные знания между сессиями без необходимости что-либо записывать с вашей стороны, файл Claude.md помогает определить общее направление конкретного проекта.

По мере продвижения по процессу вы можете добавить дополнительные пользовательские инструкции, например, руководство по стилю оформления кода. Я написал статью о том, как это работает для пользовательских инструкций в ИИ-помощнике, но принципы точно такие же и для Claude Code, если вам интересно узнать больше.

Что дальше?

Надеемся, это было полезное введение, которое поможет вам начать работу. Если вас интересует дальнейшая оптимизация рабочего процесса агента, ознакомьтесь со статьей о настройке пользовательских инструкций для вашего LLM, включая определение руководства по стилю кода Unity C# .

Посмотрите видео здесь:

Интерфейс командной строки Unity (CLI)