Przewodnik programisty ds. skryptów w chmurze

W tym przewodniku opisano sposób używania interfejsu API tworzenia skryptów w chmurze usługi Mesh i narzędzi deweloperskich do tworzenia środowisk (te zaczynają się jako projekty w a unity, a następnie są przekazywane do kolekcji usługi Mesh). Zalecamy najpierw przeczytanie infrastruktury Ustawianie skryptów w chmurze na platformie Azure , aby zapoznać się z pojęciami i podstawową architekturą usługi Mesh Cloud Scripting.

W tej sekcji opisano funkcje i interfejs interfejsu API tworzenia skryptów w chmurze usługi Mesh, który służy do pisania skryptów, które napędzają zachowania w środowiskach.

Podstawowa struktura MODELU DOM

Struktura DOM odzwierciedla strukturę sceny aparatu Unity. Element członkowski "Scena" aplikacji odpowiada obiektowi gry, do którego jest dołączony składnik mesh Cloud Scripting. Następujące klasy interfejsu API tworzenia skryptów w chmurze usługi Mesh mapować jeden do jednego za pomocą obiektów aparatu Unity utworzonych w edytorze:

  • GameObject (& Transform Component) —> TransformNode
  • Składnik jasny —> PointLightNode, SpotLightNode, DirectionalLightNode
  • Składnik animatora —> AnimationNode (i klasy pochodne, zobacz poniżej)
  • Box Collider, składnik —> BoxGeometryNode
  • Składnik zderzacz sfery —> SphereGeometryNode
  • Składnik zderzacz kapsułek —> CapsuleGeometryNode
  • Składnik zderzacz siatki —> MeshGeometryNode
  • Składnik Text Mesh Pro —> TextNode
  • Sztywny składnikbody —> RigidBodyNode

Jeśli na przykład utworzysz scenę z obiektem gry, który ma składnik Light (ustawiony na światło punktu) i dołączony zderzacz sfery, scena będzie zawierać węzeł TransformNode z dwoma elementami podrzędnymi: PointLightNode i SphereGeometryNode.

Ponadto niektóre obiekty interfejsu API skryptów w chmurze usługi Mesh nie mają odpowiednich wbudowanych składników aparatu Unity. Są to dodatkowe składniki, które można utworzyć w środowisku Unity, które są częścią pakietu zestawu narzędzi usługi Mesh.

  • Składnik Mesh Cloud Scripting (opisany powyżej)
  • Składnik WebSlate

Mapowanie modelu DOM aparatu Unity na dom siatki

Możesz utworzyć scenę ze składnikami, o których interfejs API skryptów w chmurze usługi Mesh nie wie. Nie będą one po prostu istnieć w modelu DOM skryptów w chmurze usługi Mesh dla sceny. Jednak pełna struktura sceny obiektów GameObject zostanie zdublowana w interfejsie API DOM jako węzły TransformNodes.

Aparat Unity ma kształt interfejsu API GameObject/składnika; Jednak model DOM tworzenia skryptów w chmurze usługi Mesh ma jedną strukturę drzewa. Węzeł TransformNode w interfejsie API tworzenia skryptów w chmurze usługi Mesh zawiera elementy podrzędne, które mogą być innymi węzłami TransformNode lub innymi węzłami mapowymi na składniki. Możemy rozważyć to scaloną listę składników skojarzonego obiektu gry i elementów podrzędnych jego składnika transformacji.

Przekształć odchylone

Jeśli dodasz składnik, który używa składnika RectTransform — na przykład składnika Text Mesh Pro — obiekt gry nie będzie wyświetlany jako węzeł na grafie sceny Siatki skryptów w chmurze. Nadal można przenosić, włączać i wyłączać taki składnik, ale w tym celu wymagane jest opakowywanie obiektu gry przy użyciu obiektu RectTransform w innym obiekcie gry przy użyciu zwykłego składnika Transform.

Zdarzenia zmiany właściwości

Zdarzenia zmiany właściwości można subskrybować, wywołując dowolny AddPropertyChangedEventHandler węzeł w hierarchii. Musisz przekazać nazwę właściwości jako ciąg.

Istnieje również możliwość subskrybowania wszystkich zdarzeń przez zasubskrybowanie DomObjectPropertyChanged zdarzenia. Jest to wywoływane, gdy zmienia się dowolna właściwość w modelu DOM.

Cykl życia obiektu

Węzły, podczas tworzenia, są nieparzyste. Oznacza to, że nie będą widoczne w scenie, dopóki nie zostaną jawnie dodane jako dziecko do sceny lub jednego z jej elementów potomnych. Podobnie ustawienie elementu nadrzędnego węzła na wartość null spowoduje usunięcie go i jego elementów podrzędnych ze sceny.

Czasami chcesz tymczasowo wyłączyć węzeł, ale nie zachować rekordu miejsca, w którym znajdował się w scenie. Z tego powodu każdy węzeł ma flagę "aktywny". Po ustawieniu wartości false wyłączy węzeł i jego elementy podrzędne.

Można tworzyć obiekty i składniki gry w a unity, które są częścią sceny, ale są wyłączone. Będą one wyświetlane jako węzły w hierarchii sceny skryptów chmury usługi Mesh, ale ich aktywna flaga ma ustawioną wartość false. Ustawienie aktywnej flagi na true spowoduje włączenie ich w scenie aparatu Unity.

Klonowanie i ponowne wdrażanie

Węzły można klonować i reparented w interfejsie API tworzenia skryptów w chmurze usługi Mesh; odpowiednia scena aparatu Unity zostanie odpowiednio zaktualizowana. Jeśli sklonujesz węzeł, sklonuje ten węzeł i wszystkie jego elementy podrzędne (w tym elementy podrzędne, które mogą znajdować się w odpowiednich obiektach aparatu Unity, ale nie są widoczne dla usługi Mesh Cloud Scripting).

Istnieje możliwość sklonowania lub ponownego repozytorium węzłów odpowiadających składnikom aparatu Unity. Jest to implementowane przez ponowne utworzenie tych składników aparatu Unity w oparciu o reprezentacje węzła skryptów w chmurze usługi Mesh. Tylko węzły, które można tworzyć za pomocą interfejsu API tworzenia skryptów w chmurze usługi Mesh, można sklonować lub powtórzyć. Jeśli utworzono składnik w środowisku Unity i ustawiono pola, które nie zostały odzwierciedlone w odpowiednim węźle skryptów chmury usługi Mesh, te pola zostaną zresetowane do wartości domyślnych, jeśli węzeł zostanie sklonowany. Z tego powodu zalecamy klonowanie lub reparent węzłów przekształcania, w których manipulujesz obiektami utworzonymi w afiszacie Unity. Zawsze będą one prawidłowo zachowywać wszystkie oryginalne ustawienia aparatu Unity.

Użytkownicy

W interfejsie API znajdują się różne miejsca, które udostępniają właściwości użytkownika. Właściwość User.Identifier jest ciągiem identyfikatora trwałego, który jest trwały dla użytkownika, nawet jeśli użytkownik opuści i ponownie dołączy. Nazwa wyświetlana użytkownika jest również dostępna za pośrednictwem adresu User.DisplayName. Identyfikator zdarzenia, z którego nawiązano połączenie użytkownika, jest dostępny za pośrednictwem .User.ConnectedEventId

Podczas opracowywania nazwy wyświetlanej użytkownika, identyfikatora i identyfikatora zdarzenia można wyśmiewać w edytorze składników usługi Mesh Cloud Scripting w ustawieniach dewelopera, jak pokazano poniżej.

Pozorowanie właściwości użytkownika

Avatary

Awatary są reprezentacją użytkowników w scenie. Mogą służyć do teleportowania użytkowników do danej lokalizacji, podróży między scenami i wykrywania kolizji z woluminami wyzwalaczy.

Okna dialogowe informacji

W usłudze Mesh Cloud Scripting istnieje możliwość wyskakującego okna dialogowego miejsca na ekranie w aplikacji Usługi Microsoft Mesh z niestandardowym komunikatem. SceneNode zawiera funkcję dla tego elementu ShowMessageToParticipants(string message, IReadOnlyCollection<Participant> participants). Tagi tekstu sformatowanego mogą służyć w komunikacie do kontrolowania właściwości tekstu (kolor, pogrubienie itp.).

Klasy

CloudApplication

Interfejs ICloudApplication jest punktem wyjścia do tworzenia aplikacji usługi Mesh. Jest ona dostępna w pliku "App.cs" jako zmienna _app. Oprócz sceny program ICloudApplication zawiera funkcje tworzenia dla wszystkich dostępnych typów. Ma również wiele innych metod, ale są przeznaczone do użytku wewnętrznego.

InteractableNode

MeshInteractableSetup to niestandardowy składnik aparatu Unity, który jest częścią pakietu zestawu narzędzi usługi Mesh. Po dołączeniu go do obiektu gry w a unity, będzie on zgłaszać zdarzenia kliknięcia, gdy dowolny użytkownik kliknie dowolny z aktywnych zderzaków w tym obiekcie gry lub jego elementach podrzędnych.

Poniżej przedstawiono prosty przykład, w którym składnik MeshInteractableSetup jest dodawany do tego samego obiektu gry co zderzacz box:

Przykład prostych danych wejściowych

WebSlateNode

WebSlate to niestandardowy składnik aparatu Unity, który jest częścią pakietu zestawu narzędzi usługi Mesh. Aby dodać prefab webSlate do sceny, wybierz pozycję GameObject>Mesh Toolkit>WebSlate na pasku menu. Witryna internetowa przypisana do właściwości URL wystąpienia webSlate jest renderowana na czworokącie tego prefab.

Poniżej przedstawiono przykład, w którym prefab webSlate został dodany do sceny i przypisany adres URL:

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

Przykład webSlate

Nasłuchiwanie kliknięć

Oto prosty skrypt skryptów chmury usługi Mesh, który obraca moduł za każdym razem, gdy jest klikany. Zastąp metodę wycinkową StartAsync wewnątrz App.cs tym kodem.

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

Informacje o trafieniu

Można dowiedzieć się, który użytkownik kliknął zderzacz, patrząc na argumenty zdarzenia zmiany właściwości. Można również odczytać normalny kontakt i położenie kliknięcia z argumentów zdarzenia. Te współrzędne będą względne względem lokalnej przestrzeni współrzędnych węzła InteractableNode.

Animatorów

Możesz utworzyć i dodać animację aparatu Unity do sceny i kontrolować ją za pomocą usługi Mesh Cloud Scripting. Wtyczka zestawu narzędzi usługi Mesh będzie przeglądać zasoby w projekcie aparatu Unity, a dla każdego znalezionego animatora wygeneruje klasę w folderze "AnimationScripts" w projekcie Mesh Cloud Scripting. Ta klasa pochodzi z AnimationNode i może służyć do kontrolowania animatora z usługi Mesh Cloud Scripting. Po dodaniu animatora jako składnika do obiektu gry w a unity znajdziesz odpowiednie wystąpienie wygenerowanej klasy jako element podrzędny odpowiedniego węzła TransformNode. Przy użyciu interfejsu API tej klasy możesz kontrolować animatora.

Model programowania Mesh Cloud Scripting jest autorytatywny dla serwera i obsługujemy tylko niewielki podzbiór funkcji Animator. Dzieje się tak, ponieważ modelujemy animatora na serwerze i oczekujemy, że wszyscy klienci będą dokładnie synchronizować się z modelem serwera. Z tego powodu obecnie obsługiwany jest tylko następujący interfejs API:

  • Ustawienie stanu (dla każdej warstwy istnieje odpowiednia właściwość w klasie, którą można ustawić na wyliczenie na podstawie dostępnych stanów w Programie Animator). Stany są ustawiane natychmiast, a nie przez przejścia.
  • Ustawienie zmiennej zmiennoprzecinkowej: uwidocznione są tylko zmienne zmiennoprzecinkowe i tylko w celu powiązania z "Motion Time" w animacji.
  • Ustawienie szybkości warstwy

W stanie można utworzyć klip animacji bez ograniczeń dotyczących wartości, które można ustawić w scenie aparatu Unity. Obsługiwane są również klipy animacji w pętli. Następujące funkcje animatorów nie są obsługiwane za pośrednictwem węzłów AnimationNodes:

  • Przejścia: w przypadku dodawania przejść do usługi Animator nie będzie można ich wyzwolić za pomocą interfejsu API tworzenia skryptów w chmurze usługi Mesh (serwer nie przechodzi w modelu).
  • Zmienne (inne niż zmiennoprzecinkowe do kierowania czasem ruchu). Zmienne używane do napędzania logiki przejścia lub mnożników szybkości nie są obsługiwane.
  • Stany dublowane, Przesunięcie cyklu i IK stóp.

Późne sprzężenia i animatorzy

Gdy klienci dołączają do zdarzenia usługi Mesh, synchronizują się z bieżącym stanem i czasem lokalnym wszystkich uruchomionych węzłów animacji. Jeśli masz długotrwałą animację odtwarzaną w stanie, czas odtwarzania zostanie ustawiony na prawidłowy bieżący czas animacji przy opóźnieniu sprzężenia. Jeśli jednak stan zostanie wyzwolony, nie zostaną one wyzwolone w kliencie dołączonym z opóźnieniem. Niektóre inne scenariusze mogą nie działać zgodnie z oczekiwaniami; jeśli na przykład wyzwolisz dźwięk, włączając element AudioSource na początku stanu, usługa AudioSource będzie nadal włączona w kliencie późnego dołączania, ale rozpocznie odtwarzanie na początku klipu audio.

Stan początkowy animatora

Zalecamy tworzenie animatorów, które mają stany domyślne, które nic nie robią. Gdy scena zacznie grać w a unity, aktywuje wszystkich Animatorów i rozpocznie odtwarzanie ich domyślnych animacji. Może się to zdarzyć przed wystąpieniem połączenia usługi Mesh Cloud Scripting Service; w związku z tym nie ma możliwości synchronizacji tych stanów i zachowania może nie być tak pożądane.

Reparenting i klonowanie animatora

Nie można utworzyć węzłów AnimationNode za pomocą interfejsu API tworzenia skryptów w chmurze usługi Mesh. Jedynym sposobem utworzenia elementu AnimationNode jest wyeksportowanie sceny aparatu Unity zawierającej składnik Animator. Jeśli spróbujesz sklonować lub ponownie utworzyć element AnimationNode, wystąpi błąd, ponieważ nie ma możliwości obsługi tej akcji. Nadal istnieje możliwość sklonowania lub ponownego sklonowania nadrzędnego węzła AnimationNode, ponieważ odpowiada to zawierającemu obiektowi gry aparatu Unity, który można sklonować i wywzorować.

Uwagi dotyczące wygenerowanego kodu

Wygenerowany kod usunie spacje z nazw animatorów, warstw, stanów i zmiennych; na przykład nazwa zmiennej "my var" staje się "myVar" w kodzie. W związku z tym można utworzyć animatorów, którzy nie będą generować prawidłowego kodu. Jeśli na przykład masz dwie zmienne o nazwie "my var" i "myVar", podczas generowania wystąpi błąd i zostanie wyświetlony komunikat z prośbą o zmianę nazw zmiennych.

LightNode

Wszystkie mapy PointLightNode, DirectionalLightNode i SpotLightNode do składnika Unity Light (który będzie miał jego typ ustawiony na odpowiednią wartość). Można ustawić podstawowe parametry tych świateł za pomocą interfejsów API LightNode. Można również utworzyć światła ręcznie za pomocą interfejsu API. Tworzenie węzłów świetlnych za pośrednictwem interfejsu API spowoduje pozostawienie parametrów, które nie są ustawiane za pomocą interfejsu API skryptów w chmurze usługi Mesh do wartości domyślnych.

GeometryNode

BoxGeometryNode, SphereGeometryNode, CapsuleGeometryNode i MeshGeometryNode są mapami odpowiednio na składnik Box Collider Aparatu Unity, składnik zderzaczy sphere, składnik zderzacz kapsułek i składnik zderzacz siatki. Można je również utworzyć za pomocą interfejsu API tworzenia skryptów w chmurze usługi Mesh. Włączenie i wyłączenie węzłów geometrycznych spowoduje dodanie i usunięcie ich z kandydatów trafień, jeśli element MeshInteractableSetup jest dołączony do ich obiektu gry lub jednego z jego elementów nadrzędnych.

Tworzenie węzłów geometrycznych za pomocą interfejsu API spowoduje pozostawienie parametrów, które nie są ustawiane za pośrednictwem interfejsu API usługi Mesh do wartości domyślnych (na przykład dla materiału fizycznego zostanie ustawiona wartość none, a parametr isTrigger zostanie ustawiony na wartość false).

RigidBodyNode

Dodanie składnika Sztywna osoba do obiektu spowoduje umieszczenie ruchu pod kontrolą fizyki siatki. Bez dodawania kodu obiekt Rigidbody zostanie pociągnięty w dół przez grawitację i będzie reagować na kolizje z innymi obiektami.

Uwaga: GeometryNode.Friction zwróci wartość staticFriction. Jeśli jednak zostanie ono ustawione po stronie skryptów chmury usługi Mesh, zaktualizuje zarówno klienta, jak staticFriction i dynamicFriction na klientach.

Wyzwalanie woluminów

Węzły geometryczne mogą działać jako woluminy wyzwalacza, gdy ich IsTrigger właściwość jest ustawiona na wartość true. Ta flaga IsTrigger odpowiada właściwości zderzaczemu w a unity i nie można jej zmienić w czasie wykonywania. Gdy geometria jest wyzwalaczem, zostanie wygenerowana Entered i Exited dla wszystkich awatarów, które zaczynają się/przestają nakładać się na nią.

Uwaga: obiekt Aparatu Unity należy dodać do TriggerVolume warstwy, aby umożliwić ignorowanie wiązki teleportu, ponieważ zderzacze w warstwie Default blokują belkę teleportu.

TextNode

TextNode mapuje na składnik TextMeshPro aparatu Unity. Jeśli dodasz składnik TextMeshPro do sceny, w hierarchii sceny skryptów w chmurze usługi Mesh pojawi się odpowiedni element TextNode. Dzięki temu można ustawić tekst składnika w czasie wykonywania. Możesz również zmienić podstawowe właściwości tekstu za pomocą interfejsu API TextNode — pogrubienia, kursywy, podkreślenie, przekreślenie i kolor. Obecnie nie można utworzyć węzła TextNode za pomocą interfejsu API; należy je utworzyć, dodając je do sceny w a środowisku Unity. Ponadto nie można bezpośrednio sklonować węzła TextNode — zamiast tego należy sklonować nadrzędny element TranformNode węzła TextNode.

Siatki

Siatki są obecnie "ukryte" składniki interfejsu API tworzenia skryptów w chmurze usługi Mesh. Można je tworzyć w edytorze aparatu Unity i można nimi manipulować, manipulując ich nadrzędnymi obiektami gier/składnikami transformowania, ale nie można ich tworzyć programowo ani edytować ich właściwości w czasie wykonywania za pomocą interfejsu API usługi Mesh.

Inne tematy dotyczące skryptów chmury usługi Mesh

Dodawanie zasobów do usługi Mesh Cloud Scripting Service

Jeśli musisz dodać zasób dla usługi Mesh Cloud Scripting Service do użycia, musisz dodać go jako zasób osadzony do pliku projektu C#. Można to zrobić za pomocą interfejsu użytkownika projektu w programie Visual Studio lub bezpośrednio dodając następujący wiersz do pliku csproj:

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

Należy pamiętać, że w ten sposób jest spakowany plik scene.map, który można zobaczyć w pliku csproj w celu uzyskania informacji.

Praca z fizyką siatki

Mesh Physics będzie dbać o synchronizację ruchu sztywnych ciał między klientami. Usługa Mesh Cloud Scripting TransformNode.Position, RigidBody.VelocityTransformNode.Rotationi RigidBody.AngularVelocity nie zostanie zaktualizowana o najnowszy stan symulacji. Jednak klienci będą stosować zmiany, jeśli są one ustawione w usłudze Mesh Cloud Scripting Service. Należy pamiętać, że zmiana pojedynczej właściwości pozostawi inne niezmienione. Na przykład jeśli tylko pozycja jest ustawiona, prędkość nie zostanie zmieniona, a sztywna treść będzie kontynuować ruch ze starą prędkością z nowej pozycji. Biorąc pod uwagę, że usługa Mesh Cloud Scripting Service nie jest aktualizowana przy użyciu najnowszego stanu ruchu dla sztywnych ciał, zaleca się ustawienie ich tylko dla nowych sztywnych ciał.

RigidBodyNode W przypadku TransformNode klonowania sklonowana treść zostanie zarejestrowana i przekazana do Mesh Physics synchronizacji między klientami. Uwaga: Sklonowana sztywna treść będzie miała położenie, rotację i prędkości od początku sceny oryginalnego sztywnego ciała. Jeśli powinny one być inne, należy je jawnie ustawić w usłudze Mesh Cloud Scripting.

Następne kroki