Verwendung von Datasmith-Metadaten in der Unreal Engine | Unreal Engine 5.7 Dokumentation

Der Datasmith-Importer kann automatisch Metadaten über die Objekte importieren, die er verarbeitet: Informationen, die Sie für diese Objekte in Ihrer 3D-Design- oder CAD-Anwendung eingerichtet haben. Metadaten werden am häufigsten verwendet, um Informationen aus der realen Welt über das mechanische Teil oder das architektonische Element zu speichern, welches das Asset darstellt, wie z. B. die Kosten des Teils, das Material, aus dem es besteht, physikalische Eigenschaften wie sein Gewicht oder seine Isolierungseffizienz oder Nutzungsinformationen wie das maximale Drehmoment, das auf ein Teil angewendet werden kann. Sie können Metadaten auch verwenden, um jede andere Art von Informationen über ein Asset zu speichern, die Sie für Ihr Projekt benötigen.

Diese Metadaten im Unreal Editor und in der Unreal Engine verfügbar zu haben, kann Ihnen auf zwei Arten helfen:

In Ihrer Asset-Pipeline: Sie können Metadaten verwenden, wenn Sie Assets importieren und Ihre Levels einrichten, um verschiedene Arten von Assets und Actors zu unterscheiden, die eine unterschiedliche Verarbeitung benötigen. Zum Beispiel:
- Sie könnten Metadaten während des Datasmith-Importprozesses verwenden, um bestimmte Arten von Assets zu identifizieren, die Sie in Ihrer endgültigen Szene nicht benötigen, sodass Sie deren Import überspringen können.
- Nach dem Import könnten Sie diese verwenden, um Actors in Ihrem Level zu identifizieren, die Sie zusammenführen, verbinden oder ersetzen möchten, oder deren Materialien Sie ersetzen möchten.
Zur Laufzeit in Ihrem Spiel: Sie können Metadaten zur Laufzeit verwenden, um Benutzern ausgewählte Informationen über Ihre Actors anzuzeigen, die aus Ihrem Quell-Design-Tool stammen. Zum Beispiel:
- Wenn die Objekte in Ihrem Level BIM-Daten haben, die Informationen über ihre strukturellen Eigenschaften enthalten, möchten Sie diese Informationen möglicherweise in Ihrer interaktiven Erfahrung visualisieren, wenn der Spieler diese Objekte in der Szene auswählt.
- Wenn Ihr Projekt ein Produktkonfigurator ist, der es dem Spieler ermöglicht, zwischen verschiedenen Designoptionen zu wählen, möchten Sie möglicherweise, dass Ihre Spiel-Logik die Gesamtkosten der aktuellen Auswahl des Spielers basierend auf den den sichtbaren Assets zugewiesenen Kosten-Metadaten berechnet und anzeigt.

Diese Seite beschreibt, wie man Metadaten über den Datasmith-Importprozess in Unreal einbringt und wie man darauf in Ihren Skripten sowohl im Editor als auch zur Laufzeit zugreift.

Metadatenquellen

Datasmith importiert derzeit Metadaten aus den folgenden Design-Tools:

Datasmith verarbeitet derzeit nur Metadaten zu Geometrie, nicht zu andere Arten von Szenenobjekten wie Lichtern oder Kameras.

Anzeigen von Metadaten im Unreal Editor

Nach Abschluss des Datasmith-Importprozesses können Sie die Metadaten für jeden Statisches-Mesh-Actor in Ihrem Level im Details-Panel unter dem Abschnitt Asset User Data anzeigen:

Anzeigen von Datasmith-Metadaten in Unreal

Datasmith-Metadaten sind derzeit im Editor schreibgeschützt.

Zugriff auf Metadaten in Blueprint und Python

Es gibt mehrere verschiedene Möglichkeiten, auf die Metadaten zuzugreifen, die mit Ihren Szenenobjekten verknüpft sind. Welche Methode Sie verwenden sollten, hängt davon ab, ob Sie während des Datasmith-Importprozesses oder nach Abschluss des Imports auf die Metadaten zugreifen müssen.

Alle Metadaten-Schlüssel und -Werte werden in der Unreal Engine als Strings gespeichert, unabhängig von ihrem ursprünglichen Typ in Ihrer Design- oder CAD-Anwendung. Wenn Sie beispielsweise in 3ds Max einen Metadatenwert als booleschen Wert wie true oder als Zahl wie 312 festlegen, werden diese beim Auslesen in einem Skript in Unreal als Strings vorliegen. Wenn Sie die Werte als boolesche Werte oder Zahlen benötigen, verwenden Sie einen Blueprint-Konvertierungsknoten wie Utilities > String > String to Int oder String to Float, oder eingebaute Python-String-Parsing-Funktionen wie int() oder float().

Zugriff auf Metadaten während des Imports

Wenn Sie während des Datasmith-Importprozesses auf Ihre Metadaten zugreifen müssen – zum Beispiel, um bestimmte Meshs zu identifizieren, die Sie vor der Erstellung von Unreal-Assets für Ihre Szene herausfiltern möchten – können Sie die Metadaten aus der Datasmith-Szene lesen. Für Hintergrundinformationen darüber, wie man ein Skript während des Importprozesses ausführt, siehe Anpassung des Datasmith-Importprozesses.

Sie finden die Metadaten angehängt an Mesh-Actor-Elemente in der Datasmith-Szene.

Blueprints

Python

Die Knoten, die Sie benötigen, befinden sich unter Datasmith > Scene und Datasmith > Element.

Um diese Knoten zu erreichen, müssen Sie das Kontrollkästchen Context Sensitive im Kontextmenü deaktivieren oder die benötigten Knoten in der Palette finden.

Knoten	Beschreibung
Get All Metadata	Ruft ein Array aller Metadatenobjekte ab, die für alle Objekte in der Datasmith-Szene aufgezeichnet wurden.
Get All Objects and Values for Key	Ruft eine Liste aller Objekte in der Datasmith-Szene ab, die einen bestimmten Schlüssel haben. Sie erhalten auch eine Liste aller Werte, die für diesen Schlüssel über alle diese Objekte hinweg aufgezeichnet wurden.
Get Metadata for Object	Ruft alle Metadaten ab, die einem bestimmten Objekt zugewiesen sind.
Get Metadata Value for Key	Ruft den Wert eines bestimmten Schlüssels ab, der einem bestimmten Objekt zugewiesen ist.
Get Metadata Keys and Values for Value	Ruft alle Schlüssel eines bestimmten Objekts ab, deren Wert mit dem Input String to Match übereinstimmt.

Für die oben genannten Knoten, die ein „Datasmith Metadata Element“-Objekt zurückgeben, können Sie die Schlüssel und Werte aus dem Metadatenobjekt abrufen, indem Sie Datasmith > Element > Get Properties, Get Property und Get Property Count verwenden:

Verwendungsbeispiel

Dieses Beispiel zeigt, wie Sie die einem Metadaten-Schlüssel zugewiesenen Werte verwenden können, um Geometrie zu identifizieren, die Sie in Ihrem Projekt nicht benötigen, und diese aus Ihrer Datasmith-Szene zu entfernen, bevor Sie Statisches-Mesh-Assets erstellen:

Während des Datasmith-Importprozesses können Sie über das unreal.DatasmithSceneElement-Objekt auf die Metadaten Ihrer Szenenobjekte zugreifen. Für Details zu den folgenden Funktionen siehe die Python-API-Referenz.


`get_all_metadata(object_class)` Ruft ein Array aller Metadatenobjekte ab, die für alle Objekte in der Datasmith-Szene aufgezeichnet wurden.
`get_all_objects_and_values_for_key(key, object_class)` Ruft eine Liste aller Objekte in der Datasmith-Szene ab, die einen angegebenen Schlüssel haben. Sie erhalten auch eine Liste aller Werte, die für diesen Schlüssel über alle diese Objekte hinweg aufgezeichnet wurden.
`get_metadata_for_object(object)` Ruft alle Metadaten ab, die einem angegebenen Objekt zugewiesen sind.
`get_metadata_value_for_key(object, key)` Ruft den Wert eines angegebenen Schlüssels ab, der einem angegebenen Objekt zugewiesen ist.
`get_metadata_keys_and_values_for_value(object, string_to_match)` Ruft alle Schlüssel eines angegebenen Objekts ab, deren Wert mit dem zweiten Parameter übereinstimmt.

Verwendungsbeispiel


    key_name = "name"
    remove_keyword = "Clutch"
    meshes_to_skip = set([])
    # Alle Szenenelemente abrufen, die den „name“-Schlüssel haben.
    objects_and_values = ds_scene_in_memory.get_all_objects_and_values_for_key(key_name, unreal.DatasmithMeshActorElement)
    objects = objects_and_values[0]
    values = objects_and_values[1]
    #Durch diese iterieren und nach solchen suchen, deren Wert mit einem Schlüsselwort übereinstimmt
    for index, value in enumerate(values):
        if remove_keyword in value:
            print("removing actor named: " + value)
            # Entferne das Mesh-Actor-Element aus der Szene und füge das Mesh-Element einer Liste hinzu, um es später zu entfernen
            mesh_actor = objects[index]
            mesh = mesh_actor.get_mesh_element()
            meshes_to_skip.add(mesh)
            ds_scene_in_memory.remove_mesh_actor(mesh_actor)
    # Entfernen aller Meshs, die wir nicht importieren müssen.
    for mesh in meshes_to_skip:
        mesh_name = mesh.get_element_name()
        print("Entfernen des Mesh mit dem Namen: " + mesh_name)
        ds_scene_in_memory.remove_mesh(mesh)

key_name = "name"
    remove_keyword = "Clutch"
    meshes_to_skip = set([])
    # Alle Szenenelemente abrufen, die den „name“-Schlüssel haben.
    objects_and_values = ds_scene_in_memory.get_all_objects_and_values_for_key(key_name, unreal.DatasmithMeshActorElement)
    objects = objects_and_values[0]
    values = objects_and_values[1]
    #Durch diese iterieren und nach solchen suchen, deren Wert mit einem Schlüsselwort übereinstimmt
    for index, value in enumerate(values):
        if remove_keyword in value:
            print("removing actor named: " + value)
            # Entferne das Mesh-Actor-Element aus der Szene und füge das Mesh-Element einer Liste hinzu, um es später zu entfernen
            mesh_actor = objects[index]
            mesh = mesh_actor.get_mesh_element()
            meshes_to_skip.add(mesh)
            ds_scene_in_memory.remove_mesh_actor(mesh_actor)
    # Entfernen aller Meshs, die wir nicht importieren müssen.
    for mesh in meshes_to_skip:
        mesh_name = mesh.get_element_name()
        print("Entfernen des Mesh mit dem Namen: " + mesh_name)
        ds_scene_in_memory.remove_mesh(mesh)

Zugriff auf Metadaten nach dem Import

Wenn der Importprozess Ihre Datasmith-Szene in Unreal-Assets und -Actors abschließt, wendet er auch die Metadaten von jedem Mesh-Element in der Datasmith-Szene auf alle Actors im Level an, die Instanzen dieses Statisches-Mesh-Assets darstellen. Sie können dann Blueprint oder Python verwenden, um die Metadaten für einen oder alle Statisches-Mesh-Actors in Ihrem Level abzurufen.

Blueprints

Python

Die folgenden Knoten greifen auf Metadaten für einen bestimmten Actor zu. Diese haben sehr wenig Einfluss auf die Leistung, sodass Sie sie jederzeit verwenden können, sogar zur Laufzeit in Ihrem Projekt. Wenn Sie die importierten Metadaten für ein oder mehrere ausgewählte Objekte in Ihrer Szene visualisieren möchten – zum Beispiel in einem Appell oder einem Menü in der Laufzeit-UI Ihres Projekts – sind dies die Knoten, die Sie in Ihren Laufzeit-Blueprint-Diagrammen verwenden müssen.

Sie finden sie unter der Kategorie Datasmith User Data.

Knoten	Beschreibung
Get Datasmith User Data Value for Key	Ruft den Wert der Metadaten mit dem angegebenen Schlüssel ab, der dem angegebenen Objekt zugewiesen ist.
Get Datasmith User Data Keys and Values for Value	Ruft alle Schlüssel des angegebenen Objekts ab, die den von Ihnen im Input String to Match angegebenen Wert haben. Verwenden Sie diesen Knoten, wenn Sie den Wert kennen, den Sie suchen, aber nicht den Namen des Schlüssels.
Get Datasmith User Data	Ruft ein Metadatenobjekt ab, das alle für den Actor aufgezeichneten Schlüssel-Wert-Paare enthält, sodass Sie diese selbst durchlaufen können.

Die folgenden Knoten greifen dagegen auf die Metadaten aller Statisches-MeshActors im aktuellen Level zu (oder auf alle, die sich eine bestimmte Klasse teilen). Da Ihr Level potenziell eine große Anzahl von Actors enthalten kann, von denen jeder viele Eigenschaften hat, können diese Funktionen ressourcenintensiv für die CPU sein und bei der Laufzeitausführung zu schlechter Leistung führen. Daher können Sie sie nur in Diagrammen verwenden, die Sie in Editor-exklusiven Blueprint-Klassen erstellen.

Sie finden diese Knoten unter der Kategorie Editor Scripting > Datasmith User Data.

Knoten	Beschreibung
Get All Objects and Values for Key	Ruft eine Liste aller Actors im aktuellen Level ab, die einen bestimmten Schlüssel in ihren Datasmith-Metadaten haben. Sie erhalten auch eine Liste aller Werte, die für diesen Schlüssel über alle diese Objekte hinweg aufgezeichnet wurden.
Get All Datasmith User Data	Ruft die vollständige Liste aller Metadatenobjekte für alle Actors im aktuellen Level ab.

Die oben genannten Knoten Get Datasmith User Data und Get All Datasmith User Data geben Datasmith-Benutzerdaten-Objekt-Referenzen zurück. Dieses Objekt hat eine Variable, auf die Sie zugreifen können, genannt Metadata, welche eine Map aller Schlüssel-Wert-Paare ist, die die Datasmith-Metadaten des Objekts ausmachen. Um mit dieser Art von Objekt zu arbeiten, ziehen Sie vom Output-Pin ab und wählen Sie Variables > Get Metadata:

Dies liefert Ihnen die Schlüssel und Werte als Map. Sie können dann die Hilfsknoten in der Kategorie Utilities > Map verwenden, um mit den Daten zu arbeiten. Zum Beispiel iteriert dieses Diagramm durch alle Schlüssel nacheinander und ruft den mit jedem Schlüssel verknüpften Wert ab:

Weitere Informationen zu Blueprint-Map-Knoten finden Sie in der Blueprint-API-Referenz.

Verwendungsbeispiel

Dieser Abschnitt zeigt ein vereinfachtes Beispiel, wie Sie die Metadaten Ihres Assets zur Laufzeit für ein Objekt visualisieren können, das der Spieler im Level auswählt.

Der Text wird von einem UMG-Widget geschrieben, das zwei Textfelder enthält, die jeweils an eine String-Variable gebunden sind. Im Blueprint-Diagramm für das Widget extrahiert eine benutzerdefinierte Aktion zwei Elemente von Datasmith-Metadaten aus einem Actor, den Sie in einem benutzerdefinierten Ereignis übergeben, und speichert diese Elemente in den gebundenen Variablen.

Der folgende Level-Blueprint zeigt ein Beispiel dafür, wie ein Widget wie dieses hinzugefügt wird, wenn das Spiel beginnt, und wie es mit dem Actor unter dem Cursor jedes Mal eingefügt wird, wenn der Benutzer eine Maustaste drückt.

Weitere Informationen zum Erstellen von Benutzeroberflächen in UMG finden Sie im UMG UI Designer Quick Start Guide und den umliegenden Abschnitten.

Nach Abschluss des Datasmith-Importvorgangs können Sie Metadaten für alle Actors oder ausgewählte Actors mithilfe der Klasse unreal.DatasmithContentLibrary abrufen. Weitere Details zu den folgenden Funktionen finden Sie in der Python-API-Referenz.


`get_all_datasmith_user_data(object_class)` Ruft die vollständige Liste aller Metadaten-Objekte für alle Actors im aktuellen Level ab.
`get_all_objects_and_values_for_key(key, object_class)` Ruft eine Liste aller Actors im aktuellen Level ab, die einen bestimmten Schlüssel in ihren Datasmith-Metadaten haben. Sie erhalten auch eine Liste aller Werte, die für diesen Schlüssel über alle diese Objekte hinweg aufgezeichnet wurden.
`get_datasmith_user_data(object)` Ruft ein Metadaten-Objekt ab, das alle Schlüssel-Wert-Paare enthält, die für den angegebenen Actor aufgezeichnet wurden, sodass Sie diese selbst durchlaufen können.
`get_datasmith_user_data_keys_and_values_for_value(object, string_to_match)` Ruft alle Schlüssel des angegebenen Actors ab, die den im zweiten Parameter angegebenen Wert haben. Verwenden Sie diesen Knoten, wenn Sie den gesuchten Wert kennen, aber nicht den Namen des Schlüssels.
`get_datasmith_user_data_value_for_key(object, key)` Ruft den Wert der Metadaten mit dem angegebenen Schlüssel ab, der dem angegebenen Actor zugewiesen ist.

Verwendungsbeispiel

In Python-Skripten, die Sie im Unreal Editor ausführen, können Sie nach dem Import Datasmith-Metadaten verwenden, um Statisches-Mesh-Actors in Ihrem Level zu identifizieren, denen Sie bestimmte spezielle Verarbeitungen zuweisen möchten.


    import unreal
    new_actor_name = "Exterior Walls"
    metadata_key = "Type"
    metadata_value = "Wall: Exterior"
    meshes_to_join = set([])
    # Durch die Actors im aktuellen Level iterieren
    all_actors = unreal.EditorLevelLibrary.get_all_level_actors()
    for actor in all_actors:
        # Ruft den Wert der Datasmith-Metadaten dieses Actors für den oben festgelegten Schlüssel ab, falls vorhanden
        actor_value = unreal.DatasmithContentLibrary.get_datasmith_user_data_value_for_key(actor, metadata_key)
        # Wenn der Schlüssel existiert und sein Wert ein oben festgelegtes Schlüsselwort enthält, füge den Actor einer Liste hinzu
        if actor_value and metadata_value in actor_value:
            print("found a matching actor: " + actor_value)
            meshes_to_join.add(actor)
    # Füge alle oben gefundenen Actors zu einem einzigen Actor mit vielen Komponenten zusammen
    options = unreal.EditorScriptingJoinStaticMeshActorsOptions(destroy_source_actors=True, new_actor_label=new_actor_name, rename_components_from_source=True)
    unreal.EditorLevelLibrary.join_static_mesh_actors(meshes_to_join, options)
    print "Merged all actors!"

import unreal
    new_actor_name = "Exterior Walls"
    metadata_key = "Type"
    metadata_value = "Wall: Exterior"
    meshes_to_join = set([])
    # Durch die Actors im aktuellen Level iterieren
    all_actors = unreal.EditorLevelLibrary.get_all_level_actors()
    for actor in all_actors:
        # Ruft den Wert der Datasmith-Metadaten dieses Actors für den oben festgelegten Schlüssel ab, falls vorhanden
        actor_value = unreal.DatasmithContentLibrary.get_datasmith_user_data_value_for_key(actor, metadata_key)
        # Wenn der Schlüssel existiert und sein Wert ein oben festgelegtes Schlüsselwort enthält, füge den Actor einer Liste hinzu
        if actor_value and metadata_value in actor_value:
            print("found a matching actor: " + actor_value)
            meshes_to_join.add(actor)
    # Füge alle oben gefundenen Actors zu einem einzigen Actor mit vielen Komponenten zusammen
    options = unreal.EditorScriptingJoinStaticMeshActorsOptions(destroy_source_actors=True, new_actor_label=new_actor_name, rename_components_from_source=True)
    unreal.EditorLevelLibrary.join_static_mesh_actors(meshes_to_join, options)
    print "Merged all actors!"