Compartir a través de

Guía del programador de Scripting en la nube

  • Artículo

En esta guía se describe cómo usar mesh Cloud Scripting API y las herramientas de desarrollo para compilar entornos (estos comienzan como proyectos en Unity y, a continuación, se cargan en una colección mesh). Le recomendamos que lea primero la sección Establecimiento de la infraestructura de scripting en la nube en Azure para familiarizarse con los conceptos y la arquitectura básica de Mesh Cloud Scripting.

En esta sección se describen las características y la interfaz de mesh Cloud Scripting API, que se usa para escribir los scripts que impulsan comportamientos en entornos.

Estructura DOM básica

La estructura DOM refleja la estructura de la escena de Unity. El miembro "Scene" de la aplicación corresponde al objeto de juego al que está asociado el componente Mesh Cloud Scripting. Las siguientes clases de Mesh Cloud Scripting API asignan uno a uno con objetos de Unity creados en el editor:

  • GameObject (componente de transformación de &):> TransformNode
  • Componente de luz:> PointLightNode, SpotLightNode, DirectionalLightNode
  • Componente de animador:> AnimationNode (y clases derivadas, consulte a continuación)
  • Componente colisionador de box:> BoxGeometryNode
  • Componente del colisionador de esfera:> SphereGeometryNode
  • Componente del colisionador de cápsulas -> CapsuleGeometryNode
  • Componente del colisionador de malla:> MeshGeometryNode
  • Componente Text Mesh Pro:> TextNode
  • Componente Rigidbody:> RigidBodyNode

Por ejemplo, si creas una escena con un objeto de juego que tiene un componente Light (establecido en una luz puntual) y un colisionador de esfera conectado, la escena contendrá un TransformNode con dos elementos secundarios: PointLightNode y SphereGeometryNode.

Además, algunos objetos mesh Cloud Scripting API no tienen los componentes integrados de Unity correspondientes. Estos son componentes adicionales que puede crear en Unity que forman parte del paquete del kit de herramientas de Mesh.

  • Componente Mesh Cloud Scripting (descrito anteriormente)
  • Componente WebSlate

Asignación del DOM de Unity al DOM de malla

Puede crear una escena con componentes que mesh Cloud Scripting API no conoce. Estos simplemente no existirán en mesh Cloud Scripting DOM para la escena. Sin embargo, la estructura de escena completa de GameObjects se reflejará en la API DOM como TransformNodes.

Unity tiene una forma de API GameObject/component; Sin embargo, Mesh Cloud Scripting DOM tiene una estructura de árbol único. TransformNode en mesh Cloud Scripting API tiene elementos secundarios que pueden ser otros TransformNodes o pueden ser otros nodos que se asignan a los componentes. Podemos considerar esta lista combinada de los componentes del objeto de juego asociado y los elementos secundarios de su componente de transformación.

Rect Transform

Si agregas un componente que usa rectTransform (por ejemplo, el componente Text Mesh Pro), el objeto de juego no aparecerá como un nodo en el gráfico de escena mesh Cloud Scripting. Todavía es posible mover, habilitar y deshabilitar este componente, pero para ello, es necesario encapsular el objeto de juego mediante RectTransform en otro objeto de juego mediante el componente De transformación normal.

Eventos de cambio de propiedades

Puede suscribirse a eventos de cambio de propiedad llamando a AddPropertyChangedEventHandler en cualquier nodo de la jerarquía. Debe pasar el nombre de la propiedad como una cadena.

También es posible suscribirse a todos los eventos mediante la suscripción al DomObjectPropertyChanged evento. Se llama a esto cuando cambia cualquier propiedad del DOM.

Ciclo de vida de los objetos

Los nodos, cuando se crean, no son primarios. Esto significa que no estarán visibles en la escena hasta que se agreguen explícitamente como elemento secundario a la escena o a uno de sus descendientes. Del mismo modo, si se establece el elemento primario de un nodo en NULL, se quitará y sus descendientes de la escena.

A veces quiere deshabilitar un nodo temporalmente, pero no mantener un registro de dónde estaba en la escena. Por este motivo, cada nodo tiene una marca "activa". Cuando se establece en false, deshabilitará el nodo y sus descendientes.

Puede crear objetos y componentes de juego en Unity que forman parte de la escena, pero están deshabilitados. Estos aparecerán como nodos en la jerarquía de la escena mesh Cloud Scripting, pero tendrán su marca activa establecida en false. Si se establece la marca activa en true, se habilitarán en la escena de Unity.

Clonación y reparentes

Los nodos se pueden clonar y reparentar en mesh Cloud Scripting API; la escena de Unity correspondiente se actualizará en consecuencia. Si clona un nodo, clonará ese nodo y todos sus elementos secundarios (incluidos los elementos secundarios que pueden estar en los objetos de Unity correspondientes, pero no son visibles para Mesh Cloud Scripting).

Es posible clonar o reparentar nodos que corresponden a componentes de Unity. Esto se implementa mediante la recreación de estos componentes de Unity en función de las representaciones del nodo Mesh Cloud Scripting. Solo los nodos que se pueden crear a través de Mesh Cloud Scripting API se pueden clonar o reparentar. Si ha creado un componente en Unity y ha establecido campos que no se reflejan en el nodo de scripting en la nube de malla correspondiente, estos campos se restablecerán a sus valores predeterminados si se clona el propio nodo. Por este motivo, se recomienda clonar o reparentar nodos de transformación en los que se manipulan objetos creados en Unity. Estos siempre mantendrán correctamente toda la configuración original de Unity.

Usuarios

Hay varios lugares en la API que proporcionan propiedades de usuario. La User.Identifier propiedad es una cadena de identificador persistente que es persistente para el usuario, incluso si el usuario deja y vuelve a unirse. El nombre para mostrar del usuario también es accesible a través User.DisplayNamede . El identificador de evento desde el que se ha conectado el usuario es accesible a través User.ConnectedEventIdde .

Durante el desarrollo, el nombre para mostrar del usuario, el identificador y el identificador de evento se pueden simular en el editor de componentes Mesh Cloud Scripting en la "Configuración del desarrollador", como se muestra a continuación.

Propiedades de usuario simuladas

Avatares

Avatares son la representación de los usuarios en la escena. Se pueden usar para teletransportar a los usuarios a una ubicación determinada, viajar entre escenas y detectar colisiones con volúmenes desencadenadores.

Cuadros de diálogo de información

Es posible que en Mesh Cloud Scripting aparezca un cuadro de diálogo de espacio de pantalla en la aplicación Microsoft Mesh con un mensaje personalizado. SceneNode contiene una función para esto, ShowMessageToParticipants(string message, IReadOnlyCollection<Participant> participants). Las etiquetas de texto enriquecido se pueden usar en el mensaje para controlar las propiedades de texto (color, negrita, etc.).

Cuadros de diálogo de entrada

Mesh Cloud Scripting puede solicitar una entrada de texto de un asistente en un evento Mesh con un mensaje personalizado. CloudApplication proporciona el método Task<string> ShowInputDialogToParticipantAsync(string message, Participant participant, CancellationToken token). Las etiquetas de texto enriquecido se pueden usar en el mensaje para controlar las propiedades de texto (por ejemplo, color o negrita).

Clases

CloudApplication

La ICloudApplication interfaz es el punto de partida para desarrollar aplicaciones mesh. Está disponible en "App.cs" como la variable _app. Además de la escena, ICloudApplication tiene funciones de creación para todos los tipos disponibles. También tiene una serie de otros métodos, pero son para uso interno.

InteractableNode

MeshInteractableSetup es un componente de Unity personalizado que forma parte del paquete del kit de herramientas de Mesh. Al adjuntarlo a un objeto de juego en Unity, generará eventos de clic cuando cualquier usuario haga clic en cualquiera de los collidables activos de ese objeto de juego o sus elementos secundarios.

A continuación se muestra un ejemplo sencillo, donde el componente MeshInteractableSetup se agrega al mismo objeto de juego que el colisionador de cuadros:

Ejemplo de entrada simple

WebSlateNode

WebSlate es un componente de Unity personalizado que forma parte del paquete del kit de herramientas de Mesh. Para agregar un objeto prefabricado WebSlate a la escena, seleccione GameObject>Mesh Toolkit>WebSlate en la barra de menús. El sitio web que se asigna a la propiedad URL de la instancia de WebSlate se representa en el quad de este objeto prefabricado.

A continuación se muestra un ejemplo, donde se ha agregado un objeto prefabricado WebSlate a la escena y se ha asignado una dirección URL:

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

Ejemplo de WebSlate

Escuchar clics

Este es un script sencillo de Scripting en la nube de Mesh que gira el cubo cada vez que se hace clic en él. Reemplace el método de código auxiliar StartAsync dentro App.cs por este código.

        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;
        }

Información de aciertos

Es posible averiguar qué usuario ha hecho clic en el colisionador examinando los argumentos del evento de cambio de propiedad. También puede leer el contacto normal y la posición del clic en los argumentos del evento. Estas coordenadas serán relativas al espacio de coordenadas local de InteractableNode.

Animadores

Puede crear y agregar un animador de Unity a la escena y controlarlo a través de Mesh Cloud Scripting. El complemento mesh toolkit buscará los recursos del proyecto de Unity y, para cada animador que se encuentre, generará una clase en una carpeta "AnimationScripts" en el proyecto Mesh Cloud Scripting. Esta clase deriva de AnimationNode y se puede usar para controlar el animador de Mesh Cloud Scripting. Cuando agregues el Animator como componente a un objeto de juego en Unity, encontrarás una instancia correspondiente de la clase generada como elemento secundario del transformNode correspondiente. Con la API de esta clase, puede controlar el Animator.

El modelo de programación Mesh Cloud Scripting es autoritativo del servidor y solo se admite un pequeño subconjunto de la funcionalidad animator. Esto se debe a que modelamos el animador en el servidor y esperamos que todos los clientes se sincronicen con precisión con el modelo de servidor. Por este motivo, actualmente solo se admite la SIGUIENTE API:

  • Configuración de estado (para cada capa hay una propiedad correspondiente en la clase que se puede establecer en una enumeración basada en los estados disponibles en el Animator). Los estados se establecen inmediatamente, no a través de transiciones.
  • Valor de variable float: solo se exponen variables float y solo para el propósito de enlazar a "Tiempo de movimiento" en un animador.
  • Configuración de velocidad de capa

Dentro de un estado, puede crear un clip de animación sin restricciones sobre los valores que puede establecer en la escena de Unity. También se admiten clips de animación de bucle. Las siguientes características de animadores no se admiten a través de AnimationNodes:

  • Transiciones: si agrega transiciones al animador, no podrá desencadenarlas a través de Mesh Cloud Scripting API (el servidor no modela las transiciones).
  • Variables (distintas de floats para impulsar el tiempo de movimiento). No se admiten las variables usadas para controlar la lógica de transición ni los multiplicadores de velocidad.
  • Estados reflejados, desplazamiento de ciclo y IK de pie.

Unión tardía y animadores

Cuando los clientes se unen a un evento mesh, se sincronizan con el estado actual y la hora local de todos los nodos de animación en ejecución. Si tienes una animación de larga duración que se reproduce en un estado, el tiempo de reproducción se establecerá en la hora actual correcta de la animación en combinación tardía. Sin embargo, si el estado desencadena eventos, no se desencadenarán en el cliente unido más tarde. Es posible que algunos otros escenarios no funcionen según lo previsto; por ejemplo, si activa un sonido habilitando un AudioSource al principio de un estado, audioSource seguirá estando habilitado en el cliente de unión tardía, pero comenzará a reproducirse al principio del clip de audio.

Estado inicial del animador

Se recomienda crear animadores que tengan estados predeterminados que no hagan nada. Cuando una escena comienza a reproducirse en Unity, activará todos los animadores y empezará a reproducir sus animaciones predeterminadas. Esto puede ocurrir antes de que se produzca la conexión de Mesh Cloud Scripting Service; por lo tanto, es posible que no haya ninguna manera de sincronizar estos estados y comportamiento como desee.

Reparente y clonación del animador

AnimationNodes no se puede crear a través de Mesh Cloud Scripting API. La única manera de crear un AnimationNode es exportando una escena de Unity que contiene un componente animador. Si intenta clonar o reparentar animationNode, obtendrá un error porque no hay ninguna manera de admitir esta acción. Todavía es posible clonar o reparentar el elemento primario del AnimationNode, ya que esto corresponde al objeto de juego de Unity que se puede clonar y primariamente.

Notas sobre el código generado

El código generado quitará espacios de nombres de animadores, capas, estados y variables; por ejemplo, el nombre de la variable "my var" se convierte en "myVar" en el código. Por este motivo, es posible crear animadores que no generen código válido. Por ejemplo, si tiene dos variables denominadas "my var" y "myVar", recibirá un error durante la generación y un mensaje que le pide que cambie el nombre de las variables.

LightNode

PointLightNode, DirectionalLightNode y SpotLightNode se asignan al componente Light de Unity (que tendrá su tipo establecido en el valor correspondiente). Es posible establecer los parámetros básicos de estas luces a través de las API de LightNode. También es posible crear luces a mano a través de la API. La creación de nodos ligeros a través de la API dejará los parámetros que no se pueden establecer a través de Mesh Cloud Scripting API en sus valores predeterminados.

GeometryNode

BoxGeometryNode, SphereGeometryNode, CapsuleGeometryNode y MeshGeometryNode se asignan al componente colisionador box de Unity, componente de colisionador de esferas, componente de colisionador de cápsulas y componente colisionador de malla, respectivamente. También se pueden crear a través de Mesh Cloud Scripting API. Al habilitar y deshabilitar nodos de geometría, se agregarán y se quitarán de candidatos de posicionamiento si un MeshInteractableSetup está asociado a su objeto de juego o a uno de sus elementos primarios.

La creación de nodos de geometría a través de la API dejará los parámetros que no se pueden establecer a través de mesh API en sus valores predeterminados (por ejemplo, El material físico se establecerá en ninguno y isTrigger se establecerá en false).

RigidBodyNode

La adición de un componente Rigidbody a un objeto pondrá su movimiento bajo el control de la física de malla. Sin agregar ningún código, un objeto Rigidbody se extraerá hacia abajo por gravedad y reaccionará ante colisiones con otros objetos.

Nota: GeometryNode.Friction devolverá staticFriction. Sin embargo, si se establece en mesh Cloud Scripting, se actualizará tanto como staticFrictiondynamicFriction en los clientes.

Desencadenadores de volúmenes

Los nodos de geometría pueden actuar como volúmenes desencadenadores cuando su IsTrigger propiedad se establece en true. Esta marca corresponde a la IsTrigger propiedad del colisionador en Unity y no se puede cambiar en tiempo de ejecución. Cuando la geometría es un desencadenador, se generará Entered y Exited para cualquier Avatares que inicie o detenga la superposición con él.

Nota: El objeto unity debe agregarse a la TriggerVolume capa para permitir que el haz de teletransporte lo ignore, ya que los colisionadores de la Default capa bloquean el haz de teletransporte.

TextNode

TextNode se asigna al componente TextMeshPro de Unity. Si agrega un componente TextMeshPro a la escena, habrá un TextNode correspondiente en la jerarquía de escenas de Scripting en la nube de Malla. Esto le permite establecer el texto del componente en tiempo de ejecución. También puede cambiar las propiedades de texto básicas a través de TextNode API: negrita, cursiva, subrayado, tachado y color. Actualmente no es posible crear un TextNode a través de la API; Debe crearlos agregándolos a la escena en Unity. Además, no puede clonar un TextNode directamente; en su lugar, debe clonar el TranformNode primario de TextNode.

Mallas

Actualmente, las mallas son componentes "ocultos" en mesh Cloud Scripting API. Se pueden crear en el editor de Unity y se pueden manipular manipulando sus objetos de juego primarios o componentes de transformación, pero no se pueden crear mediante programación, ni se pueden editar sus propiedades en tiempo de ejecución a través de mesh API.

Otros temas de Scripting en la nube de Mesh

Adición de recursos al servicio Mesh Cloud Scripting

Si necesita agregar un recurso para que lo use Mesh Cloud Scripting Service, debe agregarlo como un recurso incrustado en el archivo de proyecto de C#. Esto se puede hacer a través de la interfaz de usuario del proyecto en Visual Studio o agregando la siguiente línea al archivo .csproj directamente:

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

Tenga en cuenta que así es como se empaqueta scene.map, que puede ver en el archivo .csproj como referencia.

Trabajar con física de malla

Mesh Physics se encargará de sincronizar el movimiento de los cuerpos rígidos entre los clientes. Mesh Cloud Scripting TransformNode.Position, TransformNode.Rotationy RigidBody.VelocityRigidBody.AngularVelocity no se actualizarán con el estado de simulación más reciente. Sin embargo, los clientes aplicarán cambios si se establecen en Mesh Cloud Scripting Service. Tenga en cuenta que cambiar la propiedad única dejará a otros sin cambios. Por ejemplo, si solo se establece la posición, la velocidad no se cambiará y el cuerpo rígido continuará el movimiento con la velocidad antigua desde la nueva posición. Dado que Mesh Cloud Scripting Service no se actualiza con el estado de movimiento más reciente para cuerpos rígidos, se recomienda establecer estos solo para nuevos cuerpos rígidos.

Si TransformNode con RigidBodyNode se clona, el cuerpo clonado se registrará y se entregará a Mesh Physics para la sincronización entre los clientes. Nota: El cuerpo rígido clonado tendrá posición, rotación y velocidades desde el principio de la escena del cuerpo rígido original. Si estos deben ser diferentes, deben establecerse explícitamente en Mesh Cloud Scripting.

Pasos siguientes

Administración y infraestructura de scripting en la nube