Prozedurale Modelle

ProceduralModels sind eine Art parametergetriebenes Model, mit dem Sie 3D-Objekte mit Code erstellen und generieren können. Anstatt den Inhalt eines Modells manuell zu bearbeiten, definieren Sie seine Struktur über ein Generator-Modul und eine Reihe von Attributen. Wenn sich diese Attribute ändern oder das Modell in der Größe verändert wird, wird der Generator automatisch ausgeführt, um das Modell zu aktualisieren.

Prozedurale Modelle erleichtern:

• Anpassungen an Modellen, ohne sie neu zu erstellen, indem Parameter geändert werden. Wenn beispielsweise der Wert von StepSize bei einer Wendeltreppe verändert wird, regeneriert sich die Treppe automatisch mit der aktualisierten Anzahl von Stufen.
• Eine automatische Integration in bestehende Studio-Systeme wie Rückgängig/Wiederherstellen, Team Create und Dragwerkzeuge durch Implementierung einer einzigen OnGenerate-Funktion.
• Hohe Leistung durch Modelle, die sich wie Standardobjekte verhalten, bis sich ihre Parameter ändern.
• Generierung von Inhalten sowohl zur Bearbeitungszeit als auch zur Laufzeit, indem dasselbe System im Studio und im Spiel verwendet wird.
• Teilen parametrized Modelle im Creator Store, wodurch Assets flexibler und anpassbarer werden.

Prozedurale Modelle einfügen

Sie können prozedurale Modelle in Ihr Spiel auf folgende Weise hinzufügen:

• Fügen Sie manuell ein ProceduralModel-Objekt in den Workspace ein. Diese Option enthält ein Vorlage-Generator ModuleScript, um Ihnen den Einstieg zu erleichtern.

  

• Generieren Sie ein prozedurales Modell mit Assistant oder dem Roblox Studio MCP-Server.

• Fügen Sie ein prozedurales Modell aus dem Creator Store ein, um ein vorhandenes Modell zu verwenden oder anzupassen.

Um anzupassen, wie prozedurale Modelle generiert werden, können Sie Ihre eigenen Generator-Module definieren.

OnGenerate-Funktion

Die OnGenerate-Funktion ist das Herzstück jedes ProceduralModel in Form von OnGenerate(params, targetContainer).

Diese vom Entwickler definierte Funktion ist verantwortlich dafür, den Inhalt des Modells basierend auf den bereitgestellten Parametern zu generieren und die Ergebnisse in den gegebenen Container zu schreiben.

OnGenerate hat zwei Hauptverantwortlichkeiten:

• Verarbeiten der Eingabeparameter, um die Struktur des Modells zu bestimmen
• Schreiben der generierten Ergebnisse gemäß dieser Struktur in den bereitgestellten targetContainer

Die folgenden Abschnitte beschreiben:

• Wann und wie die Engine OnGenerate aufruft
• Wie die Engine die Inhalte verarbeitet, die in den targetContainer geschrieben werden

Generator-Module

Die OnGenerate-Funktion wird innerhalb eines ModuleScript definiert, das als Generator-Modul bekannt ist. Das ProceduralModel identifiziert, welches Generator-Modul verwendet werden soll, durch seine Generator-Eigenschaft.

Generator-Module sind Standard-Luau-Module, werden jedoch direkt von der Engine als Teil des Generierungsprozesses benötigt. Sie folgen einer definierten Struktur und geben eine Tabelle mit standardisierten Feldern zurück.

Generator-Modulstruktur
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

Die standardisierten Felder umfassen:

• Attributes: Eine Zuordnung, die Parameternamen und deren Standardwerte definiert.
• OnGenerate: Die Funktion, die eine params-Tabelle und einen targetContainer empfängt.

Die params-Tabelle innerhalb von OnGenerate umfasst:

• Attributes: Eine Tabelle, die entweder die vom Modul definierten Attribute oder alle Modellattribute enthält, wenn keine angegeben sind.
• Size: Ein Parameter, der die Abmessungen des Modells im Maßstab eins widerspiegelt.
• Pause: Eine Methode, die es ermöglicht, dass die Generierung während komplexer Generierungsaufgaben effizient ausgesetzt wird.

Die OnGenerate-Funktion sollte Inhalte um den Ursprung im targetContainer generieren. Sie sollte niemals direkt die Haupthierarchie des DataModel ändern.

Parameter

Parameter sind die Eingaben, die die Generierung steuern. Dazu gehören die eingebaute Size-Eigenschaft von ProceduralModel sowie benutzerdefinierte Attribute, die im Generator-Modul angegeben sind. Diese expliziten Parameter werden direkt an OnGenerate übergeben. Implizite Parameter, wie der Quellcode des Moduls oder der Sandboxing-Status, lösen ebenfalls eine Regenerierung aus, wenn sie geändert werden, werden jedoch nicht an OnGenerate übergeben.

Das vollständige Set von Parametern umfasst:

• Explizit:

  • Size: Definiert den Bereich um den Ursprung, in dem Inhalte generiert werden.
  • Attributes: Eine Zuordnung, die die aktuellen Eingabewerte von Attributen enthält.
• Implizit:

  • Generator: Das Modul, das die Generierungslogik bereitstellt.
  • Quellcode: Änderungen am Luau-Code des Generator-Moduls.
  • Sandboxing: Änderungen am Sandboxing-Status des Generator-Moduls.

Regenerierungsverhalten

Um die Leistung aufrechtzuerhalten und API-Interaktionen zu vereinfachen, wird OnGenerate nicht sofort aufgerufen, wenn sich Parameter ändern. Stattdessen wird das ProceduralModel als dirty markiert, was darauf hinweist, dass eine Regenerierung aussteht. Diese ausstehende Regenerierung erfolgt normalerweise später im selben Frame.

Wenn die Regenerierung fehlschlägt, wird der schmutzige Zustand gelöscht, bis eine weitere Parameteränderung erfolgt. Wenn ein Ort gespeichert wird, während das Modell schmutzig ist, bleibt der Zustand bestehen, und das Modell wird bei der nächsten Spiel-Ladung der Generierungswarteschlange hinzugefügt.

Ausführungsprozess

Wenn verfügbare Verarbeitungszeit vorhanden ist, regeneriert die Engine schmutzige Modelle, indem sie die folgenden Schritte ausführt:

1. Benötigt das Generator-Modul und gibt bei Bedarf nach.
2. Startet einen neuen Thread für den Generierungsprozess.
3. Baut die Parameter-Tabelle auf und normalisiert die Size nach dem aktuellen Maßstab des Modells.
4. Wendet Standardwert-Attribute auf fehlende Attribute an.
5. Initialisiert einen temporären GeneratedFolder als targetContainer.
6. Ruft OnGenerate auf.
7. Nach der Rückkehr von OnGenerate:

   • Wenn erfolgreich, wandert die Form in den targetContainer zu dem ProceduralModel.
   • Wenn die Generierung fehlschlägt, verwendet sie stattdessen einen Platzhalter für den Fehler.

Wenn sich die Parameter erneut ändern, während ein Generationsthread pausiert ist, wird die ausstehende Generierung abgebrochen und mit den aktualisierten Parametern neu gestartet.

Generationsergebnisse

Das Einfügen von generierten Ergebnissen in das Modell umfasst die folgenden Schritte:

1. Beendet alle während der Generierung undichten Kind-Threads.
2. Positioniert die Ergebnisse mit PivotTo.
3. Wenn der Scale des Modells nicht 1 ist, verwendet ScaleTo, um die Größenormalisierung rückgängig zu machen.
4. Verankert die Ergebnisse im GeneratedFolder des Modells.
5. Wenn das Generator-Modul sandboxed ist, stellt sicher, dass die ModuleScripts im Ergebnis die Fähigkeiten des Generator-Moduls nicht überschreiten.
6. Füllt fehlende Attribute des Modells mit ihren Standardwerten.
7. Löscht den schmutzigen Zustand des Modells.

Generierungsdetails

Zusätzlich zum zentralen Generierungsfluss beschreiben die folgenden Details Verhaltensweisen und Überlegungen, die beeinflussen, wie die Generierung von ProceduralModel funktioniert.

Größenanpassung

Aufgrund der während der Generierung angewandten Größenormalisierung unterstützt ProceduralModel mehrere Größenanpassungs-Workflows:

• Das Ändern der Size-Eigenschaft regeneriert das Modell mit neuen Inhalten.
• Das Ändern des Scale skaliert die vorhandenen Ergebnisse einheitlich über ScaleTo.

Timeouts

Als Sicherheitsmaßnahme wird ein Generator-Modul, das zu viel Arbeit verrichtet, ohne Ergebnisse zurückzugeben, beendet. Wenn die Generierung einen "Script Timeout"-Fehler erreicht, fügen Sie zusätzliche Aufrufe zu parameters:Pause() hinzu, um der Engine zu ermöglichen, die verbleibende Arbeit auf einen späteren Frame zu verschieben.

Der Aufruf von parameters:Pause() ist sehr kostengünstig und gibt typischerweise sofort während der normalen Ausführung des Generators zurück. Daher kann es frei zu Beginn von Schleifen ohne Einfluss auf die Leistung aufgerufen werden.

Undo-Historie

Generierte Ergebnisse werden mit der Parameteränderung, die sie ausgelöst hat, mithilfe von Rückgängig-Wegpunktüberschreibungen gruppiert. Wenn mehrere Parameteränderungen in einem einzigen Frame auftreten, werden die Ergebnisse dem neuesten Wegpunkt zugeordnet.

Sandboxing

ProceduralModel unterstützt Sandboxing. Alle von Ihnen aus dem Creator Store eingefügten Drittanbieter-prozeduralen Modelle sind standardmäßig sandboxed, um unerwünschte Änderungen an Ihrem Spiel zu verhindern.

Der Generierungscode wird im Kontext des Generator-Moduls ausgeführt und verwendet den Sandboxing-Status dieses Moduls. Diese Einstellungen sind standardmäßig nicht sichtbar. Um sie anzuzeigen oder zu ändern, setzen Sie Workspace.SandboxedInstanceMode = Experimental. Dies macht die Eigenschaften Sandboxed und Capabilities im ModuleScript sichtbar.

Ein sandboxed Generator-Modul benötigt in der Regel mindestens die folgenden Fähigkeiten:

• RunServerScript (um das Modul auszuführen)
• CreateInstances
• Basic

Das Sandboxing für das ProceduralModel und sein Generator-Modul sind unabhängig voneinander. Wenn es auf das Generator-Modul angewendet wird, beeinflusst das Sandboxing keine normalen Laufzeitskripte innerhalb des ProceduralModel. Dies ermöglicht es Ihnen, die Generierung zur Bearbeitungszeit stark einzuschränken, ohne das Verhalten im Spiel zu beeinträchtigen.

Verschachtelung

ProceduralModels können andere ProceduralModels generieren. Wenn dies geschieht, verarbeitet die Engine die Hierarchie von oben nach unten innerhalb desselben Generierungsschritts, wenn möglich, wobei tiefere Modelle zuletzt generiert werden.

Einschränkungen

• Die Generierung wird innerhalb von Actor-Instanzen nicht unterstützt.
• Modelle können nicht in Pakete umgewandelt werden.
• Gelenke, die beim Verwenden von Dragern mit Gelenkoberflächen aktiviert erstellt werden, bleiben bei Regenerierungen von ProceduralModel nicht erhalten.