Průvodce programátorem cloudových skriptů

Tato příručka popisuje, jak pomocí rozhraní API cloudových skriptování mesh a vývojářských nástrojů vytvářet prostředí (ty začínají jako projekty v Unity a pak se nahrají do kolekce Mesh). Doporučujeme, abyste si nejdříve přečetli infrastrukturu set cloud Scripting v Azure , abyste se seznámili s koncepty a základní architekturou cloudových skriptů mesh.

Tato část popisuje funkce a rozhraní rozhraní rozhraní MESH Cloud Scripting API, které se používá k zápisu skriptů, které řídí chování v prostředích.

Základní struktura DOM

Struktura DOM zrcadlí strukturu scény Unity. Člen scény aplikace odpovídá hernímu objektu, ke kterému je připojena komponenta Mesh Cloud Scripting. Následující třídy rozhraní API cloudových skriptů mesh mapují 1:1 s objekty Unity vytvořenými v editoru:

• GameObject (komponenta&transformace) –> TransformNode
• Light Component –> PointLightNode, SpotLightNode, DirectionalLightNode
• Animator Component –> AnimationNode (a odvozené třídy, viz níže)
• Součást sbalovače boxů –> BoxGeometryNode
• Komponenta spletiče Sphere –> SphereGeometryNode
• Komponenta skládací kapsle -> CapsuleGeometryNode
• Komponenta spletiče mesh –> MeshGeometryNode
• Komponenta Text Mesh Pro –> TextNode
• Pevná komponenta –> RigidBodyNode

Pokud například vytvoříte scénu s herním objektem, který má komponentu Light (nastavenou na bodové světlo) a připojenou kulisu, bude vaše scéna obsahovat TransformNode se dvěma podřízenými objekty: PointLightNode a SphereGeometryNode.

Některé objekty rozhraní API cloudových skriptů Mesh navíc nemají odpovídající předdefinované komponenty Unity. Jedná se o další komponenty, které můžete vytvořit v Unity, které jsou součástí balíčku sady nástrojů Mesh.

• Komponenta Mesh Cloud Scripting (popsaná výše)
• Komponenta WebSlate

Mapování modelu Unity DOM na modelu DOM Mesh

Můžete vytvořit scénu s komponentami, o kterých rozhraní MESH Cloud Scripting API neví. Tyto objekty prostě nebudou existovat ve skriptovacím systému Mesh Cloud DOM pro scénu. Struktura celé scény GameObjects se však bude zrcadlit v rozhraní API DOM jako TransformNodes.

Unity má tvar rozhraní API GameObject/komponent; Skriptovací objekt DOM mesh cloud však má jednu stromovou strukturu. Uzel TransformNode ve skriptovacím rozhraní API cloudu Mesh má podřízené položky, které můžou být jiné uzly TransformNode nebo jiné uzly, které se mapují na komponenty. Můžeme zvážit sloučený seznam komponent přidruženého herního objektu a dětí jeho transformační komponenty.

Transformace rect

Pokud přidáte komponentu, která používá rectTransform ( například komponentu Text Mesh Pro), herní objekt se v grafu scény Skriptování cloudu Mesh nezobrazí jako uzel. Přesto je možné tuto komponentu přesunout, povolit a zakázat, ale k tomu je potřeba zabalit herní objekt pomocí funkce RectTransform v jiném herním objektu pomocí běžné součásti Transformace.

Události změny vlastnosti

Události změny vlastností můžete přihlásit k odběru voláním AddPropertyChangedEventHandler na libovolný uzel v hierarchii. Název vlastnosti musíte předat jako řetězec.

Můžete se také přihlásit k odběru všech událostí přihlášením k odběru DomObjectPropertyChanged události. To se volá, když se změní jakákoli vlastnost v dom.

Životní cyklus objektu

Uzly při vytváření nejsou oddělené. To znamená, že se ve scéně nezobrazí, dokud nebudou explicitně přidáni jako dítě do scény nebo jednoho z jeho potomků. Podobně nastavení nadřazeného uzlu na hodnotu null ho odebere a jeho potomky ze scény.

Někdy chcete uzel dočasně zakázat, ale nechcete uchovávat záznam o tom, kde byl ve scéně. Z tohoto důvodu má každý uzel příznak "aktivní". Když je nastavená hodnota false, zakáže uzel a jeho potomky.

V Unity můžete vytvářet herní objekty a komponenty, které jsou součástí scény, ale jsou zakázané. Zobrazí se jako uzly v hierarchii scény skriptování cloudu mesh, ale jejich aktivní příznak bude nastaven na false. Nastavení aktivního příznaku na true je povolí ve scéně Unity.

Klonování a opakované načítání

Uzly je možné naklonovat a znovu načíst v rozhraní MESH Cloud Scripting API; odpovídající scéna Unity se odpovídajícím způsobem aktualizuje. Pokud naklonujete uzel, naklonuje tento uzel a všechny jeho podřízené položky (včetně podřízených položek, které můžou být v odpovídajících objektech Unity, ale nejsou viditelné pro Skriptování cloudu Mesh).

Je možné klonovat nebo znovu naklonovat uzly, které odpovídají komponentám Unity. To se implementuje tak, že tyto komponenty Unity znovu vytvoříte na základě reprezentací uzlů Skriptování cloudu Mesh. Klonovat nebo znovu naklonovat lze pouze uzly, které je možné vytvořit prostřednictvím rozhraní API pro skriptování cloudu Mesh. Pokud jste vytvořili komponentu v Unity a nastavili pole, která se neprojeví v odpovídajícím uzlu skriptování cloudu Mesh, budou tato pole v případě klonování samotného uzlu resetována na výchozí hodnoty. Z tohoto důvodu doporučujeme klonovat nebo znovu naklonovat uzly transformace, kde manipulujete s objekty vytvořenými v Unity. Vždy se zachová všechna původní nastavení Unity.

Uživatelé

V rozhraní API jsou různá místa, která poskytují vlastnosti uživatele. Vlastnost User.Identifier je řetězec trvalého identifikátoru, který je trvalý pro uživatele, i když uživatel odejde a znovu se připojí. Zobrazované jméno uživatele je přístupné také prostřednictvím User.DisplayName. ID události, ze které se uživatel připojil, je přístupné prostřednictvím User.ConnectedEventId.

Během vývoje zobrazovaného jména, identifikátoru a ID události je možné v editoru komponent Skriptování cloudu Mesh v editoru vývojářských nastavení napodobovat, jak je znázorněno níže.

Avatary

Avatary představují reprezentaci uživatelů ve scéně. Dají se použít k teleportaci uživatelů do daného umístění, cestování mezi scénami a k detekci kolizí s aktivačními svazky.

Informační dialogy

Ve skriptování Mesh Cloud je možné v aplikaci Microsoft Mesh s vlastní zprávou zobrazit dialogové okno s místem na obrazovce. SceneNode obsahuje funkci pro tuto funkci. ShowMessageToParticipants(string message, IReadOnlyCollection<Participant> participants) Značky rtf textu lze ve zprávě použít k řízení vlastností textu (barva, tučné atd.).

Vstupní dialogy

Skriptování cloudových sítí může požadovat zadání textu od účastníka v události Mesh s vlastní zprávou. CloudApplication poskytuje metodu Task<string> ShowInputDialogToParticipantAsync(string message, Participant participant, CancellationToken token). Značky rtf textu lze ve zprávě použít k řízení vlastností textu (například barva nebo tučné písmo).

Třídy

CloudApplication

Rozhraní ICloudApplication je výchozím bodem pro vývoj aplikací Mesh. Je k dispozici v App.cs jako proměnná _app. Kromě scény ICloudApplication obsahuje funkce pro všechny dostupné typy. Má také řadu dalších metod, ale jsou určené pro interní použití.

InteragableNode

MeshInteractableSetup je vlastní komponenta Unity, která je součástí balíčku Mesh toolkit. Když ho připojíte k hernímu objektu v Unity, vyvolá události kliknutí, když některý uživatel klikne na některý z aktivních kolidovatelných objektů hry nebo jeho dětí.

Níže je uveden jednoduchý příklad, kde je komponenta MeshInteractableSetup přidána do stejného herního objektu jako kompleter pole:

WebSlateNode

WebSlate je vlastní komponenta Unity, která je součástí balíčku sady nástrojů Mesh. Pokud chcete do scény přidat prefab webSlate, vyberte WebSlate GameObject>Mesh Toolkit>WebSlate z řádku nabídek. Web, který je přiřazen k vlastnosti URL instance WebSlate, se zobrazí na čtyřúhelníku tohoto prefabu.

Příklad je uvedený níže, kde byl do scény přidán prefab webSlate a přiřazena adresa URL:

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

Naslouchání kliknutím

Tady je jednoduchý skript Cloud Mesh, který při každém kliknutí otočí datovou krychli. Nahraďte metodu zástupných procedur StartAsync uvnitř App.cs tohoto kódu.

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

Informace o přístupech

Pokud chcete zjistit, který uživatel klikl na sbajt, podívejte se na argumenty události změny vlastnosti. Můžete si také přečíst normální kontakt a pozici kliknutí z argumentů události. Tyto souřadnice budou relativní vzhledem k místnímu souřadnicovém prostoru interagovatelného uzlu.

Animátorů

Do scény můžete vytvořit a přidat Animator Unity a řídit ho prostřednictvím skriptování Cloud Mesh. Modul plug-in Mesh toolkit bude hledat prostředky v projektu Unity a pro každý nalezený animátor vygeneruje třídu ve složce AnimationScripts v projektu Mesh Cloud Scripting. Tato třída je odvozena z AnimationNode a lze použít k řízení Animator z Mesh Cloud Scripting. Když přidáte Animator jako součást do herního objektu v Unity, najdete odpovídající instanci vygenerované třídy jako podřízený objektu TransformNode. Pomocí rozhraní API této třídy můžete ovládat Animator.

Programovací model Skriptování cloudu Mesh je autoritativní a podporujeme pouze malou podmnožinu funkcí Animatoru. Je to proto, že modelujeme Animator na serveru a očekáváme, že se všichni klienti budou přesně synchronizovat s modelem serveru. Z tohoto důvodu se v současné době podporuje pouze následující rozhraní API:

• Nastavení stavu (pro každou vrstvu existuje odpovídající vlastnost třídy, která může být nastavena na výčet na základě dostupných stavů v Animatoru). Stavy se nastavují okamžitě, ne prostřednictvím přechodů.
• Nastavení plovoucí proměnné: Jsou vystaveny pouze plovoucí proměnné a pouze pro účely vazby na "Čas pohybu" v Animatoru.
• Nastavení rychlosti vrstvy

Ve stavu můžete vytvořit animační klip bez omezení, jaké hodnoty můžete nastavit ve scéně Unity. Podporují se také klipy animací smyček. Animátory nejsou podporovány pomocí animátorů:

• Přechody: Pokud do animátoru přidáte přechody, nebudete je moct aktivovat prostřednictvím rozhraní MESH Cloud Scripting API (server neprovádí přechody modelu).
• Proměnné (jiné než plováky pro řízení doby pohybu) Proměnné používané k řízení logiky přechodu nebo násobení rychlosti se nepodporují.
• Zrcadlené stavy, posun cyklu a IK nohy.

Pozdní spojení a animátory

Když se klienti připojí k události mesh, synchronizují se s aktuálním stavem a místním časem všech spuštěných uzlů animace. Pokud máte ve stavu přehrávání dlouhotrvající animace, nastaví se doba přehrávání na správný aktuální čas animace při pozdním spojení. Pokud však váš stav aktivuje události, tyto události se neaktivují v pozdním připojeném klientovi. Některé jiné scénáře nemusí fungovat podle očekávání; Pokud například aktivujete zvuk tak, že povolíte AudioSource na začátku stavu, bude zvukový zdroj stále povolený v klientovi pozdního připojení, ale začne se přehrávat na začátku zvukového klipu.

Počáteční stav Animatoru

Doporučujeme vytvořit animátory s výchozími stavy, které nedělají nic. Když se scéna začne přehrávat v Unity, aktivuje se všechny animátory a začne přehrávat výchozí animace. K tomu může dojít dříve, než dojde ke službě Mesh Cloud Scripting Service; proto neexistuje způsob, jak synchronizovat tyto stavy a chování podle potřeby.

Opětovné naklonování a klonování animatoru

AnimationNodes nelze vytvořit prostřednictvím rozhraní MESH Cloud Scripting API. Jediným způsobem, jak vytvořit AnimationNode, je exportem scény Unity, která obsahuje komponentu Animatoru. Pokud se pokusíte naklonovat nebo znovu spustit AnimationNode, zobrazí se chyba, protože neexistuje způsob, jak tuto akci podporovat. Stále je možné naklonovat nebo znovu naklonovat nadřazenou položku AnimationNode, protože to odpovídá objektu Unity Game Object, který lze klonovat a nadřazený.

Poznámky ke vygenerovanému kódu

Vygenerovaný kód odebere mezery z názvů animátorů, vrstev, stavů a proměnných; Například název proměnné "my var" se v kódu změní na "myVar". Z tohoto důvodu je možné vytvořit animátory, které negenerují platný kód. Pokud máte například dvě proměnné s názvem "my var" a "myVar", zobrazí se během generování chyba a zpráva s výzvou k přejmenování proměnných.

LightNode

PointLightNode, DirectionalLightNode a SpotLightNode všechny mapuje na komponentu Unity Light (která bude mít typ nastaven na odpovídající hodnotu). Základní parametry těchto světel je možné nastavit prostřednictvím rozhraní API LightNode. Světla je také možné vytvořit ručně prostřednictvím rozhraní API. Vytváření světlých uzlů prostřednictvím rozhraní API ponechá parametry, které nejsou nastavené prostřednictvím rozhraní API pro skriptování cloudu Mesh na výchozí hodnoty.

GeometryNode

BoxGeometryNode, SphereGeometryNode, CapsuleGeometryNode a MeshGeometryNode mapovat na komponentu Box Collider Komponenty Unity, Komponentu spletiče Sphere, komponentu spletiče kapsle a komponentu Sbalit mesh v uvedeném pořadí. Dají se také vytvořit prostřednictvím rozhraní MESH Cloud Scripting API. Pokud je objekt MeshInteractableSetup připojený k hernímu objektu nebo některému z jeho nadřazených objektů, povolíte a zakážete uzly geometrie, přidají se a odeberou z nich přístupové kandidáty.

Vytváření uzlů geometrie prostřednictvím rozhraní API ponechá parametry, které nejsou nastaveny prostřednictvím rozhraní MESH API na výchozí hodnoty (například fyzika materiál bude nastaven na žádný a isTrigger bude nastaven na false).

RigidBodyNode

Přidání ztuhlé součásti do objektu umístí jeho pohyb pod kontrolu Fyzika sítě. Bez přidání jakéhokoli kódu bude objekt Rigidbody stažen dolů závažností a bude reagovat na kolize s jinými objekty.

Poznámka: GeometryNode.Friction vrátí staticFriction. Pokud je ale nastavená na straně skriptování cloudu Mesh, aktualizuje se jak na klientech, tak staticFriction dynamicFriction i na klientech.

Aktivační svazky

Uzly geometrie můžou fungovat jako aktivační svazky, pokud je jejich IsTrigger vlastnost nastavena na true. Tento příznak odpovídá IsTrigger vlastnosti v kolaci v Unity a nelze ji změnit za běhu. Když je geometrie triggerem, vygeneruje Entered se a Exited pro všechny avatary, které se s ní začnou nebo přestanou překrývat.

Poznámka: Objekt Unity je potřeba přidat do TriggerVolume vrstvy, aby ho teleportový paprsek ignoroval, protože kolače ve Default vrstvě blokují teleportový paprsek.

Textový uzel

TextNode se mapuje na komponentu TextMeshPro Unity. Pokud do scény přidáte komponentu TextMeshPro, bude v hierarchii scény skriptování Mesh Cloud existovat odpovídající uzel TextNode. To vám umožní nastavit text komponenty za běhu. Základní vlastnosti textu můžete také změnit prostřednictvím rozhraní API uzlu TextNode – tučné písmo, kurzíva, podtržení, přeškrtnutí a barva. V současné době není možné vytvořit textový uzel prostřednictvím rozhraní API; musíte je vytvořit tak, že je přidáte do scény v Unity. Objekt TextNode také nemůžete naklonovat přímo – musíte místo toho naklonovat nadřazený uzel TextNode TranformNode.

Sítě

Meshes are currently "hidden" components to the Mesh Cloud Scripting API. Dají se vytvořit v editoru Unity a dají se manipulovat s nadřazenými herními objekty nebo komponentami transformace, ale nedají se vytvářet programově, ani je nelze upravovat za běhu prostřednictvím rozhraní MESH API.

Vizuální skripty

Skriptovací počítač Unity můžete vytvořit a přidat do scény a řídit ho prostřednictvím cloudových skriptů Mesh. Modul plug-in Mesh toolkit bude procházet prostředky v projektu Unity a pro každý nalezený skriptovací počítač vygeneruje třídu ve složce VisualScripts ve vašem projektu Skriptování cloudu Mesh. Tato třída je odvozena z VisualScriptNode a lze použít k manipulaci s proměnnými Unity přidruženými k script machine z Mesh Cloud Scripting. Když do Objektu GameObject v Unity přidáte skriptovací počítač jako součást, najdete odpovídající instanci vygenerované třídy jako podřízenou instanci odpovídajícího objektu TransformNode. Pomocí rozhraní API této třídy můžete řídit proměnné skriptu počítače.

Synchronizace stavu

Ve výchozím nastavení služba Mesh automaticky replikuje změny scény provedené vizuálními skripty na jednom klientovi do všech ostatních klientů. Aby služba Mesh Cloud Scripting věděla o změně provedené prostřednictvím vizuálního skriptování, musí být splněny následující předpoklady:

• Komponenta Skriptovací počítač je na Objektu GameObject, který je následníkem kořene scény Skriptování cloudu Mesh.
• Je povolená možnost Povolit skriptování vizuálů komponenty Mesh Cloud Scripting.

Pokud některá z výše uvedených podmínek není splněná, skriptovací modul runtime vizuálního skriptování mesh bude i nadále replikovat změny scény, ale skriptování mesh cloudu zůstane pro tyto změny nepochopné.

Počáteční stav

Doporučujeme, aby se vaše vizuální skripty při spuštění neupravily ani nespoléhaly na sdílený stav. Událost Při spuštění obvykle nastane dříve, než dojde k připojení služby Cloud Scripting Service mesh. Proto neexistuje způsob, jak v daném okamžiku synchronizovat stav a chování nemusí být to, co si přejete.

Pozdní spojení

Když se klienti připojí k události Mesh, synchronizují se s aktuálním stavem všech uzlů vizuálních skriptů. Jakákoli událost Změny stavu, která byla dříve vyvolána na ostatních klientech, nebude vyvolána v pozdním připojeném klientovi. Některé jiné scénáře nemusí fungovat podle očekávání; Pokud například aktivujete zvuk tak, že povolíte AudioSource v reakci na událost On State Changed , audioSource bude stále povolen v klientovi pozdního připojení, ale začne přehrávat na začátku zvukového klipu.

Přeučování a klonování

VisualScriptNode nelze vytvořit prostřednictvím rozhraní API pro skriptování cloudu Mesh. Jediným způsobem, jak vytvořit VisualScriptNode, je export scény Unity, která obsahuje komponentu Script Machine. Pokud se pokusíte naklonovat nebo znovu použít VisualScriptNode, zobrazí se chyba, protože neexistuje způsob, jak tuto akci podporovat. Stále je možné klonovat nebo znovu naklonovat nadřazenou položku VisualScriptNode, protože to odpovídá objektu Unity GameObject, který lze klonovat a nadřazený.

Poznámky ke vygenerovanému kódu

Vygenerovaný kód odebere mezery z názvů skriptových počítačů a proměnných; Například název proměnné "my var" se v kódu změní na "MyVar". Z tohoto důvodu je možné vytvořit skriptovací počítače, které negenerují platný kód. Pokud máte například dvě proměnné s názvem "my var" a "myVar", zobrazí se během generování chyba a zpráva s výzvou k přejmenování proměnných.

Další témata týkající se skriptování cloudových sítí

Přidání prostředků do služby Skriptování cloudu Mesh

Pokud potřebujete přidat prostředek, který chcete použít pro cloudovou skriptovací službu Mesh, musíte ho přidat jako vložený prostředek do souboru projektu C#. Můžete to provést pomocí uživatelského rozhraní projektu v sadě Visual Studio nebo přidáním následujícího řádku přímo do souboru .csproj:

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

Všimněte si, že toto je způsob balení scene.map, který můžete vidět v souboru .csproj pro referenci.

Práce s fyzikou mesh

Mesh Physics se postará o synchronizaci pohybu pevných těles mezi klienty. Mesh Cloud Scripting TransformNode.Position, TransformNode.RotationRigidBody.Velocity a RigidBody.AngularVelocity nebude aktualizován s nejnovějším stavem simulace. Pokud jsou však klienti nastaveni ve službě Skriptování cloudu Mesh, použijí změny. Všimněte si, že změna jedné vlastnosti ponechá ostatní beze změny. Pokud je například nastavena pouze pozice, rychlost se nezmění a pevné tělo bude pokračovat v pohybu se starou rychlostí z nové pozice. Vzhledem k tomu, že Služba skriptování cloudu Mesh není aktualizována s nejnovějším stavem pohybu pevných těles, doporučujeme je nastavit pouze pro nové pevné těla.

RigidBodyNode Pokud TransformNode se naklonuje, naklonované tělo se zaregistruje a předá Mesh Physics synchronizaci mezi klienty. Poznámka: Klonované pevné tělo bude mít pozici, otáčení a rychlosti od začátku scény původního tuhého těla. Pokud se mají lišit, musí být nastavené explicitně ve skriptování Cloud Mesh.

Další kroky

Infrastruktura a správa cloudových skriptů