Поделиться через

Руководство программиста по облачным сценариям

  • Статья

В этом руководстве описывается, как использовать API облачной скриптов Сетки и средства разработчика для создания сред (они начинаются как проекты в Unity и затем передаются в коллекцию сетки). Рекомендуется сначала ознакомиться с инфраструктурой настройки облачных сценариев в Azure , чтобы ознакомиться с понятиями и базовой архитектурой Облачной скриптов Сетки.

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

Базовая структура DOM

Структура DOM отражает структуру сцены Unity. Член "Сцена" приложения соответствует объекту игры, к которому подключен компонент Cloud Scripting Сетки. Следующие классы API Cloud Scripting Mesh сопоставляют один к одному с объектами Unity, созданными в редакторе:

  • GameObject (и компонент преобразования) —> TransformNode
  • Компонент light —> PointLightNode, SpotLightNode, DirectionalLightNode
  • Компонент Animator —> AnimationNode (и производные классы см. ниже)
  • Компонент Box Collider —> BoxGeometryNode
  • Компонент Collider Sphere —> SphereGeometryNode
  • Компонент Collider капсулы —> КапсулаGeometryNode
  • Компонент Collider Сетки —> MeshGeometryNode
  • Компонент Text Mesh Pro —> TextNode
  • Компонент жесткого элемента —> HdBodyNode

Например, если вы создаете сцену с игровым объектом с компонентом Light (устанавливается на точку света) и подключенным к нему коллайдером сферы, сцена будет содержать ПреобразованиеNode с двумя дочерними объектами: PointLightNode и SphereGeometryNode.

Кроме того, некоторые объекты API Сценариев в сетке не имеют соответствующих встроенных компонентов Unity. Это дополнительные компоненты, которые можно создать в Unity, которые являются частью пакета набора средств Сетки.

  • Компонент облачной скриптов Сетки (описано выше)
  • Компонент WebSlate

Сопоставление Unity DOM с сеткой DOM

Вы можете создать сцену с компонентами, о которым не знает API облачной скриптов Сетки. Они просто не будут существовать в DOM облачной скриптов Сетки для сцены. Однако полная структура сцены GameObjects будет зеркально отображаться в API DOM как TransformNodes.

Unity имеет форму API GameObject/component; Однако модель DOM в облаке Сетки имеет одну структуру дерева. ПреобразованиеNode в API облачных сценариев Сетки имеет дочерние элементы, которые могут быть другими преобразованиями Или могут быть другими узлами, которые сопоставляются с компонентами. Мы можем рассмотреть этот объединенный список компонентов связанного игрового объекта и дочерних элементов его компонента преобразования.

Прямоугольное преобразование

Если добавить компонент, использующий RectTransform (например, компонент Text Mesh Pro), объект игры не будет отображаться как узел в графе сцены сценариев сетки. Вы по-прежнему можете перемещать, включать и отключать такой компонент, но для этого необходимо упаковать объект игры с помощью RectTransform в другой игровой объект с помощью обычного компонента преобразования.

События изменения свойств

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

Вы также можете подписаться на все события, подписавшись на DomObjectPropertyChanged событие. Это вызывается при изменении любого свойства в DOM.

Жизненный цикл объектов

Узлы, созданные при создании, не имеют значения. Это означает, что они не будут видимы в сцене, пока они явно не будут добавлены в качестве ребенка на сцену или одного из его потомков. Аналогичным образом, если родительский узел имеет значение NULL, он удаляется и его потомки из сцены.

Иногда вы хотите временно отключить узел, но не сохранять запись о том, где он был в сцене. По этой причине каждый узел имеет флаг "активный". Если задано значение false, он отключит узел и его потомки.

Вы можете создавать игровые объекты и компоненты в Unity, которые являются частью сцены, но отключены. Они будут отображаться как узлы в иерархии сцены облачной скриптов Сетки, но будут иметь их активный флаг, равный false. При задании активного флага значение true они будут включаться в сцене Unity.

Клонирование и повторное клонирование

Узлы можно клонировать и повторно использовать в API облачных сценариев Сетки; соответствующая сцена Unity будет обновляться соответствующим образом. Если клонировать узел, он клонирует этот узел и все его дочерние элементы (включая дочерние элементы, которые могут находиться в соответствующих объектах Unity, но не отображаются в Cloud Scripting сетки).

Клонировать или повторно клонировать узлы, соответствующие компонентам Unity. Это реализуется путем повторного создания этих компонентов Unity на основе представлений узлов облачной скриптов сетки. Можно клонировать или повторно клонировать только узлы, которые можно создать с помощью API облачной скриптов Сетки. Если вы создали компонент в Unity и задали поля, которые не отражаются в соответствующем узле Cloud Scripting Mesh, эти поля будут сброшены по умолчанию, если сам узел клонирован. По этой причине рекомендуется клонировать или повторно преобразовывать узлы преобразования, в которых вы управляете объектами, созданными в Unity. Они всегда будут правильно хранить все исходные параметры Unity.

Пользователи

В API есть различные места, которые предоставляют свойства пользователя. Это User.Identifier свойство является строкой постоянного идентификатора, которая является постоянной для пользователя, даже если пользователь покидает и выполняет повторное взаимодействие. Отображаемое имя пользователя также доступно через User.DisplayName. Идентификатор события, из которому подключен пользователь, доступен через User.ConnectedEventId.

Во время разработки отображаемое имя пользователя, идентификатор и идентификатор события можно использовать в редакторе компонентов cloud Scripting сетки в разделе "Параметры разработчика", как показано ниже.

Макет свойств пользователя

Аватары

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

Диалоговые окна сведений

В Сетке Cloud Scripting можно открыть диалоговое окно пространства экрана в приложении Microsoft Mesh с пользовательским сообщением. SceneNode содержит функцию для этого. ShowMessageToParticipants(string message, IReadOnlyCollection<Participant> participants) Теги форматированного текста можно использовать в сообщении для управления свойствами текста (цветом, полужирным шрифтом и т. д.).

Диалоговые окна ввода

Облачная скриптация Сетки может запрашивать текстовые данные от участника в событии Сетки с пользовательским сообщением. CloudApplication предоставляет метод Task<string> ShowInputDialogToParticipantAsync(string message, Participant participant, CancellationToken token). Теги форматированного текста можно использовать в сообщении для управления свойствами текста (например, цветом или полужирным шрифтом).

Классы

CloudApplication

Интерфейс ICloudApplication является отправной точкой для разработки приложений Сетки. Он доступен в App.cs в качестве переменной _app. Помимо сцены, ICloudApplication имеет функции для всех доступных типов. Он также имеет ряд других методов, но они используются для внутреннего использования.

Элемент "ВзаимодействиеableNode"

MeshInteractableSetup — это пользовательский компонент Unity, который входит в пакет набора средств Сетки. При присоединении его к игровому объекту в Unity он вызывает события щелчка, когда любой пользователь щелкает любой из активных параметров взаимодействия в этом игровом объекте или его дочерних объектах.

Ниже показан простой пример, в котором компонент MeshInteractableSetup добавляется в тот же игровой объект, что и коллидер поля:

Простой пример ввода

WebSlateNode

WebSlate — это пользовательский компонент Unity, который входит в пакет набора средств Сетки. Чтобы добавить префаб WebSlate в сцену, выберите GameObject>Mesh Toolkit>WebSlate в строке меню. Веб-сайт, назначенный свойству URL-адреса экземпляра WebSlate, отображается на четырехугольнике этого префаба.

Ниже показан пример, где в сцену был добавлен префаб WebSlate и назначен URL-адрес:

        var webSlateNode = Root.FindFirstChild<WebSlateNode>(true);
        webSlateNode.Url = new System.Uri("https://en.wikipedia.org/wiki/Color");

Пример WebSlate

Прослушивание щелчков

Ниже приведен простой скрипт Cloud Scripting сетки, который сменяет куб при каждом щелчке. Замените метод заглушки StartAsync внутри App.cs этого кода.

        private float _angle = 0;

        public Task StartAsync(CancellationToken token)
        {
            // First we find the TransformNode that corresponds to our Cube gameobject
            var transform = _app.Scene.FindFirstChild<TransformNode>();

            // Then we find the InteractableNode child of that TransformNode
            var sensor = transform.FindFirstChild<InteractableNode>();

            // Handle a button click
            sensor.Selected += (_, _) =>
            {
                // Update the angle on each click
                _angle += MathF.PI / 8;
                transform.Rotation = new Rotation { X = 1, Y = 0, Z = 0, Angle = _angle };
            };

            return Task.CompletedTask;
        }

Сведения о попадании

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

Аниматоры

Вы можете создать и добавить аниматор Unity в сцену и управлять им с помощью Сетки Cloud Scripting. Подключаемый модуль набора средств Сетки будет просматривать ресурсы в проекте Unity и для каждого найденного animator он создаст класс в папке AnimationScripts в проекте Облачной скриптов Сетки. Этот класс является производным от AnimationNode и может использоваться для управления аниматором из облачной скриптов Сетки. При добавлении Animator в качестве компонента в объект игры в Unity вы найдете соответствующий экземпляр созданного класса в качестве дочернего элемента соответствующего объекта TransformNode. С помощью API этого класса можно управлять аниматором.

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

  • Параметр состояния (для каждого слоя есть соответствующее свойство в классе, которое можно задать в перечислении на основе доступных состояний в Animator). Состояния устанавливаются немедленно, а не через переходы.
  • Параметр переменной float: предоставляются только переменные с плавающей запятой и только для привязки к "Время движения" в аниматоре.
  • Параметр скорости слоя

В состоянии можно создать клип анимации без ограничений на значения, которые можно задать в сцене Unity. Кроме того, поддерживаются циклионные клипы анимации. Следующие функции аниматоров не поддерживаются с помощью AnimationNodes:

  • Переходы: если вы добавляете переходы в animator, вы не сможете активировать их с помощью API сценариев Сетки (сервер не моделировает переходы).
  • Переменные (кроме с плавающей запятой для перемещения). Переменные, используемые для передачи логики перехода или умножения скорости, не поддерживаются.
  • Зеркальные состояния, смещение цикла и IK.

Поздние соединения и аниматоры

При присоединении клиентов к событию Сетки они синхронизируются с текущим состоянием и локальным временем всех запущенных узлов анимации. Если у вас есть длительное воспроизведение анимации в состоянии, время воспроизведения будет задано правильное текущее время анимации в конце соединения. Однако если ваше состояние запускает события, они не будут запущены в клиенте, присоединенном к нему. Некоторые другие сценарии могут не работать должным образом; Например, если вы активируете звук, включив AudioSource в начале состояния, то AudioSource по-прежнему будет включен в клиенте позднего соединения, но начнет воспроизводиться в начале звукового клипа.

Начальное состояние аниматора

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

Аниматор повторного и клонирования

АнимацияNodes не может быть создана с помощью API облачной скриптов Сетки. Единственным способом создания AnimationNode является экспорт сцены Unity, содержащей компонент Animator. При попытке клонировать или повторно выполнить анимацию AnimationNode вы получите сообщение об ошибке, так как это действие не поддерживается. Клонировать или повторно клонировать родительский элемент AnimationNode можно, так как это соответствует содержащей объект игры Unity, который может быть клонирован и родительским.

Заметки о созданном коде

Созданный код удаляет пробелы из имен аниматоров, слоев, состояний и переменных; Например, имя переменной "my var" становится "myVar" в коде. Из-за этого можно создать аниматоры, которые не будут создавать допустимый код. Например, если у вас есть две переменные с именем "my var" и "myVar", вы получите ошибку во время создания и сообщение с просьбой переименовать переменные.

LightNode

PointLightNode, DirectionalLightNode и SpotLightNode все сопоставляется с компонентом Unity Light (который будет иметь его тип, заданный соответствующим значением). Можно задать основные параметры этих световых интерфейсов через API LightNode. Кроме того, можно создать свет вручную с помощью API. Создание легких узлов через API оставляет параметры, которые не заданы через API облачных сценариев Сетки по умолчанию.

GeometryNode

BoxGeometryNode, SphereGeometryNode, CapsuleGeometryNode и MeshGeometryNode сопоставляют с компонентом Unity Box Collider, компонентОм Коллидера Sphere, компонентом Коллидера капсулы и компонентом Коллидера сетки соответственно. Их также можно создать с помощью API облачной скриптов Сетки. Включение и отключение узлов geometry будет добавлять и удалять их из кандидатов попаданий, если СеткаInteractableSetup присоединена к объекту игры или одному из его родителей.

Создание геометрических узлов с помощью API оставляет параметры, которые не заданы через API сетки по умолчанию (например, физический материал будет иметь значение none, и isTrigger будет иметь значение false).

ЖесткийBodyNode

Добавление компонента Жесткого тела в объект будет помещать его движение под контролем физики сетки. Без добавления кода объект Жесткого объекта будет вытащить вниз по тяжести и отреагировать на столкновения с другими объектами.

Примечание. GeometryNode.Friction Возвращается staticFriction. Однако если задано на стороне Сетки Cloud Scripting, он обновится как staticFriction на клиентах, так и dynamicFriction на клиентах.

Активация томов

Геометрические узлы могут выступать в качестве томов триггеров, если их IsTrigger свойство имеет значение true. Этот флаг соответствует IsTrigger свойству в коллайдере в Unity и не может быть изменен во время выполнения. Когда геометрия является триггером, он будет создавать Entered и Exited для всех аватаров, которые запуска и остановки перекрываются с ним.

Примечание. Объект Unity должен быть добавлен TriggerVolume в слой, чтобы позволить телепорту пропускать его, так как коллайдеры в Default слое блокируют луч телепорта.

TextNode

TextNode сопоставляется с компонентом TextMeshPro в Unity. При добавлении компонента TextMeshPro в сцену в иерархии сцены Сетки Cloud Scripting будет соответствующий TextNode. Это позволяет задать текст компонента во время выполнения. Вы также можете изменить основные свойства текста через API TextNode — полужирный, курсив, подчеркивание, зачеркнутый и цвет. В настоящее время невозможно создать TextNode через API; Их необходимо создать, добавив их в сцену в Unity. Кроме того, вы не можете клонировать текстовый объект напрямую, а клонировать родительский TranformNode textNode.

Сетки

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

Визуальные скрипты

Вы можете создать и добавить компьютер скрипта Unity в сцену и управлять им с помощью Cloud Scripting Сетки. Подключаемый модуль набора средств Сетки будет просматривать ресурсы в проекте Unity, а для каждого найденного компьютера скрипта он создаст класс в папке "VisualScripts" в проекте Облачной скриптов Сетки. Этот класс является производным от VisualScriptNode и может использоваться для управления переменными Unity, связанными с машиной скриптов из Сетки Cloud Scripting. При добавлении компьютера скрипта в качестве компонента в GameObject в Unity вы найдете соответствующий экземпляр созданного класса в качестве дочернего элемента соответствующего TransformNode. С помощью API этого класса можно управлять переменными компьютера скриптов.

Синхронизация состояния

По умолчанию Сетка автоматически реплицирует изменения сцены, выполненные визуальными скриптами на одном клиенте на всех остальных клиентах. Чтобы учесть изменения, внесенные с помощью визуального скрипта, необходимо выполнить следующие предварительные условия:

  • Компонент "Компьютер скрипта" находится в gameObject, который является потомком корневого элемента сцены облачной скриптов Сетки.
  • Параметр "Включить визуальный скрипт" компонента Cloud Scripting Сетки включен.

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

Начальное состояние

Рекомендуется, чтобы визуальные скрипты не изменяли или не опирались на общее состояние при запуске. Событие On Start обычно происходит перед подключением службы "Облачные скрипты сетки", поэтому синхронизация состояния в данный момент времени отсутствует, и поведение может не быть нужным.

Позднее присоединение

При присоединении клиентов к событию Сетки они синхронизируются с текущим состоянием всех узлов визуального скрипта. Любое событие изменения состояния, которое ранее было поднято на других клиентах, не будет поднято на клиенте с поздним присоединением. Некоторые другие сценарии могут не работать должным образом; Например, если вы активируете звук, включив AudioSource в ответ на событие "Изменение состояния", то AudioSource по-прежнему будет включен в клиенте позднего соединения, но начнет воспроизводиться в начале звукового клипа.

Повторное клонирование и клонирование

VisualScriptNode нельзя создать с помощью API облачной скриптов Сетки. Единственным способом создания VisualScriptNode является экспорт сцены Unity, содержащей компонент "Компьютер скрипта". Если вы попытаетесь клонировать или повторно использовать VisualScriptNode, вы получите сообщение об ошибке, так как это действие не поддерживается. Клонировать или повторно клонировать родительский элемент VisualScriptNode по-прежнему можно, так как это соответствует содержащей Unity GameObject, которую можно клонировать и родительскую.

Заметки о созданном коде

Созданный код удаляет пробелы из имен компьютеров скриптов и переменных; Например, имя переменной "my var" становится "MyVar" в коде. Из-за этого можно создать компьютеры скриптов, которые не будут создавать допустимый код. Например, если у вас есть две переменные с именем "my var" и "myVar", вы получите ошибку во время создания и сообщение с просьбой переименовать переменные.

Другие разделы по облачным скриптам Сетки

Добавление ресурсов в службу облачных сценариев Сетки

Если вам нужно добавить ресурс для службы сценариев Mesh Cloud, необходимо добавить его как внедренный ресурс в файл проекта C#. Это можно сделать с помощью пользовательского интерфейса проекта в Visual Studio или путем добавления следующей строки в CSPROJ-файл напрямую:

<EmbeddedResource Include="<my_resource_file>" CopyToOutputDirectory="PreserveNewest" />

Обратите внимание, что это способ упаковки scene.map, который можно просмотреть в CSPROJ-файле для справки.

Работа с физикой сетки

Mesh Physics будет заботиться о синхронизации движения жестких тел между клиентами. Облачные скрипты Сетки TransformNode.PositionTransformNode.Rotationи RigidBody.AngularVelocity RigidBody.Velocity не будут обновлены с последним состоянием имитации. Однако клиенты будут применять изменения, если они заданы в службе облачных сценариев Сетки. Обратите внимание, что изменение одного свойства не изменится. Например, если задано только положение, скорость не будет изменена, а жесткое тело будет продолжать движение со старой скоростью от новой позиции. Учитывая, что служба облачных сценариев Сетки не обновляется с последним состоянием движения для жестких тел, рекомендуется задать только для новых жестких тел.

Если TransformNode с RigidBodyNode клонирован, клонированное тело будет зарегистрировано и передано Mesh Physics для синхронизации между клиентами. Примечание. Клонированные жесткие тела будут иметь положение, поворот и скорости с начала сцены исходного жесткого тела. Если они должны отличаться, они должны быть заданы явным образом в Cloud Scripting сетки.

Следующие шаги

Инфраструктура и управление облачными скриптами