Guide du programmeur de scriptur cloud

Ce guide explique comment utiliser l’API Mesh Cloud Scripting et les outils de développement pour créer des environnements (ceux-ci commencent en tant que projets dans Unity, puis sont chargés dans une collection Mesh). Nous vous recommandons de lire d’abord l’infrastructure Set cloud Scripting dans Azure pour vous familiariser avec les concepts et l’architecture de base de Mesh Cloud Scripting.

Cette section décrit les fonctionnalités et l’interface de l’API Mesh Cloud Scripting, qui est utilisée pour écrire les scripts qui pilotent les comportements dans les environnements.

Structure DOM de base

La structure DOM reflète la structure de votre scène Unity. Le membre « Scene » de l’application correspond à l’objet de jeu auquel votre composant Mesh Cloud Scripting est attaché. Les classes d’API Mesh Cloud Scripting suivantes mappent un-à-un avec les objets Unity créés dans l’éditeur :

• GameObject (&Transform Component) -> TransformNode
• Composant Light -> PointLightNode, SpotLightNode, DirectionalLightNode
• Composant Animator -> AnimationNode (et classes dérivées, voir ci-dessous)
• Composant Box Collider -> BoxGeometryNode
• Composant Collider Sphere -> SphereGeometryNode
• Composant Capsule Collider -> CapsuleGeometryNode
• Composant Mesh Collider -> MeshGeometryNode
• Composant Text Mesh Pro -> TextNode
• Composant Rigidbody -> RigidBodyNode

Par exemple, si vous créez une scène avec un objet de jeu qui a un composant Light (défini sur une lumière de point) et un collider de sphère attaché, votre scène contiendra un TransformNode avec deux enfants : un PointLightNode et un SphereGeometryNode.

En outre, certains objets API Mesh Cloud Scripting n’ont pas de composants Unity intégrés correspondants. Il s’agit de composants supplémentaires que vous pouvez créer dans Unity qui font partie du package de kit de ressources Mesh.

• Composant Mesh Cloud Scripting (décrit ci-dessus)
• Composant WebSlate

Mappage du DOM Unity au DOM mesh

Vous pouvez créer une scène avec des composants que l’API Mesh Cloud Scripting ne connaît pas. Celles-ci n’existent tout simplement pas dans le DOM mesh Cloud Scripting pour la scène. Toutefois, la structure de scène complète des GameObjects sera mise en miroir dans l’API DOM en tant que TransformNodes.

Unity a une forme d’API GameObject/component ; toutefois, le DOM Mesh Cloud Scripting a une seule arborescence. Un TransformNode dans l’API Mesh Cloud Scripting a des enfants qui peuvent être d’autres TransformNodes ou d’autres nœuds mappés aux composants. Nous pouvons considérer cette liste fusionnée des composants de l’objet de jeu associé et des enfants de son composant de transformation.

Transformation rectangulaire

Si vous ajoutez un composant qui utilise un RectTransform( par exemple, le composant Text Mesh Pro), l’objet de jeu n’apparaît pas en tant que nœud dans le graphique de scène Mesh Cloud Scripting. Il est toujours possible de déplacer, d’activer et de désactiver ce composant, mais pour ce faire, vous devez encapsuler l’objet de jeu à l’aide de RectTransform dans un autre objet de jeu à l’aide du composant Transform standard.

Événements de changement de propriété

Vous pouvez vous abonner aux événements de modification de propriété en appelant AddPropertyChangedEventHandler n’importe quel nœud de la hiérarchie. Vous devez passer le nom de la propriété sous forme de chaîne.

Il est également possible de s’abonner à tous les événements en s’abonnant à l’événement DomObjectPropertyChanged . Cela est appelé lorsqu’une propriété dans le DOM change.

Cycle de vie des objets

Les nœuds, lorsqu’ils sont créés, ne sont pasparés. Cela signifie qu’ils ne seront pas visibles dans la scène tant qu’ils ne seront pas explicitement ajoutés en tant qu’enfant à la scène ou à l’un de ses descendants. De même, la définition du parent d’un nœud sur Null le supprime et ses descendants de la scène.

Parfois, vous souhaitez désactiver temporairement un nœud, mais pas conserver un enregistrement de l’emplacement où il se trouvait dans la scène. Pour cette raison, chaque nœud a un indicateur « actif ». Quand la valeur est false, elle désactive le nœud et ses descendants.

Vous pouvez créer des objets et des composants de jeu dans Unity qui font partie de la scène, mais qui sont désactivés. Ceux-ci s’affichent en tant que nœuds dans la hiérarchie de scène Mesh Cloud Scripting, mais leur indicateur actif est défini sur false. La définition de l’indicateur actif sur true les active active dans la scène Unity.

Clonage et réparentation

Les nœuds peuvent être clonés et réparentés dans l’API Mesh Cloud Scripting ; la scène Unity correspondante sera mise à jour en conséquence. Si vous clonez un nœud, il clone ce nœud et tous ses enfants (y compris les enfants qui peuvent se trouver dans les objets Unity correspondants, mais qui ne sont pas visibles par mesh Cloud Scripting).

Il est possible de cloner ou de réparer des nœuds qui correspondent aux composants Unity. Cela est implémenté en recréant ces composants Unity en fonction des représentations de nœud Mesh Cloud Scripting. Seuls les nœuds qui peuvent être créés via l’API Mesh Cloud Scripting peuvent être clonés ou réparentés. Si vous avez créé un composant dans Unity et défini des champs qui ne sont pas reflétés dans le nœud mesh Cloud Scripting correspondant, ces champs sont réinitialisés à leurs valeurs par défaut si le nœud lui-même est cloné. Pour cette raison, nous vous recommandons de cloner ou de réparer des nœuds de transformation dans lesquels vous manipulez des objets créés dans Unity. Celles-ci conservent toujours correctement tous les paramètres Unity d’origine.

Utilisateurs

Il existe différents emplacements dans l’API qui fournissent des propriétés utilisateur. La User.Identifier propriété est une chaîne d’identificateur persistant persistante pour l’utilisateur, même si l’utilisateur quitte et rejoint. Le nom d’affichage de l’utilisateur est également accessible via User.DisplayName. L’ID d’événement à partir duquel l’utilisateur est connecté est accessible via User.ConnectedEventId.

Pendant le développement, le nom d’affichage, l’identificateur et l’ID d’événement de l’utilisateur peuvent être simulés dans l’éditeur de composant Mesh Cloud Scripting dans les « Paramètres du développeur », comme indiqué ci-dessous.

Avatars

Les avatars sont la représentation des utilisateurs dans la scène. Ils peuvent être utilisés pour téléporter les utilisateurs à un emplacement donné, voyager entre les scènes et détecter les collisions avec des volumes de déclencheurs.

Boîtes de dialogue d’informations

Il est possible dans Mesh Cloud Scripting de faire apparaître une boîte de dialogue d’espace d’écran dans l’application Microsoft Mesh avec un message personnalisé. SceneNode contient une fonction pour cela. ShowMessageToParticipants(string message, IReadOnlyCollection<Participant> participants) Les balises de texte enrichi peuvent être utilisées dans le message pour contrôler les propriétés du texte (couleur, gras, etc.).

Boîtes de dialogue d’entrée

Mesh Cloud Scripting peut demander une entrée de texte à un participant dans un événement Mesh avec un message personnalisé. CloudApplication fournit la méthode Task<string> ShowInputDialogToParticipantAsync(string message, Participant participant, CancellationToken token). Les balises de texte enrichi peuvent être utilisées dans le message pour contrôler les propriétés du texte (par exemple, couleur ou gras).

Classes

CloudApplication

L’interface ICloudApplication est le point de départ du développement d’applications Mesh. Il est disponible dans « App.cs » comme variable _app. En plus de la scène, ICloudApplication crée des fonctions pour tous les types disponibles. Il a également un certain nombre d’autres méthodes, mais elles sont destinées à une utilisation interne.

InteractableNode

MeshInteractableSetup est un composant Unity personnalisé qui fait partie du package du kit de ressources Mesh. Lorsque vous l’attachez à un objet de jeu dans Unity, il déclenche des événements de clic quand un utilisateur clique sur l’un des collidables actifs dans cet objet de jeu ou ses enfants.

Un exemple simple est illustré ci-dessous, où le composant MeshInteractableSetup est ajouté au même objet de jeu que le collisionneur de boîtes :

WebSlateNode

WebSlate est un composant Unity personnalisé qui fait partie du package du kit de ressources Mesh. Pour ajouter un préfabriqué WebSlate à votre scène, sélectionnez GameObject>Mesh Toolkit>WebSlate dans la barre de menus. Le site web affecté à la propriété URL de l’instance WebSlate est rendu sur le quad de ce préfabriqué.

Un exemple est illustré ci-dessous, où un prefab WebSlate a été ajouté à la scène et affecté une URL :

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

Écoute des clics

Voici un script simple mesh Cloud Scripting qui fait pivoter le cube chaque fois qu’il est cliqué. Remplacez la méthode stub StartAsync à l’intérieur App.cs de ce code.

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

Informations sur l’accès

Il est possible de déterminer quel utilisateur a cliqué sur le collider en examinant les arguments d’événement de modification de propriété. Vous pouvez également lire la normale du contact et la position du clic à partir des arguments d’événement. Ces coordonnées sont relatives à l’espace de coordonnées local de l’InteractableNode.

Animateurs

Vous pouvez créer et ajouter un animateur Unity à votre scène et le contrôler via mesh Cloud Scripting. Le plug-in mesh toolkit examine les ressources de votre projet Unity et pour chaque Animateur trouvé, il génère une classe dans un dossier « AnimationScripts » dans votre projet Mesh Cloud Scripting. Cette classe dérive d’AnimationNode et peut être utilisée pour contrôler l’animateur à partir de Mesh Cloud Scripting. Lorsque vous ajoutez l’Animator en tant que composant à un objet de jeu dans Unity, vous trouverez une instance correspondante de la classe générée en tant qu’enfant du TransformNode correspondant. À l’aide de l’API de cette classe, vous pouvez contrôler l’animateur.

Le modèle de programmation Mesh Cloud Scripting fait autorité sur le serveur et nous prenons en charge uniquement un petit sous-ensemble de la fonctionnalité d’animation. Cela est dû au fait que nous modélisons l’animateur sur le serveur et nous attendons à ce que tous les clients se synchronisent avec précision avec le modèle serveur. Pour cette raison, seule l’API suivante est actuellement prise en charge :

• Paramètre d’état (pour chaque couche, il existe une propriété correspondante dans la classe qui peut être définie sur une énumération en fonction des états disponibles dans l’animation). Les états sont définis immédiatement, et non pas par des transitions.
• Paramètre de variable float : seules les variables float sont exposées, et uniquement à des fins de liaison à « Temps de mouvement » dans un Animateur.
• Paramètre de vitesse de couche

Dans un état, vous pouvez créer un clip d’animation sans restriction sur les valeurs que vous pouvez définir dans la scène Unity. Les clips d’animation en boucle sont également pris en charge. Les fonctionnalités suivantes des Animateurs ne sont pas prises en charge par le biais d’AnimationNodes :

• Transitions : si vous ajoutez des transitions à votre Animateur, vous ne pourrez pas les déclencher via l’API Mesh Cloud Scripting (le serveur ne modèle pas les transitions).
• Variables (autres que les flotteurs pour piloter le temps de mouvement). Les variables utilisées pour générer une logique de transition ou des multiplicateurs de vitesse ne sont pas prises en charge.
• États mis en miroir, décalage de cycle et IK de pied.

Jointure tardive et animateurs

Lorsque les clients rejoignent un événement Mesh, ils se synchronisent avec l’état actuel et l’heure locale de tous les nœuds d’animation en cours d’exécution. Si vous avez une animation longue en cours de lecture dans un état, l’heure de lecture est définie sur l’heure actuelle correcte de l’animation lors de la jointure tardive. Toutefois, si votre état déclenche des événements, ceux-ci ne seront pas déclenchés dans le client joint en retard. Certains autres scénarios peuvent ne pas fonctionner comme prévu ; par exemple, si vous déclenchez un son en activant audioSource au début d’un état, audioSource sera toujours activé dans le client de jointure tardive, mais commence à lire au début du clip audio.

État initial de l’animateur

Nous vous recommandons de créer des animateurs qui ont des états par défaut qui ne font rien. Lorsqu’une scène commence à jouer dans Unity, elle active tous les animateurs et commence à lire leurs animations par défaut. Cela peut se produire avant que la connexion du service mesh Cloud Scripting ne se produise ; par conséquent, il n’existe aucun moyen de synchroniser ces états et ce comportement peut ne pas être aussi souhaité.

Animateur réparent et clonage

AnimationNodes ne peut pas être créé via l’API Mesh Cloud Scripting. La seule façon de créer un AnimationNode consiste à exporter une scène Unity qui contient un composant Animator. Si vous essayez de cloner ou de réparer animationNode, vous obtenez une erreur, car il n’existe aucun moyen de prendre en charge cette action. Il est toujours possible de cloner ou de réparer le parent de l’AnimationNode, car cela correspond à l’objet de jeu Unity contenant qui peut être cloné et parenté.

Remarques sur le code généré

Le code généré supprime les espaces des noms d’animateurs, de couches, d’états et de variables ; par exemple, le nom de variable « my var » devient « myVar » dans le code. Pour cette raison, il est possible de créer des animateurs qui ne génèrent pas de code valide. Par exemple, si vous avez deux variables nommées « my var » et « myVar », vous obtenez une erreur pendant la génération et un message vous demandant de renommer la ou les variables.

LightNode

PointLightNode, DirectionalLightNode et SpotLightNode sont tous mappés au composant Unity Light (qui aura son type défini sur la valeur correspondante). Il est possible de définir les paramètres de base de ces lumières via les API LightNode. Il est également possible de créer des lumières à l’aide de l’API. La création de nœuds légers via l’API laisse les paramètres qui ne sont pas définis par le biais de l’API Mesh Cloud Scripting sur leurs valeurs par défaut.

GeometryNode

BoxGeometryNode, SphereGeometryNode, CapsuleGeometryNode et MeshGeometryNode sont mappés au composant Box Collider de Unity, au composant de collision de sphère, au composant capsule collider et au composant mesh Collider, respectivement. Ils peuvent également être créés via l’API Mesh Cloud Scripting. L’activation et la désactivation des nœuds Geometry vont ajouter et les supprimer des candidats à l’accès si un MeshInteractableSetup est attaché à leur objet de jeu ou à l’un de ses parents.

La création de nœuds géométriques par le biais de l’API laisse les paramètres qui ne sont pas définis par défaut par l’API Mesh (par exemple, le matériau physique n’est défini sur aucun et isTrigger a la valeur false).

RigidBodyNode

L’ajout d’un composant Rigidbody à un objet mettra son mouvement sous le contrôle de la physique du maillage. Sans ajouter de code, un objet Rigidbody sera tiré vers le bas par gravité et réagira aux collisions avec d’autres objets.

Remarque : GeometryNode.Friction retourne staticFriction. Toutefois, s’il est défini côté Script cloud Mesh, il met à jour les deux staticFriction et dynamicFriction sur les clients.

Déclencher des volumes

Les nœuds geometry peuvent agir en tant que volumes de déclencheur lorsque leur IsTrigger propriété est définie sur true. Cet indicateur correspond à la IsTrigger propriété sur le collider dans Unity et ne peut pas être modifié au moment de l’exécution. Lorsque la géométrie est un déclencheur, elle génère Entered et Exited pour tous les avatars qui démarrent/arrêtent le chevauchement avec celui-ci.

Remarque : L’objet Unity doit être ajouté à la TriggerVolume couche pour permettre au faisceau de téléport de l’ignorer, car les collisionneurs dans la Default couche bloquent le faisceau de téléport.

TextNode

TextNode est mappé au composant TextMeshPro de Unity. Si vous ajoutez un composant TextMeshPro à votre scène, il y aura un TextNode correspondant dans votre hiérarchie de scène Mesh Cloud Scripting. Cela vous permet de définir le texte du composant au moment de l’exécution. Vous pouvez également modifier les propriétés de texte de base par le biais de l’API TextNode ( gras, italique, soulignement, frappement et couleur). Il n’est actuellement pas possible de créer un TextNode via l’API ; vous devez les créer en les ajoutant à votre scène dans Unity. En outre, vous ne pouvez pas cloner directement un TextNode. Vous devez au lieu de cela cloner le tranformNode parent de TextNode.

Maillages

Les maillages sont actuellement des composants « masqués » de l’API Mesh Cloud Scripting. Ils peuvent être créés dans l’éditeur Unity et peuvent être manipulés en manipulant leurs objets de jeu parent/composants Transform, mais ils ne peuvent pas être créés par programmation, ni leurs propriétés peuvent être modifiées au moment de l’exécution via l’API Mesh.

Scripts visuels

Vous pouvez créer et ajouter une machine de script Unity à votre scène et la contrôler via Mesh Cloud Scripting. Le plug-in mesh toolkit examine les ressources de votre projet Unity et pour chaque machine de script trouvée, elle génère une classe dans un dossier « VisualScripts » dans votre projet Mesh Cloud Scripting. Cette classe dérive de VisualScriptNode et peut être utilisée pour manipuler les variables Unity associées à la machine de script à partir de Mesh Cloud Scripting. Lorsque vous ajoutez l’ordinateur de script en tant que composant à un GameObject dans Unity, vous trouverez une instance correspondante de la classe générée en tant qu’enfant du TransformNode correspondant. À l’aide de l’API de cette classe, vous pouvez contrôler les variables de l’ordinateur de script.

Synchronisation d’état

Par défaut, Mesh réplique automatiquement les modifications de scène effectuées par des scripts visuels sur un client vers tous les autres clients. Pour que mesh Cloud Scripting prenne connaissance d’une modification apportée par le biais d’un script visuel, les conditions préalables suivantes doivent être remplies :

• Le composant Machine de script se trouve sur un GameObject qui est un descendant de la racine de la scène Mesh Cloud Scripting.
• L’option « Activer le script visuel » du composant Mesh Cloud Scripting est activée.

Si l’une des conditions ci-dessus n’est pas remplie, le runtime Mesh Visual Scripting continue de répliquer les modifications de scène, mais Mesh Cloud Scripting reste inconscient de ces modifications.

InitialState

Nous recommandons que vos scripts visuels ne modifient pas ou ne s’appuient pas sur l’état partagé au démarrage. L’événement On Start se produit généralement avant que la connexion du service mesh Cloud Scripting ne se produise ; par conséquent, il n’existe aucun moyen de synchroniser l’état à ce stade dans le temps, et le comportement peut ne pas être ce que vous souhaitez.

Jointure tardive

Lorsque les clients rejoignent un événement Mesh, ils se synchronisent avec l’état actuel de tous les nœuds Visual Script. Tout événement De modification de l’état qui a été déclenché précédemment sur les autres clients ne sera pas déclenché sur le client joint en retard. Certains autres scénarios peuvent ne pas fonctionner comme prévu ; par exemple, si vous déclenchez un son en activant audioSource en réponse à un événement On State Changed, audioSource sera toujours activé dans le client de jointure tardive, mais commence à lire au début du clip audio.

Réparentation et clonage

VisualScriptNode ne peut pas être créé via l’API Mesh Cloud Scripting. La seule façon de créer un VisualScriptNode consiste à exporter une scène Unity qui contient un composant Machine de script. Si vous essayez de cloner ou de réparer VisualScriptNode, vous obtenez une erreur, car il n’existe aucun moyen de prendre en charge cette action. Il est toujours possible de cloner ou de réparer le parent du VisualScriptNode, car cela correspond au GameObject Unity contenant qui peut être cloné et parenté.

Remarques sur le code généré

Le code généré supprime les espaces des noms des machines de script et des variables ; par exemple, le nom de variable « my var » devient « MyVar » dans le code. Pour cette raison, il est possible de créer des machines de script qui ne génèrent pas de code valide. Par exemple, si vous avez deux variables nommées « my var » et « myVar », vous obtenez une erreur pendant la génération et un message vous demandant de renommer la ou les variables.

Autres rubriques de script cloud Mesh

Ajout de ressources au service Mesh Cloud Scripting

Si vous devez ajouter une ressource pour votre service Mesh Cloud Scripting à utiliser, vous devez l’ajouter en tant que ressource incorporée dans votre fichier projet C#. Vous pouvez effectuer cette opération via l’interface utilisateur du projet dans Visual Studio ou en ajoutant la ligne suivante dans le fichier .csproj directement :

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

Notez que c’est la façon dont scene.map est empaquetée, que vous pouvez voir dans le fichier .csproj pour référence.

Utilisation de la physique du maillage

Mesh Physics s’occupera de synchroniser le mouvement des corps rigides entre les clients. Mesh Cloud Scripting TransformNode.Position, TransformNode.RotationRigidBody.Velocity et RigidBody.AngularVelocity ne sera pas mis à jour avec l’état de simulation le plus récent. Toutefois, les clients appliquent des modifications si celles-ci sont définies dans le service Mesh Cloud Scripting. Notez que la modification d’une propriété unique laissera d’autres personnes inchangées. Par exemple, si seule la position est définie, la vitesse ne sera pas modifiée et le corps rigide continuera de mouvement avec une ancienne vitesse de nouvelle position. Étant donné que mesh Cloud Scripting Service n’est pas mis à jour avec l’état de mouvement le plus récent pour les corps rigides, il est recommandé de les définir uniquement pour les nouveaux corps rigides.

S’il TransformNode RigidBodyNode est cloné, le corps cloné est inscrit et remis à Mesh Physics la synchronisation entre les clients. Remarque : Le corps rigide cloné aura une position, une rotation et des vitesses à partir du début de la scène du corps rigide original. S’ils doivent être différents, ils doivent être définis explicitement dans mesh Cloud Scripting.

Étapes suivantes