Modele proceduralne

ProceduralModels to typ modeli sterowanych parametrami Model, który pozwala na budowanie i generowanie obiektów 3D przy użyciu kodu. Zamiast ręcznie edytować zawartość modelu, definiujesz jego strukturę za pomocą modułu generatora i zestawu atrybutów. Gdy te atrybuty się zmieniają lub gdy model jest zmieniany pod względem rozmiaru, generator automatycznie działa, aby zaktualizować model.

Modele proceduralne ułatwiają:

• Nieniszczące dostosowywanie modeli poprzez zmianę parametrów zamiast ich odbudowy. Na przykład zmiana wartości StepSize na spiralnych schodach automatycznie regeneruje schody z zaktualizowaną liczbą stopni.
• Automatyczną integrację z istniejącymi systemami Studio, takimi jak cofanie/ponawianie, Team Create i narzędzia do przeciągania, poprzez implementację jednej funkcji OnGenerate.
• Utrzymanie wysokiej wydajności, przy czym modele zachowują się jak standardowe obiekty, dopóki ich parametry się nie zmienią.
• Generowanie treści zarówno w czasie edycji, jak i w czasie wykonywania, korzystając z tego samego systemu w Studio i w grze.
• Udostępnianie parametrów modelu w Sklepie Twórcy, co sprawia, że zasoby są bardziej elastyczne i konfigurowalne.

Wstawianie modeli proceduralnych

Możesz dodać modele proceduralne do swojej gry na następujące sposoby:

• Ręcznie wstaw obiekt ProceduralModel do Workspace. Ta opcja zawiera szablon generatora ModuleScript, który pomoże ci zacząć.

  

• Wygeneruj model proceduralny za pomocą Asystenta lub serwera MCP Roblox Studio.

• Wstaw model proceduralny ze Sklepu Twórcy, aby użyć lub dostosować istniejący model.

Aby dostosować sposób, w jaki modele proceduralne są generowane, możesz zdefiniować własne moduły generatorów.

Funkcja OnGenerate

Funkcja OnGenerate jest rdzeniem każdego ProceduralModel w postaci OnGenerate(params, targetContainer).

Ta zdefiniowana przez dewelopera funkcja odpowiada za generowanie zawartości modelu na podstawie podanych parametrów oraz zapisywanie wyników w podanym kontenerze.

OnGenerate ma dwa główne zadania:

• Przetwarzać dostarczone parametry, aby określić strukturę modelu
• Zapiszać wygenerowane wyniki zgodnie z tą strukturą w podanym targetContainer

Poniższe sekcje opisują:

• Kiedy i jak silnik wywołuje OnGenerate
• Jak silnik przetwarza zawartość zapisaną w targetContainer

Moduły generatorów

Funkcja OnGenerate jest zdefiniowana w ModuleScript znanym jako moduł generatora. ProceduralModel identyfikuje, który moduł generatora używać poprzez swoją właściwość Generator.

Moduły generatorów są standardowymi modułami Luau, ale są wymagane bezpośrednio przez silnik jako część procesu generacji. Podążają one za określoną strukturą i zwracają tabelę ze znormalizowanymi polami.

Struktura modułu generatora
local MyGenerator = {}

MyGenerator.Attributes = {
    DoSomething = true,
    AmountOfSomething = 137,
}

type Params = {
    Size: Vector3,
    Attributes: typeof(MyGenerator.Attributes),
    Pause: (self: any) -> (),
}
function MyGenerator.OnGenerate(params: Params, targetContainer: GeneratedFolder)
    
end

return MyGenerator

Znormalizowane pola obejmują:

• Attributes: Mapa definiująca nazwy parametrów i ich wartości domyślne.
• OnGenerate: Funkcja, która otrzymuje tabelę params i targetContainer.

Tabela params wewnątrz OnGenerate obejmuje:

• Attributes: Tabela, która zawiera atrybuty zdefiniowane przez moduł lub wszystkie atrybuty modelu, jeśli żadne nie są określone.
• Size: Parametr, który odzwierciedla wymiary modelu w skali jeden.
• Pause: Metoda, która umożliwia efektywne przerwanie generacji podczas skomplikowanych zadań generacyjnych.

Funkcja OnGenerate powinna generować treść w okolicy pochodzenia w targetContainer. Nie powinna bezpośrednio modyfikować głównej hierarchii DataModel.

Parametry

Parametry to dane wejściowe, które kontrolują generację. Obejmują one wbudowaną właściwość Size modelu proceduralnego, a także niestandardowe atrybuty określone w module generatora. Te jawne parametry są przekazywane bezpośrednio do OnGenerate. Implikowane parametry, takie jak kod źródłowy modułu lub status sandboxingu, również wyzwalają regenerację, kiedy się zmieniają, ale nie są przekazywane do OnGenerate.

Pełny zestaw parametrów obejmuje:

• Jawne:

  • Size: Określa obszar wokół pochodzenia, w którym generowana jest zawartość.
  • Attributes: Mapa zawierająca aktualne wartości atrybutów wejściowych.
• Implikowane:

  • Generator: Moduł, który dostarcza logikę generacji.
  • Kod źródłowy: Zmiany w kodzie Luau modułu generatora.
  • Sandboxing: Zmiany w statusie sandboxingu modułu generatora.

Zachowanie regeneracji

Aby utrzymać wydajność i uprościć interakcje z API, OnGenerate nie jest wywoływane natychmiast po zmianie parametrów. Zamiast tego ProceduralModel jest oznaczany jako brudny, co wskazuje, że regeneracja jest oczekiwana. Ta oczekująca regeneracja zazwyczaj następuje później w tym samym klatce.

Jeśli regeneracja się nie powiedzie, stan brudny jest czyszczony, aż wystąpi kolejna zmiana parametru. Jeśli miejsce jest zapisane, gdy model jest brudny, stan ten utrzymuje się i model jest dodawany do kolejki generacji przy następnym uruchomieniu gry.

Proces wykonania

Podczas gdy czas przetwarzania jest dostępny, silnik regeneruje brudne modele, wykonując następujące kroki:

1. Wymaga moduł generatora, zatrzymując, jeśli to konieczne.
2. Rozpoczyna nowy wątek dla procesu generacji.
3. Buduje tabelę parametrów, normalizując Size według aktualnej skali modelu.
4. Zastosowuje domyślne wartości atrybutów do brakujących atrybutów.
5. Inicjalizuje tymczasowy GeneratedFolder jako targetContainer.
6. Wywołuje OnGenerate.
7. Po powrocie OnGenerate:

   • Jeśli zakończono sukcesem, migruje wyniki z targetContainer do ProceduralModel.
   • Jeśli generacja się nie powiedzie, zamiast tego używa substytutu błędu.

Jeśli parametry zmieniają się ponownie podczas, gdy wątek generacji jest wstrzymany, trwająca generacja jest anulowana i restartowana z zaktualizowanymi parametrami.

Wyniki generacji

Umieszczanie wyników generacji w modelu wiąże się z następującymi krokami:

1. Zamyka wszelkie wątki potomne uwolnione podczas generacji.
2. Pozycjonuje wyniki za pomocą PivotTo.
3. Jeśli Scale modelu nie wynosi 1, używa ScaleTo, aby cofnąć normalizację rozmiaru.
4. Umieszcza wyniki w folderze GeneratedFolder modelu.
5. Jeśli moduł generatora jest sandboxowany, zapewnia, że ModuleScripts w wynikach nie przekraczają możliwości modułu generatora.
6. Uzupełnia brakujące atrybuty w modelu ich wartościami domyślnymi.
7. Czyści stan brudny modelu.

Szczegóły generacji

Oprócz podstawowego przepływu generacji, następujące szczegóły opisują zachowania i rozważania, które wpływają na to, jak działa generacja ProceduralModel.

Rozmiar

Z powodu normalizacji skali stosowanej podczas generacji, ProceduralModel wspiera wiele różnych przepływów pracy związanych z rozmiarami:

• Zmiana właściwości Size regeneruje model z nową zawartością.
• Zmiana Scale jednolicie skalująca istniejące wyniki przy użyciu ScaleTo.

Limity czasowe

Jako zabezpieczenie, moduł generatora, który wykonuje zbyt dużo pracy bez yieldowania, jest przerywany. Jeśli generacja osiągnie błąd "Script Timeout", dodaj dodatkowe wywołania do parameters:Pause(), aby umożliwić silnikowi odroczenie pozostałej pracy do późniejszej klatki.

Wywołanie parameters:Pause() jest bardzo tanie i zazwyczaj zwraca natychmiast podczas normalnej egzekucji generatora, więc można je swobodnie wywoływać na początku pętli bez wpływu na wydajność.

Historia cofania

Wygenerowane wyniki są grupowane z zmianą parametrów, która je wywołała, przy użyciu nadpisania punktów kontrolnych cofania. Jeśli wiele zmian parametrów wystąpi w jednej klatce, wyniki są powiązane z najnowszym punktem kontrolnym.

Sandboxing

ProceduralModel wspiera sandboxing. Wszystkie modele proceduralne, które wstawiasz ze Sklepu Twórcy, są domyślnie sandboxowane, aby pomóc w zapobieganiu niezamierzonym zmianom w twojej grze.

Kod generacji działa w kontekście modułu generatora i korzysta z statusu sandboxingu tego modułu. Te ustawienia nie są widoczne domyślnie. Aby je wyświetlić lub zmodyfikować, ustaw Workspace.SandboxedInstanceMode = Experimental. To ujawnia właściwości Sandboxed i Capabilities na ModuleScript.

Sandboxowany moduł generatora zazwyczaj wymaga co najmniej następujących możliwości:

• RunServerScript (do wykonywania modułu)
• CreateInstances
• Basic

Sandboxing dla ProceduralModel i jego modułu generatora są niezależne od siebie. Kiedy jest stosowany do modułu generatora, sandboxing nie wpływa na normalne skrypty czasów wykonywania w ProceduralModel. To pozwala na ścisłe ograniczenie generacji w czasie edycji bez wpływania na zachowanie w grze.

Zagnieżdżenie

ProceduralModels mogą generować inne ProceduralModels. Kiedy to się dzieje, silnik przetwarza hierarchię od góry do dołu w tym samym kroku generacyjnym, gdy to możliwe, przy czym modele bardziej zagnieżdżone są generowane jako ostatnie.

Ograniczenia

• Generacja nie jest wspierana w instancjach Actor.
• Modele nie mogą być konwertowane na pakiety.
• Połączenia utworzone podczas użycia narzędzi do przeciągania z włączonymi Powierzchniami Połączeń nie są zachowywane podczas regeneracji ProceduralModel.