Plugin-Erstellung/Java/Prefab Klasse

* Diese Seite ist in Bearbeitung * This page is in progress *

Bitte schaue später noch einmal vorbei, um weitere Änderungen zu erfahren.

Please check back later for additional changes.

Prefab Klasse stellt ein benutzerdefiniertes Prefab dar. Ein Prefab kann aus mehreren Modellen und Meshes bestehen und zusätzlich Texturen, Materialien, Animatoren, Collider und weitere Unity-Komponenten enthalten. Ein Prefab wird in der Regel in Unity erstellt, dabei lassen sich nahezu alle Unity-Komponenten verwenden. Bei der Verwendung von Materialien oder eigenen Shadern ist darauf zu achten, dass diese HDRP-kompatibel sind.
Mit der Klasse ist es außerdem möglich, verschiedene Parameter jedes untergeordneten Elements eines Prefabs zu verändern (also eines Kindes innerhalb des Prefab-Assets selbst, nicht zu verwechseln mit einem regulären GameObject, das diesem Objekt angehängt ist).
Die Prefab Klasse erbt von GameObject und wird innerhalb der Java Plugin-API verwendet, um Prefabs aus AssetBundles oder Spielinhalten zu laden und im Spiel zu platzieren.
Dieser Artikel dokumentiert einige wichtige Methoden der Prefab Klasse und zeigt anhand ausgewählter Java-Beispiele, wie diese zu verwenden sind. Hier sind nicht alle Methoden aufgeführt. Die vollständige API-Dokumentation mit allen Methoden, Feldern und Konstruktoren ist im JavaDoc zu finden.

Was ist ein Unity Prefab?

Ein Prefab (Kurzform für Pre-fabricated object) ist in Unity ein wieder verwendbares Asset, das ein komplettes GameObject samt aller Komponenten, Eigenschaften, Einstellungen, Abhängigkeiten und untergeordneten Objekten als Vorlage kapselt. Prefabs verhalten sich wie eine Art "Bauplan": ein in Unity erstelltes Prefab kann zur Laufzeit beliebig oft instanziiert werden, wobei jede Instanz eine Kopie der Vorlage erhält. Änderungen an der Vorlage wirken sich auf alle Instanzen aus, sofern diese nicht explizit überschrieben wurden.
In Rising World Plugins werden Prefabs üblicherweise in Unity AssetBundles verpackt und über die Plugin-API geladen. Dadurch lassen sich komplexe 3D-Objekte mit mehreren Modellen, Materialien, Texturen, Animatoren und Lichteffekten in eigene Plugins einbringen.
Siehe auch:

Dokumentation

Die Prefab Klasse ist unter JavaDoc: Class Prefab zu finden. Die vollständige API-Dokumentation mit allen Paketen, Klassen, Methoden, Feldern und Konstruktoren ist im JavaDoc und im WorldElements Paket zu finden.

Java Paket

In der Java Plugin-API bezeichnet der Begriff "Package" (Paket) eine Gruppierung von zusammengehörigen Klassen, Interfaces und anderen Paketen. Die Prefab Klasse befindet sich im Package net.risingworld.api.worldelements.

Oberklasse

Die Prefab Klasse erbt von der Klasse GameObject, welche die Basisklasse für alle benutzerdefinierten Elemente (Prefab, Model, Light ...) in der Plugin-API darstellt. Über die Oberklasse stehen allen Prefabs die folgenden geerbten Methoden zur Verfügung: addChild(), addComponent(String), attachTo(Player/Npc, AttachTarget), getAttribute(), getChilds(), getCollider(), getID(), getLayer(), getLocalPosition(), getLocalRotation(), getLocalScale(), getParent(), getPluginID(), invokeComponentMethod(), isActive(), isAttached(), moveToLocalPosition(), moveToLocalTransform(), readWorldPosition(), readWorldRotation(), removeChild(), removeComponent(), removeFromParent(), rotateToLocalRotation(), setActive(), setAttribute(), setCollider(), setColliderVisible(), setComponentEnabled(), setComponentProperty(), setLayer(), setLocalPosition(), setLocalRotation(), setLocalScale() und Attribute-bezogene Methoden.

Konstruktoren

Prefab() – Erstellt ein neues, leeres Prefab-Objekt ohne zugewiesenes PrefabAsset.
Prefab(PrefabAsset prefab) – Erstellt ein neues Prefab-Objekt und weist ihm das übergebene PrefabAsset zu.

Methoden

Dieser Abschnitt listet einige wichtige in der Prefab Klasse definierten Methoden auf, thematisch zusammengefasst. Geerbte Methoden aus GameObject und Object sind nicht enthalten; eine vollständige Liste steht im JavaDoc: Class Prefab. Bei Methoden, die in mehreren Überladungen vorliegen, wird hier die wichtigste Form gezeigt und auf die weiteren Varianten im JavaDoc verwiesen.

Komponenten via Reflection

Die folgenden Methoden arbeiten mit Reflection, das heißt sie nehmen Unity-Komponentennamen als String an.

Prefab.addComponent(...)... – Fügt dem Prefab (oder einem Kind-Element) eine neue Unity-Komponente per Reflection hinzu. Der Komponentenname wird als String übergeben.
Prefab.removeComponent(...)... – Entfernt eine Unity-Komponente vom Prefab (oder einem Kind-Element) anhand ihres Namens.
Prefab.setComponentEnabled(...)... – Aktiviert oder deaktiviert eine Komponente, die von Behaviour abgeleitet ist.
Prefab.setComponentProperty(...)... – Setzt eine Property einer Komponente per Reflection.
Prefab.invokeComponentMethod(...)... – Ruft eine Methode einer Komponente per Reflection auf.

Weitere Methoden, die mit Reflection auf Komponenten zugreifen, sind im JavaDoc: Class Prefab zu finden.

Unity Komponenten

Kleine Unity Komponenten Liste - kompatibel mit Unity 6000.0.60 und für die HDRP geeignet.
Die folgenden Unity-Standardkomponenten lassen sich über die Reflection-Methoden an ein Prefab oder ein Kind-Element anhängen und steuern (kleine Auswahl, ohne Anspruch auf Vollständigkeit):
Physik: Rigidbody, BoxCollider, SphereCollider, CapsuleCollider, MeshCollider, ConstantForce
Animation: Animator
Effekte: ParticleSystem, VFX Graph (über VisualEffect), Light, AudioSource
Renderer: MeshRenderer, SkinnedMeshRenderer, DecalProjector
Planar Reflection: PlanarReflectionProbe
Sonstige: Transform
Es sind alle Unity-Standardkomponenten nutzbar, deren Klasse bereits in der Spielassembly vorhanden ist.
Fügt einem Prefab nachträglich eine Rigidbody-Komponente hinzu. prefab.addComponent(null, "Rigidbody");

Beispiel: addComponent

Fügt einem Prefab nachträglich eine Rigidbody-Komponente hinzu. Dabei wird zuerst ein Collider über die GameObject-Oberklasse zugewiesen (notwendig für Physik), und anschließend wird die Komponente über den Komponentennamen als String per Reflection hinzugefügt.

//Neues Prefab-Objekt erzeugen
Prefab prefab = new Prefab(PrefabAsset.loadFromFile("..."));
prefab.setLayer(Layer.ITEM);
prefab.setLocalPosition(player.getPosition());

//Collider zum Prefab hinzufügen (notwendig für Physik)
prefab.addCollider(new BoxCollider());

//Rigidbody-Komponente zum Hauptprefab hinzufügen (Pfad null)
prefab.addComponent(null, "Rigidbody");

//Prefab zur Spielerwelt hinzufügen
player.addGameObject(prefab);

Die Methode addComponent ist unter JavaDoc: Class Prefab - addComponent zu finden.

Animation (Animator)

Methoden, mit denen der Unity-Animator-Controller eines Prefabs oder seiner Kind-Elemente gesteuert werden kann.

Prefab.setAnimatorParameter(...) – Setzt einen Parameter am Animator-Controller. Es gibt 2 weitere Überladungen dieser Methode mit unterschiedlichen Parametern im JavaDoc: Class Prefab.
Prefab.setAnimatorTrigger(...) – Aktiviert einen Trigger-Parameter am Animator-Controller.
Prefab.resetAnimatorTrigger(...) – Deaktiviert einen zuvor gesetzten Trigger-Parameter.
Prefab.playAnimatorState(...) – Spielt einen Animator-State ab einer bestimmten normalisierten Zeit auf einem Layer ab.
Prefab.startAnimatorPlayback(...) – Startet die Animator-Wiedergabe.
Prefab.stopAnimatorPlayback(...) – Stoppt die Animator-Wiedergabe.
Prefab.rebindAnimator(...) – Bindet alle Properties und Mesh-Daten neu an den Animator-Controller.

Weitere Animator-bezogene Methoden sind im JavaDoc: Class Prefab zu finden.

Materialien

Methoden, mit denen Materialien und Material-Parameter eines Prefabs oder seiner Kind-Elemente gesetzt oder ausgelesen werden können.

Prefab.setMaterial(...) – Weist dem Prefab (oder einem Kind-Element) ein neues Material zu.
Prefab.setMaterialParameter(...) – Setzt einen Material-Parameter (zum Beispiel Farbe, Vektor, Textur). Es gibt 6 weitere Überladungen dieser Methode mit unterschiedlichen Parametern (boolean, Vector2f, Vector3f, Vector4f, TextureAsset) im JavaDoc: Class Prefab.
Prefab.clearMaterialPropertyBlock(...) – Entfernt einen MaterialPropertyBlock von einer Renderer-Komponente.

Weitere Methoden rund um Materialien sind im JavaDoc: Class Prefab zu finden.

Beispiel: setMaterialParameter (Vector3 mit Pfad)

Setzt einen Vector3-Material-Parameter an einem bestimmten untergeordneten Material. Der Pfad wird durch Slashes getrennt (zum Beispiel "child/another_child") und verweist auf das entsprechende Renderer-Element innerhalb des Prefabs.

Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
prefab.setMaterialParameter("child/another_child", "_PositionProperty", new Vector3f(0f, 10f, 0f));
prefab.setLocalPosition(player.getPosition());
player.addGameObject(prefab);

Die Methode setMaterialParameter ist unter JavaDoc: Class Prefab - setMaterialParameter zu finden.

Beispiel: setMaterialParameter (Farbe via Vector4)

Setzt die Basisfarbe eines Materials auf Rot. Vector4 wird hier verwendet, um eine Farbe zu übergeben (RGBA). Der Pfad "child/anotherchild" verweist auf das Material des entsprechenden untergeordneten Renderers.

Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
prefab.setMaterialParameter("child/anotherchild", "_BaseColor", new Vector4f(1f, 0f, 0f, 1f)); // rot
prefab.setLocalPosition(player.getPosition());
player.addGameObject(prefab);

Die Methode setMaterialParameter ist unter JavaDoc: Class Prefab - setMaterialParameter zu finden.

Beispiel: setMaterialParameter (Texture)

Weist einem Material einen neuen Texture-Asset zu, zum Beispiel eine neue Textur als Albedo-Map (entspricht _BaseColorMap in HDRP).

Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
prefab.setMaterialParameter("child/anotherchild", "_BaseColorMap", TextureAsset.loadFromFile(...));
prefab.setLocalPosition(player.getPosition());
player.addGameObject(prefab);

Die Methode setMaterialParameter ist unter JavaDoc: Class Prefab - setMaterialParameter zu finden.

VFX Graph

Methoden, mit denen VFX-Graph-Effekte eines Prefabs oder seiner Kind-Elemente gesteuert werden können. Ein VFX-Graph-Effekt besteht aus vielen kleinen Partikeln, die nach definierten Regeln animiert werden.
Hinweis: Bei VFX Graph kann es bei einem Unity-Versionswechsel des Spiels zu Inkompatibilitäten kommen, wenn die Shader mit dem Visual Effect Graph erstellt wurden. Siehe dazu den Hinweis im AssetBundles Erstellung Tutorial.

Prefab.setVFXParameter(...) – Setzt einen Parameter eines VFX-Effekts. Es gibt 6 weitere Überladungen dieser Methode mit unterschiedlichen Parametern (int, boolean, Vector2f, Vector3f, Vector4f, TextureAsset) im JavaDoc: Class Prefab.
Prefab.playVFX(...) – Startet einen VFX-Effekt.
Prefab.stopVFX(...) – Stoppt einen VFX-Effekt.
Prefab.reinitVFX(...) – Initialisiert einen VFX-Effekt neu.
Prefab.setVFXPaused(...) – Pausiert oder setzt einen VFX-Effekt fort.
Prefab.setVFXPlayRate(...) – Setzt die Wiedergabegeschwindigkeit eines VFX-Effekts.

Weitere Methoden rund um VFX Graph sind im JavaDoc: Class Prefab zu finden.

Position, Rotation und Layer

Methoden, mit denen Position, Rotation, Skalierung und Layer des Prefabs selbst oder einzelner Kind-Elemente gesetzt oder asynchron ausgelesen werden können.

Prefab.setPrefab(...)... – Weist dem Prefab-Objekt ein PrefabAsset zu.
Prefab.setActive(...)... – Aktiviert oder deaktiviert das Prefab (oder ein Kind-Element). Wird dies auf „false“ gesetzt, wird das Objekt in der Spielszene deaktiviert; d. h., es ist nicht mehr sichtbar und kollidiert nicht mehr mit dem Spieler oder der Welt. Dies wirkt sich automatisch auch auf alle untergeordneten Elemente aus.

Standardmäßig ist ein Objekt als aktiv eingestellt.

Prefab.setLayer(...)... – Setzt den Layer des Prefabs (oder eines Kind-Elements).
Prefab.setLocalPosition(...)... – Setzt die lokale Position des Prefabs relativ zum übergeordneten Objekt.
Prefab.setLocalRotation(...)... – Setzt die lokale Rotation des Prefabs.
Prefab.setLocalScale(...)... – Setzt die lokale Skalierung des Prefabs.
Prefab.readLocalPosition(...)... – Liest die aktuelle lokale Position eines Kind-Elements asynchron über einen Callback.
Prefab.readLocalRotation(...)... – Liest die aktuelle lokale Rotation eines Kind-Elements asynchron.
Prefab.readWorldPosition(...)... – Liest die aktuelle Welt-Position eines Kind-Elements.
Prefab.readWorldRotation(...)... – Liest die aktuelle Welt-Rotation eines Kind-Elements.

Weitere Methoden rund um Position, Rotation, Layer und asynchrones Lesen sind im JavaDoc: Class Prefab zu finden.

Code-Beispiele

In diesem Abschnitt sind ausgewählte Java-Codebeispiele zusammengefasst, die zeigen, wie die Methoden der Prefab Klasse in der Praxis verwendet werden.

Beispiel: Load a prefab from an asset bundle

Lädt ein AssetBundle aus dem Plugin-Ordner, holt daraus ein PrefabAsset und erzeugt daraus ein Prefab-Objekt. Das Prefab wird mit einem Layer und einer Anfangsposition versehen und abschließend an die Spieler-Welt angehängt, sodass es für diesen Spieler sichtbar wird.
Weiterführende Informationen zur Erstellung von AssetBundles enthält das AssetBundles Erstellung Tutorial.

//AssetBundle aus dem Plugin-Ordner laden
AssetBundle bundle = AssetBundle.loadFromFile(getPath() + "/assets/MyBundle.bundle");

//PrefabAsset aus dem AssetBundle laden
PrefabAsset asset = PrefabAsset.loadFromAssetBundle(bundle, "MyPrefab.prefab");

//Prefab-Objekt aus dem PrefabAsset erzeugen
Prefab prefab = new Prefab(asset);

//Layer setzen (bestimmt, wie der Spieler mit dem Prefab kollidiert)
prefab.setLayer(Layer.DEFAULT);

//Position setzen - zum Beispiel an der Spielerposition spawnen
prefab.setLocalPosition(player.getPosition());

//An die Spielerwelt anhängen (sodass es für diesen Spieler sichtbar wird)
player.addGameObject(prefab);

Die Methode ist unter JavaDoc: Class Prefab zu finden.

Wichtige Methoden

AssetBundle.loadFromFile – Lädt ein AssetBundle von einer Datei auf der Festplatte.
PrefabAsset.loadFromAssetBundle – Lädt ein PrefabAsset aus einem zuvor geladenen AssetBundle anhand seines Pfads.
Prefab – Erstellt ein Prefab-Objekt aus dem geladenen PrefabAsset.
Prefab.setLayer – Legt den Layer des Prefabs fest (zum Beispiel Layer.DEFAULT, Layer.ITEM oder Layer.OBJECT).
Prefab.setLocalPosition – Setzt die lokale Position des Prefabs.
Player.addGameObject – Hängt das Prefab an die Welt des Spielers an, sodass es nur für diesen Spieler sichtbar und aktiv ist.

Beispiel: readLocalPosition

Liest die aktuelle lokale Position des untergeordneten Objekts "inner2" (welches sich innerhalb des Objekts "inner" befindet, das wiederum ein Kind des Prefabs ist) und gibt das Ergebnis asynchron im Callback aus. Dieses Beispiel ist nützlich, wenn die Position durch eine GameObject-Physik oder einen Animator verändert wurde und daher von der ursprünglich gesetzten Position abweichen kann.

prefab.readLocalPosition("inner/inner2", player, (pos) -> {
    System.out.println("Position of 'inner2': " + pos);
});

Die Methode ist unter JavaDoc: Class Prefab - readLocalPosition zu finden.

Wichtige Methoden

Prefab.readLocalPosition – Liest die aktuelle lokale Position eines untergeordneten Elements asynchron über einen Callback.

Beispiel: setMaterialParameter (Vector3 mit Pfad)

Setzt einen Vector3-Material-Parameter an einem bestimmten untergeordneten Material. Der Pfad wird durch Slashes getrennt (zum Beispiel "child/another_child") und verweist auf das entsprechende Renderer-Element innerhalb des Prefabs.

Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
prefab.setMaterialParameter("child/another_child", "_PositionProperty", new Vector3f(0f, 10f, 0f));
prefab.setLocalPosition(player.getPosition());
player.addGameObject(prefab);

Die Methode ist unter JavaDoc: Class Prefab - setMaterialParameter zu finden.

Wichtige Methoden

Prefab.setMaterialParameter – Setzt einen Material-Parameter an einem untergeordneten Material über den Pfad zum Element.

Beispiel: setMaterialParameter (Farbe via Vector4)

Setzt die Basisfarbe eines Materials auf Rot. Vector4 wird hier verwendet, um eine Farbe zu übergeben (RGBA). Der Pfad "child/anotherchild" verweist auf das Material des entsprechenden untergeordneten Renderers.

Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
prefab.setMaterialParameter("child/anotherchild", "_BaseColor", new Vector4f(1f, 0f, 0f, 1f));  // <- Farbe Rot
prefab.setLocalPosition(player.getPosition());
player.addGameObject(prefab);

Die Methode ist unter JavaDoc: Class Prefab - setMaterialParameter zu finden.

Wichtige Methoden

Prefab.setMaterialParameter – Setzt einen Material-Parameter; eignet sich auch für Farbparameter wie _BaseColor.

Beispiel: setMaterialParameter (Texture)

Weist einem Material einen neuen Texture-Asset zu, zum Beispiel eine neue Textur als Albedo-Map (entspricht _BaseColorMap in HDRP).

Prefab prefab = new Prefab(PrefabAsset.loadFromFile(...));
prefab.setMaterialParameter("child/anotherchild", "_BaseColorMap", TextureAsset.loadFromFile(...));
prefab.setLocalPosition(player.getPosition());
player.addGameObject(prefab);

Die Methode ist unter JavaDoc: Class Prefab - setMaterialParameter zu finden.

Wichtige Methoden

Prefab.setMaterialParameter – Setzt einen Texture-Material-Parameter an einem untergeordneten Material über den Pfad zum Element.
TextureAsset.loadFromFile – Lädt eine TextureAsset aus einer Datei auf der Festplatte.