Guida del programmatore di scripting cloud

Questa guida descrive come usare l'API Mesh Cloud Scripting e gli strumenti di sviluppo per la compilazione di ambienti (questi iniziano come progetti in Unity e vengono quindi caricati in una raccolta mesh). È consigliabile leggere prima di tutto l'infrastruttura Set cloud Scripting in Azure per acquisire familiarità con i concetti e l'architettura di base di Mesh Cloud Scripting.

Questa sezione descrive le funzionalità e l'interfaccia dell'API Mesh Cloud Scripting, usata per scrivere gli script che determinano i comportamenti negli ambienti.

Struttura DOM di base

La struttura DOM rispecchia la struttura della scena unity. Il membro "Scene" dell'applicazione corrisponde all'oggetto gioco a cui è collegato il componente Mesh Cloud Scripting. Le classi API Mesh Cloud Scripting seguenti eseguono il mapping uno-a-uno con gli oggetti Unity creati nell'editor:

• GameObject (& Transform Component) -> TransformNode
• Componente chiaro -> PointLightNode, SpotLightNode, DirectionalLightNode
• Componente animazione -> AnimationNode (e classi derivate, vedere di seguito)
• Componente Box Collider -> BoxGeometryNode
• Componente collisore sphere -> SphereGeometryNode
• Componente Capsule Collider -> CapsuleGeometryNode
• Componente collisore mesh -> MeshGeometryNode
• Componente Text Mesh Pro -> TextNode
• Componente Rigidbody -> RigidBodyNode

Ad esempio, se crei una scena con un oggetto gioco con un componente Light (impostato su una luce punto) e un collisore sfera collegato, la scena conterrà un oggetto TransformNode con due elementi figlio: PointLightNode e SphereGeometryNode.

Inoltre, alcuni oggetti API di scripting cloud mesh non dispongono di componenti Unity predefiniti corrispondenti. Si tratta di componenti aggiuntivi che è possibile creare in Unity che fanno parte del pacchetto mesh toolkit.

• Componente Mesh Cloud Scripting (descritto in precedenza)
• Componente WebSlate

Mapping del DOM unity al DOM mesh

È possibile creare una scena con componenti che l'API Mesh Cloud Scripting non conosce. Questi non esistono semplicemente nel DOM di scripting cloud mesh per la scena. Tuttavia, la struttura completa della scena di GameObjects verrà rispecchiata nell'API DOM come TransformNodes.

Unity ha una forma API GameObject/component; Tuttavia, mesh cloud scripting DOM ha una singola struttura ad albero. Un oggetto TransformNode nell'API di scripting del cloud mesh include elementi figlio che possono essere altri TransformNodes o altri nodi di cui viene eseguito il mapping ai componenti. Possiamo considerare questo elenco unito dei componenti dell'oggetto gioco associato e degli elementi figlio del relativo componente di trasformazione.

Rect Transform

Se si aggiunge un componente che usa rectTransform, ad esempio il componente Text Mesh Pro, l'oggetto gioco non verrà visualizzato come nodo nel grafico della scena di scripting del cloud mesh. È comunque possibile spostare, abilitare e disabilitare tale componente, ma a tale scopo, è necessario eseguire il wrapping dell'oggetto gioco usando RectTransform in un altro oggetto gioco usando il normale componente Transform.

Eventi di modifica delle proprietà

È possibile sottoscrivere gli eventi di modifica delle proprietà chiamando AddPropertyChangedEventHandler su qualsiasi nodo della gerarchia. È necessario passare il nome della proprietà come stringa.

È anche possibile sottoscrivere tutti gli eventi sottoscrivendo l'evento DomObjectPropertyChanged . Viene chiamato quando viene modificata qualsiasi proprietà nel DOM.

Ciclo di vita degli oggetti

I nodi, al momento della creazione, non sonoparentati. Ciò significa che non saranno visibili nella scena finché non vengono aggiunti in modo esplicito come figlio alla scena o a uno dei relativi discendenti. Analogamente, l'impostazione dell'elemento padre di un nodo su Null lo rimuoverà e i relativi discendenti dalla scena.

In alcuni casi si vuole disabilitare temporaneamente un nodo, ma non mantenere un record di dove si trovava nella scena. Per questo motivo, ogni nodo ha un flag "attivo". Se impostato su false, il nodo e i relativi discendenti verranno disabilitati.

È possibile creare oggetti e componenti di gioco in Unity che fanno parte della scena, ma sono disabilitati. Questi verranno visualizzati come nodi nella gerarchia della scena di scripting del cloud mesh, ma il flag attivo sarà impostato su false. L'impostazione del flag attivo su true consentirà di abilitarle nella scena unity.

Clonazione e reparenting

I nodi possono essere clonati e replicati nell'API Mesh Cloud Scripting; la scena Unity corrispondente verrà aggiornata di conseguenza. Se si clona un nodo, il nodo verrà clonato e tutti i relativi elementi figlio (inclusi gli elementi figlio che possono trovarsi negli oggetti Unity corrispondenti ma non sono visibili a Mesh Cloud Scripting).

È possibile clonare o replicare nodi che corrispondono ai componenti di Unity. Questa operazione viene implementata ricreando questi componenti unity in base alle rappresentazioni del nodo di scripting cloud mesh. Solo i nodi che possono essere creati tramite l'API di scripting del cloud mesh possono essere clonati o replicati. Se è stato creato un componente in Unity e si impostano campi che non si riflettono nel nodo di scripting del cloud mesh corrispondente, questi campi verranno reimpostati sulle impostazioni predefinite se il nodo stesso viene clonato. Per questo motivo, è consigliabile clonare o modificare nodi di trasformazione simultanei in cui si modificano gli oggetti creati in Unity. Queste impostazioni manterranno sempre correttamente tutte le impostazioni originali di Unity.

Utenti

Esistono diverse posizioni nell'API che forniscono proprietà utente. La User.Identifier proprietà è una stringa di identificatore permanente persistente per l'utente, anche se l'utente lascia e rielabora. Il nome visualizzato dell'utente è accessibile anche tramite User.DisplayName. L'ID evento da cui l'utente è connesso è accessibile tramite User.ConnectedEventId.

Durante lo sviluppo, il nome visualizzato dell'utente, l'identificatore e l'ID evento possono essere simulati nell'editor dei componenti Mesh Cloud Scripting in "Impostazioni sviluppatore", come illustrato di seguito.

Avatar

Gli avatar sono la rappresentazione degli utenti nella scena. Possono essere usati per teletrasportare gli utenti in una determinata posizione, spostarsi tra scene e rilevare conflitti con volumi di trigger.

Finestre di dialogo informazioni

In Mesh Cloud Scripting è possibile visualizzare una finestra di dialogo dello spazio sullo schermo nell'applicazione Microsoft Mesh con un messaggio personalizzato. SceneNode contiene una funzione per questo oggetto , ShowMessageToParticipants(string message, IReadOnlyCollection<Participant> participants). I tag RTF possono essere usati nel messaggio per controllare le proprietà del testo (colore, grassetto e così via).

Dialoghi di input

Mesh Cloud Scripting può richiedere input di testo da un partecipante in un evento Mesh con un messaggio personalizzato. CloudApplication fornisce il metodo Task<string> ShowInputDialogToParticipantAsync(string message, Participant participant, CancellationToken token). I tag RTF possono essere usati nel messaggio per controllare le proprietà del testo, ad esempio il colore o il grassetto.

Classi

CloudApplication

L'interfaccia ICloudApplication è il punto di partenza per lo sviluppo di app Mesh. È disponibile in "App.cs" come variabile _app. Oltre alla scena, ICloudApplication include funzioni di creazione per tutti i tipi disponibili. Include anche diversi altri metodi, ma sono per uso interno.

InteractableNode

MeshInteractableSetup è un componente Unity personalizzato che fa parte del pacchetto del toolkit mesh. Quando lo si collega a un oggetto gioco in Unity, viene generato un evento click quando un utente fa clic su uno qualsiasi dei collidabili attivi nell'oggetto gioco o nei relativi elementi figlio.

Di seguito è riportato un semplice esempio, in cui il componente MeshInteractableSetup viene aggiunto allo stesso oggetto gioco del collisore box:

WebSlateNode

WebSlate è un componente Unity personalizzato che fa parte del pacchetto mesh toolkit. Per aggiungere un prefab WebSlate alla scena, selezionare GameObject>Mesh Toolkit>WebSlate dalla barra dei menu. Il rendering del sito Web assegnato alla proprietà URL dell'istanza WebSlate viene eseguito nel quad di questo prefab.

Di seguito è riportato un esempio in cui è stato aggiunto un prefab WebSlate alla scena e assegnato un URL:

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

Ascolto dei clic

Di seguito è riportato un semplice script di scripting cloud mesh che ruota il cubo ogni volta che viene fatto clic. Sostituire il metodo stub StartAsync all'interno App.cs di con questo codice.

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

Informazioni di hit

È possibile scoprire quale utente ha fatto clic sul collisore esaminando gli argomenti dell'evento di modifica della proprietà. È anche possibile leggere la normale del contatto e la posizione del clic dagli argomenti dell'evento. Queste coordinate saranno relative allo spazio delle coordinate locali di InteractableNode.

Animatori

È possibile creare e aggiungere un animatore Unity alla scena e controllarlo tramite mesh cloud scripting. Il plug-in Mesh Toolkit esaminerà gli asset nel progetto Unity e per ogni animatore trovato genererà una classe in una cartella "AnimationScripts" nel progetto Mesh Cloud Scripting. Questa classe deriva da AnimationNode e può essere usata per controllare l'Animazione da Mesh Cloud Scripting. Quando si aggiunge l'Animator come componente a un oggetto gioco in Unity, si troverà un'istanza corrispondente della classe generata come elemento figlio del transformNode corrispondente. Usando l'API di questa classe, è possibile controllare l'animatore.

Il modello di programmazione Mesh Cloud Scripting è autorevole dal server e supportiamo solo un piccolo subset della funzionalità Di animazione. Ciò è dovuto al fatto che viene modellato l'animatore sul server e ci si aspetta che tutti i client si sincronizzeranno accuratamente con il modello server. Per questo motivo, attualmente è supportata solo l'API seguente:

• Impostazione dello stato (per ogni livello è presente una proprietà corrispondente nella classe che può essere impostata su un'enumerazione in base agli stati disponibili nell'animazione). Gli stati vengono impostati immediatamente, non tramite transizioni.
• Impostazione variabile float: vengono esposte solo le variabili float e solo per l'associazione a "Tempo di movimento" in un animatore.
• Impostazione della velocità del livello

All'interno di uno stato, è possibile creare un clip di animazione senza restrizioni sui valori che è possibile impostare nella scena unity. Sono supportate anche le clip di animazione a ciclo continuo. Le funzionalità seguenti di Animatori non sono supportate tramite AnimationNodes:

• Transizioni: se si aggiungono transizioni all'animatore, non sarà possibile attivarli tramite l'API di scripting del cloud mesh (il server non modella le transizioni).
• Variabili diverse da float per guidare il tempo di movimento. Le variabili usate per guidare la logica di transizione o i moltiplicatori di velocità non sono supportate.
• Stati con mirroring, offset del ciclo e IK del piede.

Join in ritardo e animatori

Quando i client si uniscono a un evento mesh, vengono sincronizzati con lo stato corrente e l'ora locale di tutti i nodi di animazione in esecuzione. Se hai un'animazione a esecuzione prolungata in uno stato, l'ora di riproduzione verrà impostata sull'ora corrente corretta dell'animazione al join in ritardo. Tuttavia, se lo stato genera eventi, questi non verranno attivati nel client aggiunto in ritardo. Altri scenari potrebbero non funzionare come previsto; Ad esempio, se si attiva un suono abilitando un Oggetto AudioSource all'inizio di uno stato, AudioSource sarà ancora abilitato nel client di join in ritardo, ma inizierà a riprodurre all'inizio del clip audio.

Stato iniziale dell'animazione

È consigliabile creare animatori con stati predefiniti che non eseguono alcuna operazione. Quando una scena inizia a giocare in Unity, attiverà tutti gli animatori e inizierà a riprodurre le animazioni predefinite. Questo problema può verificarsi prima che si verifichi la connessione al servizio di scripting cloud mesh; pertanto, non esiste alcun modo per sincronizzare questi stati e il comportamento potrebbe non essere come desiderato.

Riproduzione e clonazione dell'animatore

AnimationNodes non può essere creato tramite l'API Mesh Cloud Scripting. L'unico modo per creare un Oggetto AnimationNode consiste nell'esportare una scena Unity che contiene un componente Animator. Se tenti di clonare o replicare AnimationNode, riceverai un errore perché non è possibile supportare questa azione. È comunque possibile clonare o replicare l'elemento padre di AnimationNode, in quanto corrisponde all'oggetto gioco Unity che può essere clonato e padre.

Note sul codice generato

Il codice generato rimuoverà gli spazi dai nomi di animatori, livelli, stati e variabili; ad esempio, il nome della variabile "my var" diventa "myVar" nel codice. Per questo motivo, è possibile creare animatori che non generano codice valido. Ad esempio, se sono presenti due variabili denominate "my var" e "myVar", si riceverà un errore durante la generazione e viene visualizzato un messaggio che chiede di rinominare le variabili.

LightNode

PointLightNode, DirectionalLightNode e SpotLightNode eseguono il mapping al componente Unity Light (che avrà il tipo impostato sul valore corrispondente). È possibile impostare i parametri di base di queste luci tramite le API LightNode. È anche possibile creare luci a mano tramite l'API. La creazione di nodi leggeri tramite l'API lascerà i parametri che non sono impostabili tramite l'API di scripting del cloud mesh sulle impostazioni predefinite.

GeometryNode

BoxGeometryNode, SphereGeometryNode, CapsuleGeometryNode e MeshGeometryNode eseguono rispettivamente il mapping al componente Box Collider di Unity, componente collider sphere, componente capsule collider e componente collider mesh. Possono anche essere creati tramite l'API Mesh Cloud Scripting. L'abilitazione e la disabilitazione dei nodi Geometry aggiungeranno e rimuoveranno i nodi dai candidati se un oggetto MeshInteractableSetup è collegato all'oggetto gioco o a uno dei relativi elementi padre.

La creazione di nodi geometry tramite l'API lascerà i parametri che non sono impostabili tramite l'API Mesh sui valori predefiniti, ad esempio Fisica Materiale verrà impostato su nessuno e isTrigger verrà impostato su false.

RigidBodyNode

L'aggiunta di un componente Rigidbody a un oggetto metterà il suo movimento sotto il controllo della fisica mesh. Senza aggiungere codice, un oggetto Rigidbody verrà trascinato verso il basso dalla gravità e reagisce alle collisioni con altri oggetti.

Nota: GeometryNode.Friction restituirà staticFriction. Tuttavia, se impostato sul lato Mesh Cloud Scripting, verrà aggiornato sia staticFriction dynamicFriction che nei client.

Attivare volumi

I nodi geometry possono fungere da volumi trigger quando la proprietà IsTrigger è impostata su true. Questo flag corrisponde alla IsTrigger proprietà del collisore in Unity e non può essere modificato in fase di esecuzione. Quando la geometria è un trigger, genererà Entered e Exited per tutti gli avatar che iniziano/interrompono la sovrapposizione con esso.

Nota: l'oggetto Unity deve essere aggiunto al TriggerVolume livello per consentire al raggio di teletrasporta di ignorarlo, poiché i collisi nel Default livello bloccano il raggio di teletrasporto.

TextNode

TextNode esegue il mapping al componente TextMeshPro di Unity. Se si aggiunge un componente TextMeshPro alla scena, nella gerarchia della scena mesh cloud scripting sarà presente un nodo TextNode corrispondente. In questo modo è possibile impostare il testo del componente in fase di esecuzione. È anche possibile modificare le proprietà di testo di base tramite l'API TextNode, ovvero grassetto, corsivo, sottolineatura, barrato e colore. Non è attualmente possibile creare un oggetto TextNode tramite l'API; è necessario crearli aggiungendoli alla scena in Unity. Inoltre, non è possibile clonare direttamente un oggetto TextNode. È invece necessario clonare il nodo TranformNode padre di TextNode.

Mesh

Le mesh sono attualmente componenti "nascosti" all'API di scripting del cloud mesh. Possono essere creati nell'editor di Unity e possono essere modificati modificando gli oggetti del gioco padre o i componenti Transform, ma non possono essere creati a livello di codice, né possono essere modificati in fase di esecuzione tramite l'API Mesh.

Script visivi

È possibile creare e aggiungere un computer script Unity alla scena e controllarlo tramite Mesh Cloud Scripting. Il plug-in Mesh Toolkit esaminerà gli asset nel progetto Unity e per ogni computer script trovato genererà una classe in una cartella "VisualScripts" nel progetto Mesh Cloud Scripting. Questa classe deriva da VisualScriptNode e può essere usata per modificare le variabili unity associate al computer script da Mesh Cloud Scripting. Quando si aggiunge il computer di script come componente a un GameObject in Unity, si troverà un'istanza corrispondente della classe generata come figlio dell'oggetto TransformNode corrispondente. Usando l'API di questa classe, è possibile controllare le variabili del computer di script.

Sincronizzazione dello stato

Per impostazione predefinita, Mesh replica automaticamente le modifiche della scena eseguite dagli script visivi in un client in tutti gli altri client. Affinché mesh Cloud Scripting sia consapevole di una modifica apportata tramite script visivi, è necessario soddisfare le precondizioni seguenti:

• Il componente Macchina script si trova in un GameObject discendente della radice della scena mesh cloud scripting.
• L'opzione "Enable Visual Scripting" del componente Mesh Cloud Scripting è abilitata.

Se una delle condizioni precedenti non viene soddisfatta, il runtime di scripting degli oggetti visivi mesh continuerà a replicare le modifiche della scena, ma lo scripting del cloud mesh rimarrà oblivioso a queste modifiche.

Stato iniziale

È consigliabile che gli script visivi non modifichino o si basano sullo stato condiviso all'avvio. L'evento On Start si verifica in genere prima che si verifichi la connessione al servizio di scripting cloud mesh, pertanto non è possibile sincronizzare lo stato in quel momento e il comportamento potrebbe non essere quello desiderato.

Join in ritardo

Quando i client si uniscono a un evento mesh, vengono sincronizzati con lo stato corrente di tutti i nodi di Visual Script. Qualsiasi evento State Changed che potrebbe essere stato generato in precedenza negli altri client non verrà generato nel client aggiunto in ritardo. Altri scenari potrebbero non funzionare come previsto; Ad esempio, se si attiva un suono abilitando audioSource in risposta a un evento On State Changed, audioSource sarà ancora abilitato nel client di join in ritardo, ma inizierà a riprodurre all'inizio del clip audio.

Reparenting e clonazione

VisualScriptNode non può essere creato tramite l'API Mesh Cloud Scripting. L'unico modo per creare un oggetto VisualScriptNode consiste nell'esportare una scena unity che contiene un componente del computer script. Se si tenta di clonare o replicare VisualScriptNode, verrà visualizzato un errore perché non è possibile supportare questa azione. È comunque possibile clonare o replicare l'elemento padre di VisualScriptNode, in quanto corrisponde all'oggetto GameObject unity che può essere clonato e padre.

Note sul codice generato

Il codice generato rimuoverà gli spazi dai nomi delle macchine e delle variabili script; ad esempio, il nome della variabile "my var" diventa "MyVar" nel codice. Per questo motivo, è possibile creare computer script che non generano codice valido. Ad esempio, se sono presenti due variabili denominate "my var" e "myVar", si riceverà un errore durante la generazione e viene visualizzato un messaggio che chiede di rinominare le variabili.

Altri argomenti relativi a Scripting cloud mesh

Aggiunta di risorse al servizio di scripting cloud mesh

Se è necessario aggiungere una risorsa per il servizio di scripting cloud mesh da usare, è necessario aggiungerla come risorsa incorporata nel file di progetto C#. Questa operazione può essere eseguita tramite l'interfaccia utente del progetto in Visual Studio o aggiungendo direttamente la riga seguente al file con estensione csproj:

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

Si noti che questo è il modo in cui scene.map è incluso nel pacchetto, che è possibile visualizzare nel file con estensione csproj per riferimento.

Uso della fisica mesh

Mesh Physics si occuperà di sincronizzare il movimento dei corpi rigidi tra i client. Mesh Cloud Scripting TransformNode.Position, TransformNode.RotationRigidBody.Velocity e RigidBody.AngularVelocity non verrà aggiornato con lo stato di simulazione più recente. Tuttavia, i client applicheranno le modifiche se impostate nel servizio di scripting cloud mesh. Si noti che la modifica di una singola proprietà lascerà invariate altre. Ad esempio, se viene impostata solo la posizione, la velocità non verrà modificata e il corpo rigido continuerà a movimento con la vecchia velocità dalla nuova posizione. Dato che il servizio mesh cloud scripting non viene aggiornato con lo stato del movimento più recente per i corpi rigidi, è consigliabile impostarli solo per nuovi corpi rigidi.

Se TransformNode con RigidBodyNode viene clonato, il corpo clonato verrà registrato e consegnato a Mesh Physics per la sincronizzazione tra i client. Nota: il corpo rigido clonato avrà posizione, rotazione e velocità dall'inizio della scena del corpo rigido originale. Se questi elementi devono essere diversi, devono essere impostati in modo esplicito in Mesh Cloud Scripting.

Passaggi successivi

Infrastruttura e gestione di scripting cloud