← Руководство

Управление плагинами

Управляемые плагины — это сборки .NET, которые создаются и компилируются вне Unity в динамически связанную библиотеку (DLL) с помощью таких инструментов, как Visual Studio.

Этот процесс отличается от стандартных скриптов C#, которые Unity хранит в качестве исходных файлов в папке Assets в вашем проекте Unity. Unity компилирует стандартные скрипты C# всякий раз, когда они изменяются, в то время как DLLs предкомпилированы и не изменяются. Вы можете добавить компилированный файл .dll в свой проект и прикрепить содержащиеся в нем классы к GameObjects так же, как и стандартные скрипты.

Дополнительные сведения об управляемом коде в C# см. в документации Microsoft Что такое управляемый код?.

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

Когда вы работаете с DLLs в Unity, вам нужно выполнить больше шагов, чем когда вы работаете со скриптами. Однако есть ситуации, когда вам может быть полезно создать и добавить файл .dll в проект Unity, например:

Вы хотите использовать в своем коде компиляторы, которые Unity не поддерживает.
Вы хотите добавить сторонний код .NET в файл .dll.
Вы хотите предоставить код Unity без исходного текста.

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

Создание управляемого модуля

Чтобы создать управляемый плагин, вам нужно создать DLL. Для этого вам нужен подходящий компилятор, например:

визуальная студия
MsBuild
.NET SDK

Не все компиляторы, которые производят код .NET, совместимы с Unity, поэтому вам следует проверить компилятор с некоторым доступным кодом, прежде чем делать с ним какую-либо значительную работу. Для информации о профилях .NET, которые в настоящее время поддерживает Unity, см. Поддержка профилей .NET.

Метод создания DLL зависит от того, содержит ли DLL код Unity или API:

Если DLL содержит код Unity API, перед компиляцией необходимо предоставить компилятору доступ к собственным DLL-библиотекам Unity:
1. Чтобы найти Unity DLLs:
  - На Windows, перейти к: C:\Program Files\Unity\Hub\Editor\<version-number>\Editor\Data\Managed\UnityEngine
  - На macOS:
    1. Найдите файл Unity.app на вашем компьютере. Путь к файлу Unity DLLs на macOS: /Applications/Unity/Hub/Editor/<version-number>/Unity.app/Contents/Managed/UnityEngine
    2. Правый щелчок на Unity.app
    3. Выберите Показать содержимое пакета.
2. Папка UnityEngine содержит файлы .dll для ряда модулей. Ссылайтесь на них, чтобы сделать их доступными для вашего скрипта. Некоторые пространства имен также требуют ссылки на скомпилированную библиотеку из проекта Unity (например, UnityEngine.UI). Найдите это в каталоге папки проекта: ~\Library\ScriptAssemblies
Если DLL не содержит Unity API код, или если вы уже сделали Unity DLLs доступным, следуйте документации компилятора для компиляции .dll file.The параметров, которые используются для компиляции DLL в зависимости от используемого компилятора. Например, командная строка для компилятора Roslyn, csc, может выглядеть так на macOS:

csc /r:/Applications/Unity/Hub/Editor/<version-number>/Unity.app/Contents/Managed/UnityEngine.dll /target:library /out:MyManagedAssembly.dll /recurse:*.cs

В этом примере:

Используйте параметр /r для указания пути к библиотеке, которая будет включена в сборку, в данном случае это библиотека UnityEngine.
Используйте параметр /target, чтобы указать тип требуемой сборки; «library» означает сборку DLL.
Используйте /out для указания имени библиотеки, которое в данном случае будет «MyManagedAssembly.dll».
Добавьте имена исходных файлов для включения. Используйте метод /recurse для добавления всех файлов, заканчивающихся на “.cs” в вашем текущем рабочем каталоге и любых подкаталогах. Полученный файл .dll появляется в той же папке, что и исходные файлы.

Использование управляемого модуля

После компиляции файла DLL вы можете перетащить файл .dll в проект Unity, как и любой другой ресурс. Затем вы можете:

Разверните управляемый модуль, чтобы просмотреть отдельные классы в библиотеке.
Перетащите классы, полученные из MonoBehaviour на Game Объекты.
Используйте неMonoBehaviour классы непосредственно из других скриптов.

Создание DLL с Visual Studio

В этом разделе поясняется:

Как построить и интегрировать простой пример DLL с Visual Studio
Как подготовить сессию отладки для DLL в Unity.

Настройка Project

Откройте Visual Studio и создайте новый проект.
Выберите Файл > Новый > Project > Визуальный C# > .Net Стандартный > Библиотека классов (.NET Стандартный).
Добавьте в новую библиотеку следующую информацию:
- Имя: Пространство имен (для этого примера используйте DLLTest в качестве имени).
- Местоположение: Родительная папка проекта.
- Имя решения: Папка проекта.
Сделайте Unity DLLs доступными для вашего скрипта. В Visual Studio откройте контекстное меню Ссылки в Обзоре решений и выберите Добавить ссылку > Просмотр > Выбрать файл.
Выберите необходимый файл .dll, расположенный в папке UnityEngine.

Кодирование DLL

В этом примере переименуйте класс по умолчанию в MyUtilities в браузере решений.
Заменить его код следующим:

using System;   
using UnityEngine;

namespace DLLTest {

    public class MyUtilities {
    
        public int c;

        public void AddValues(int a, int b) {
            c = a + b;  
        }
    
        public static int GenerateRandom(int min, int max) {
            System.Random rand = new System.Random();
            return rand.Next(min, max);
        }
    }
}

Создайте проект для создания файла DLL вместе с его символами отладки.

Отладка DLL в Unity

Чтобы настроить сеанс отладки для DLL в Unity:

Создайте новый проект в Unity и скопируйте файл .dll (например, <project folder>/bin/Debug/DLLTest.dll) в папку Assets.
Создайте скрипт C# под названием Test в папке Assets.
Замените его содержимое скриптом, который создаёт новый экземпляр класса, объявленного в вашей DLL, использует его функции и выводит результат в Консоль Например, чтобы создать тестовый скрипт для DLL из раздела выше, скопируйте следующий код:

using UnityEngine;
using System.Collections;
using DLLTest;

public class Test : MonoBehaviour {

     void Start () {
        MyUtilities utils = new MyUtilities();
        utils.AddValues(2, 3);
        print("2 + 3 = " + utils.c);
     }
    
     void Update () {
        print(MyUtilities.GenerateRandom(0, 100));
     }
}

Присоедините этот скрипт к GameObject в Scene и нажмите кнопку Play.

Unity отображает вывод кода из DLL в окне Консоли

Компиляция небезопасного C# кода

Небезопасный C# код — это код, который может получать доступ к памяти напрямую. Он не включается по умолчанию, потому что компилятор не может проверить, что он не введет риски безопасности.

Небезопасный код может быть использован для:

Доступ к памяти с помощью указателей.
Выделение необработанной памяти.
Вызов методов с помощью указателей.

Чтобы включить поддержку компиляции небезопасного C# кода, перейдите в Изменить > Project Настройки > Проигрыватель > Другие настройки и включите Разрешить небезопасный код.

Более подробную информацию см. Документация Microsoft о небезопасном коде.