Cave: Einstiegshandbuch

Jetzt lass uns verstehen, wie Charaktere und Animationen in Cave funktionieren. Ein Charakter ist nicht nur ein 3D-Modell, das sich im Level bewegt. In einem echten Spiel-Setup kombiniert es normalerweise Physik, Bewegungslogik, ein sichtbares Mesh, ein Skelett, Animationen und Code oder Logic Bricks, die entscheiden, welche Animation abgespielt werden soll.

Um dies praktisch zu machen, verwenden wir die Standard-Player-Vorlage aus den Starter-Projekten von Cave als Hauptreferenz. Wenn Sie ein Third Person Game oder Top Down Game erstellen, generiert Cave einen Spieler, der bereits sich bewegt, einen sichtbaren animierten Charakter hat und grundlegende Lokomotionsanimationen abspielt.

Diese Lektion zeigt Ihnen, wie dieses Setup organisiert ist und wie Sie Animationen von Python aus steuern können.

Sie werden lernen:

• Wie die Starter-Player-Vorlage aufgebaut ist.
• Warum das visuelle Mesh eine Kind-Entity ist, anstatt auf der Wurzel-Player-Entity zu sein.
• Was die Animation-Komponente macht.
• Wie man den Animator von Python aus erhält (eine ähnliche Logik gilt für Logic Bricks).
• Wie man Animationen nach Namen abspielt.
• Wie Mischen, Schichten und Knochenspiegelungen funktionieren.
• Wie Animations-Callbacks und Steckdosen ins System passen.

Die Struktur der Player-Vorlage

Im Starter-Projekt ist der Player eine Entity-Vorlage. Das bedeutet, das Spieler-Setup ist wiederverwendbar und kann in mehreren Szenen platziert werden.

Die Struktur sieht ungefähr so aus:

Die genauen Kinder können je nach den ausgewählten Projektoptionen variieren, aber die wichtige Idee ist, dass die Wurzel-Player-Entity das Gameplay-Setup besitzt, während die Kind-Mesh-Entity den sichtbaren animierten Charakter besitzt.

Der Starter-Gegner verwendet eine sehr ähnliche Idee. Die Wurzel-Entity des Gegners hat Charakterphysik und Verhalten, und die Kind-Mesh-Entity enthält das sichtbare Mesh und die Animation-Komponente.

Die Wurzel-Player-Entity

Die Wurzel-Player-Entity repräsentiert den Gameplay-Charakter. Sie enthält normalerweise:

• Eine Transform-Komponente.
• Eine Character-Komponente.
• Python-Komponenten für Spielerbewegung, UI, Animationshilfen und andere Gameplay-Logik.
• Eigenschaften wie Gesundheit oder optionale Verhaltensparameter.
• Kinder, die für Kamera, UI, visuelles Mesh und Hilfsobjekte verwendet werden.

Die Character-Komponente ist besonders wichtig, da sie die physikalischen Zustände des Charakters behandelt: Laufen, Springen, Kollision, Steigungen und Bewegung gegen die Welt. Das bedeutet, dass die Wurzel-Player-Entity hauptsächlich für Gameplay und Physik verantwortlich ist.

Die Mesh-Kind-Entity

Innerhalb der Player-Vorlage gibt es eine Kind-Entity namens Mesh. Dieses Kind enthält normalerweise:

• Eine Transform-Komponente.
• Eine oder mehrere Mesh-Komponenten.
• Eine Animation-Komponente.

Die Mesh-Komponente verleiht dem Charakter sein sichtbares 3D-Modell und Material. Wenn der Charakter mehrere Materialien verwendet, kann Cave dies mit mehreren Mesh-Komponenten darstellen, die der gleichen Multi-Material-Regel folgen, die in der Importlektion erklärt wurde.

Die Animation-Komponente ist das, was das Skelett auswertet und Animationen abspielt.

Also, einfach gesagt:

Diese Trennung ist absichtlich.

Warum das Mesh eine Kind-Entity ist

Sie fragen sich vielleicht, warum das Mesh nicht direkt auf der Wurzel-Player-Entity platziert ist.

Der Grund ist, dass der physikalische Charakter und der sichtbare animierte Charakter oft unterschiedliche Transformationen benötigen.

Die Wurzel-Player-Transformation repräsentiert den Gameplay-Körper. Es ist das, was sich durch die Welt bewegt, mit Wänden kollidiert und die Charakter-Komponente trägt. Die Kind-Mesh-Transformation repräsentiert, wie der Charakter aussieht.

Diese Trennung ist in vielen Situationen nützlich:

• Das Mesh benötigt möglicherweise eine andere Skalierung als die physikalische Kapsel.
• Das Mesh benötigt möglicherweise eine kleine Verschiebung, um mit der Charakterkollision übereinzustimmen.
• Das Mesh muss unabhängig vom Bewegungskörper rotieren können.
• Das Mesh muss sich in Bewegungrichtung ausrichten, während die Wurzel eine Gameplay-Ausrichtung behält.
• Das Mesh muss möglicherweise nach vorne gerichtet bleiben, während der Spieler sich seitlich bewegt.

Stellen Sie sich zum Beispiel vor, der Spieler bewegt sich nach links. Wenn Sie eine ordnungsgemäße "nach links laufen"-Animation haben, möchten Sie möglicherweise, dass das Charakter-Mesh weiterhin nach vorne zeigt, während die Animation die seitliche Bewegung handhabt. Wenn Sie jedoch keine seitliche Animation haben, möchten Sie möglicherweise, dass das Mesh sich nach links dreht, damit der Charakter visuell in diese Richtung geht.

Beide Fälle sind valide.

Sie erfordern separate Transformationen:

Deshalb hält der Starter-Spieler und der Gegner das animierte Mesh als Kind-Entity.

Was die Animation-Komponente macht

Die Animation-Komponente ist die Hauptkomponente, die verwendet wird, um skelettale Animationen auf einer Entity abzuspielen.

Sie benötigt:

• Ein Armature.
• Eine Standard-Animation.
• Eine gültige Mesh-Komponente auf der gleichen Entity (oder mehrere).

Das Skelett definiert das Skelett. Die Animation definiert, wie sich dieses Skelett über die Zeit bewegt. Die Animation-Komponente wertet die endgültige animierte Pose aus und wendet sie auf den sichtbaren Charakter an.

Im Standard-Starter-Spieler verwendet das Kind-Mesh:

• Proto Mesh
• Proto Mat
• Proto Armature
• p-idle als Standardanimation (Idle-Animation)

Diese Starter-Assets sind da, damit Sie sofort einen funktionierenden animierten Charakter inspizieren können.

Armaturen, Animationen und Retargeting

• Ein Armature ist das Skelett des Charakters. Es enthält die Knochen, denen das Mesh folgt.
• Eine Animation speichert die Bewegung über die Zeit für Knochen in einem Armature.

Die Animation-Komponente verbindet diese Teile miteinander:

Cave kann auch Animationen bei Bedarf retargeten. Wenn die Animation, die abgespielt wird, zu einem anderen kompatiblen Armature gehört, kann die Animation-Komponente Retargeting verwenden, um diese Bewegung auf das aktuelle Armature anzuwenden.

Retargeting ist nützlich, wenn Sie Animationen über kompatible Charaktere hinweg wiederverwenden möchten, hängt jedoch immer von der Qualität und Kompatibilität der importierten Rigs ab. Wenn eine Animation verdreht, versetzt oder merkwürdig aussieht, überprüfen Sie das Quell-Rig, das importierte Armature und die Retargeting-Einstellungen.

Den Animator von Python aus erhalten

Jetzt lassen Sie uns erkunden, wie wir Charaktere durch Logik animieren können.

In Cave-Projekten ist es gängige Praxis, die Spieler-Gameplay-Logik auf der Wurzel-Player-Entity zu halten und dann von diesem Code aus auf die Kind-Mesh-Entity zuzugreifen. Die Standard-Starter-Skripte folgen dieser Idee.

Hier ist das grundlegende Muster:

import cave

class PlayerAnimationExample(cave.Component):
    def start(self, scene: cave.Scene):
        self.mesh : cave.Entity = self.entity.getChild("Mesh")
        self.animator : cave.AnimationComponent = self.mesh.get("Animation")

    def update(self):
        # Beispiel: Abspielen einer Idle-Animation.
        self.animator.playByName("p-idle", blend=0.2, loop=True)

In diesem Beispiel:

• self.entity ist die Wurzel-Player-Entity.
• getChild("Mesh") findet die visuelle Kind-Entity.
• self.mesh.get("Animation") erhält die Animation-Komponente.
• Die Variable wird animator genannt, was der gängigen Benennungspraxis in Cave-Skripten entspricht.
• playByName(...) spielt eine Animationsressource nach Namen ab.

Dies ist die grundlegende Verbindung, die Sie benötigen, bevor Sie Animationen durch Code steuern können.

Animationen nach Namen abspielen

Die häufigste Methode, die Sie verwenden werden, ist playByName.

Ihre grundlegende Verwendung sieht so aus:

self.animator.playByName("p-walk", blend=0.2, loop=True)

Die wichtigen Parameter sind:

Zum Beispiel:

self.animator.playByName("p-idle", blend=0.2, loop=True)
self.animator.playByName("p-walk", blend=0.2, loop=True)
self.animator.playByName("p-run", blend=0.2, loop=True)
self.animator.playByName("p-fall", blend=0.2, loop=True)

Dies sind die gleichen Arten von Aufrufen, die von den Standard-Spieler- und Gegner-Skripten verwendet werden.

Ein einfaches Lokomotionsbeispiel

Ein gängiges Spieleranimations-Setup ist:

• Idle abspielen, wenn der Charakter steht.
• Gehen abspielen, wenn sich der Charakter bewegt.
• Laufen abspielen, wenn sich der Charakter beim Laufen bewegt.
• Fallen abspielen, wenn der Charakter sich nicht am Boden befindet.

Hier ist ein vereinfachtes Beispiel:

import cave

class SimplePlayerAnimator(cave.Component):
    def start(self, scene: cave.Scene):
        self.character : cave.CharacterComponent = self.entity.get("Character")

        self.mesh : cave.Entity = self.entity.getChild("Mesh")
        self.meshTransform : cave.TransformComponent = self.mesh.getTransform() if self.mesh else None
        self.animator      : cave.AnimationComponent = self.mesh.get("Animation") if self.mesh else None

    def update(self):
        if self.animator is None or self.character is None:
            return

        direction = self.character.getWalkDirection()
        isMoving = direction.length() > 0
        isRunning = False # Ersetzen Sie dies durch Ihre eigene Eingabe oder Gameplay-Bedingung.

```python
if self.character.onGround():
            if isMoving:
                if isRunning:
                    self.animator.playByName("p-run", blend=0.2, loop=True)
                else:
                    self.animator.playByName("p-walk", blend=0.2, loop=True)
            else:
                self.animator.playByName("p-idle", blend=0.2, loop=True)
        else:
            self.animator.playByName("p-fall", blend=0.2, loop=True)

Dieses Beispiel ist absichtlich einfach. Der echte Start-Controller behandelt auch Eingaben, Bewegungsrichtung, Springen, optionales Punkt-und-Klick-Verhalten und Mesh-Rotation, aber die Animationsidee bleibt dieselbe.

Mesh-Rotation in Bewegungsrichtung

Da das visuelle Mesh-Objekt seine eigene Transformation hat, können Sie es getrennt vom Wurzel-Player drehen.

Der Startspieler tut dies, wenn sich die Figur bewegt:

if direction.length() > 0 and self.meshTransform:
    self.meshTransform.lookAtSmooth(
        self.entity.getTransform().transformDirection(-direction),
        6.0 * cave.getDeltaTime()
    )

Die wichtige Idee ist nicht die genaue Mathematik. Die wichtige Idee ist, dass der Gameplay-Körper und das visuelle Mesh separat gesteuert werden können.

Dies ermöglicht es Ihnen zu wählen, wie die Figur ausgerichtet sein soll:

• In Bewegungsrichtung ausrichten.
• Während des Seitwärtsbewegens nach vorne ausgerichtet bleiben.
• Sanft in die gewünschte Richtung drehen.
• Verschiedene visuelle Ausrichtungsregeln für verschiedene Spielmodi verwenden.

Dies ist einer der Hauptgründe, warum die Startfigur ein untergeordnetes Mesh-Objekt hat.

Animationsmischung

Animationsmischung macht Übergänge geschmeidiger.

Ohne Mischung kann der Wechsel von einer Animation zur anderen sofort ruckartig erfolgen. Mit Mischung kann Cave sanft zwischen Animationen auf derselben Ebene übergehen.

Zum Beispiel:

# Von diesem:
self.animator.playByName("p-idle", blend=0.2, loop=True)

# Zu diesem:
self.animator.playByName("p-walk", blend=0.2, loop=True)

Hier bedeutet blend=0.2, dass Cave über 0.2 Sekunden in die neue Animation überblendet.

Dies ist besonders wichtig für Charaktere. Ein Spieler kann harte Animationssprünge sehr leicht bemerken, selbst in einem Prototyp.

Gute Anfänger-Mischwerte sind in der Regel klein:

• 0.1 für sehr schnelle Übergänge.
• 0.2 für normale Bewegungsübergänge.
• 0.4 oder mehr für langsamere, schwerere Übergänge.

Sie sollten dies nach Gefühl einstellen.

Animationsschichten

Cave unterstützt mehrere Animationsschichten. Jede Schicht kann ihre eigene Animation abspielen, und höhere Schichten können über niedrigeren Schichten gestapelt werden. Sie können Animationen in jeder gewünschten Schicht ausführen.

Die Standardbewegungsanimation läuft normalerweise auf Schicht 0.

Zum Beispiel:

self.animator.playByName("p-walk", blend=0.2, layer=0, loop=True)

Wenn Sie eine obere Körperaktionsanimation haben, wie einen Angriff, Zielen oder Nachladen, können Sie sie auf einer anderen Schicht abspielen:

self.animator.playByName("Attack", blend=0.1, layer=1, loop=False)

Die Idee ist:

Dies ermöglicht es dem Charakter, weiterhin zu gehen, während eine andere Schicht eine Aktion hinzufügt.

Schichtgewichte

Jede Schicht hat ein Gewicht, das steuert, wie viel Einfluss diese Schicht hat.

Sie können es von Python aus ändern:

self.animator.setLayerWeight(1, 1.0)

Sie können es auch lesen:

weight = self.animator.getLayerWeight(1)

Ein Gewicht von 1.0 bedeutet, dass die Schicht voll aktiv ist. Ein Gewicht von 0.0 bedeutet, dass sie keinen sichtbaren Einfluss hat.

Schichtgewichte sind nützlich, wenn Sie eine Aktionsschicht ein- oder ausblenden möchten, wie das langsame Heben einer Waffe, Zielen oder das Überblenden in eine spezielle Haltung.

Es ist erwähnenswert, dass der Mischparameter nur Animationen zwischen denselben Schichten mischt. Und wir werden keine Animationen mischen, die auf unterschiedlichen Schichten abgespielt werden. Wenn Sie eine Animation auf Schicht 0 abspielen und dann plötzlich eine Animation auf Schicht 1 abspielen, egal wie hoch der Mischwert ist, wird sie nicht zwischen ihnen gemischt. Es wird nur gemischt, wenn bereits eine andere Animation auf Schicht 1 ausgeführt wurde. Wenn Sie zwischen Schichten mischen möchten, müssen Sie eine benutzerdefinierte Logik erstellen, um das Schichtgewicht zu verwenden.

Knochenfilter

Knochenfilter steuern, welche Knochen von einer Schicht betroffen sind und wie viel Einfluss jeder Knochen erhält.

Das macht Oberkörperanimation möglich.

Zum Beispiel möchten Sie möglicherweise:

• Schicht 0 soll den gesamten Körper steuern.
• Schicht 1 soll nur die Wirbelsäule, Arme, Hände und Waffenknochen steuern.

In Python können Sie einen Filter für eine Schicht erstellen und den Einfluss auf einen Knochen und seine Kinder zuweisen:

def setupUpperBodyLayer(self):
    armature = self.animator.armature.get()
    spine = armature.getBone("mixamorig:Spine")

    upperBody = self.animator.createLayerFilter(1)
    upperBody.defaultBlend = 0.0
    upperBody.setToBone(spine, 1.0, recursive=True)

In diesem Beispiel:

• defaultBlend = 0.0 bedeutet, dass die Schicht standardmäßig keinen Knochen beeinflusst.
• setToBone(spine, 1.0, recursive=True) bedeutet, dass die Wirbelsäule und deren Kinder vollständig betroffen sind.
• Schicht 1 kann nun für Oberkörperanimationen verwendet werden.

Ihre Knotennamen hängen von der Armatur ab, die Sie importiert haben. Überprüfen Sie immer Ihre Armatur und verwenden Sie die richtigen Knotennamen für Ihren Charakter.

Praktisches Schichtenbeispiel

Stellen Sie sich einen Charakter in der dritten Person vor, der gleichzeitig gehen und angreifen kann.

Eine mögliche Konfiguration ist:

Der Code könnte so aussehen:

import cave

class CombatAnimator(cave.Component):
    def start(self, scene: cave.Scene):
        self.mesh = self.entity.getChild("Mesh")
        self.animator : cave.AnimationComponent = self.mesh.get("Animation") if self.mesh else None

        if self.animator:
            armature = self.animator.armature.get()
            spine = armature.getBone("mixamorig:Spine")

            upperBody = self.animator.createLayerFilter(1)
            upperBody.defaultBlend = 0.0
            upperBody.setToBone(spine, 1.0, recursive=True)
            self.animator.setLayerWeight(1, 1.0)

    def playWalk(self):
        self.animator.playByName("p-walk", blend=0.2, layer=0, loop=True)

    def playAttack(self):
        self.animator.playByName("Attack", blend=0.1, layer=1, loop=False)

Dieses Beispiel geht davon aus, dass Sie über ein Animationsobjekt mit dem Namen Attack verfügen. Wenn Ihr Projekt einen anderen Animationsnamen verwendet, verwenden Sie stattdessen diesen Namen.

Die wichtige Idee ist, dass die Fortbewegung auf Schicht 0 bleibt, während der Angriff auf Schicht 1 abgespielt wird und nur die gefilterten Knochen beeinflusst.

Animations-Rückrufe

Animationen können zu bestimmten Zeiten Python-Code ausführen.

Cave unterstützt Rückrufe wie:

• Beim Start der Animation.
• Am Ende der Animation.
• Bei einem bestimmten Animationsrahmen.

Rückrufe sind nützlich, wenn Animationen Gameplay oder Effekte auslösen sollen.

Beispiele:

• Spiele einen Trittgeräusch.
• Erzeuge Staub bei einem Schritt.
• Füge Schaden bei einem Angriffsrahmen zu.
• Beginne eine Waffenspur.
• Lenkere einen Partikeleffekt.
• Benachrichtige die Logik, dass eine Animation beendet ist.

Animationen kennen oft das genaue Timing besser als der Code. Wenn ein Schwert nur dann Schaden verursachen soll, wenn der Schwung den Zielbereich erreicht, kann ein Animationsrückruf diesen Gameplay-Moment auf dem richtigen Frame platzieren.

Fußschritt-Rückrufbeispiel

Startprojekte können Fußschritt-Rückrufe in Gehen- und Laufen-Animationen enthalten. Diese zu überprüfen ist eine gute Möglichkeit, einen praktischen Animationsrückruf in Aktion zu sehen.

Die Idee ist einfach:

1. Die Animation weiß, wann der Fuß den Boden berührt.
2. Der Rückruf wird auf diesem Frame platziert.
3. Der Rückruf spielt einen Ton ab oder erzeugt einen kleinen Effekt.

Innerhalb eines Animationsrückrufs stellt Cave nützliche Variablen zur Verfügung, wie:

• entity, die zugehörige Entität.
• animator, die Animationskomponente.
• handle, die animierte Schicht/Handler, die abgespielt wird.

Ein sehr kleiner Fußschritt-Rückruf könnte so aussehen:

cave.playSound("Footstep Grass", volume=0.5)

Sie können später diese Idee erweitern, um je nach Bodenmaterial, Geschwindigkeit des Charakters oder aktuellem Zustand unterschiedliche Geräusche auszuwählen.

Wiederverwendbare Animations-Rückrufe

Rückrufe gehören zum Animationsobjekt.

Das bedeutet, dass wenn mehrere Entitäten dieselbe Animation abspielen, der Rückruf für jede Entität, die sie verwendet, ausgeführt werden kann.

Dadurch werden Rückrufe wiederverwendbar. Zum Beispiel kann dieselbe Gehen-Animation Fußschrittgeräusche für jeden Charakter auslösen, der sie abspielt, solange der Rückrufcode die zugehörige Entität korrekt verwendet.

Die Animation speichert das Timing. Die Entität bietet den Kontext.

Erweiterte Pose-Rückrufe

Cave unterstützt auch Rückrufe nach der Auswertung über Python. Diese finden statt, nachdem die Animationskomponente die Armaturpose bewertet hat.

Dies ist eine erweiterte Funktion, kann jedoch verwendet werden für:

• Inverse Kinematik.
• Kopfzielen.
• Waffenvisierung.
• Fußplatzierung.
• Letzte Pose-Anpassungen.

Das Starter-Player Toolkit enthält ein Fuß-IK-Beispiel, das dieses Konzept verwendet. Es erhält das Mesh-Kind, erhält die Animations-Komponente und registriert dann eine Methode mit:

self.animator.addPostEvaluationCallback(self.postEvaluation)

Sie müssen nicht sofort IK-Systeme schreiben, aber es ist nützlich zu wissen, dass Cave es Python ermöglicht, die endgültige Pose nach der normalen Animation abzuspielen, anzupassen.

Animations-Socket-Komponente

Die Animations-Socket-Komponente ermöglicht es einer untergeordneten Entität, einem Knochen einer übergeordneten animierten Entität zu folgen.

Die untergeordnete Entität muss unter einem Elternteil stehen, der eine Animationskomponente hat. Dann kann der Socket einen Knochen auswählen und die Position, Drehung und optional die Skalierung von diesem Knochen übernehmen, mit Offsets, falls erforderlich.

Sockets sind nützlich, um Dinge an animierte Charaktere anzufügen:

• Schwert in einer Hand.
• Waffe in einer Hand.
• Schild an einem Arm.
• Helm auf einem Kopf.
• Rucksack an einem Wirbelsäulen-Bon.
• Requisit, das an einer Hand befestigt ist.

Zum Beispiel, wenn ein Charakter ein Schwert hält, kann das Schwert eine Kind-Entity mit einer Animation Socket-Komponente sein, die dem Handknochen folgt. Während der Charakter angreift, rennt oder stillsteht, bleibt das Schwert an der richtigen animierten Position befestigt.

Was Sie sich merken sollten

• Der Starter-Spieler ist eine Vorlage mit einer Wurzel-Player-Entity und einer Kind-Mesh-Entity.
• Die Wurzel-Player kümmert sich normalerweise um Physik, Bewegung, Eigenschaften und Gameplay-Logik.
• Die Kind-Mesh kümmert sich normalerweise um das sichtbare Modell, Material, Skelett und Animationskomponente.
• Diese Trennung gibt dem physikalischen Körper und dem visuellen Charakter separate Transformationen.
• Die Animationskomponente spielt Skelettanimationen mit einem Skelett und Animationsassets.
• In Python ist es üblich, die Animationskomponente animator zu nennen.
• playByName spielt ein Animationsasset nach Namen ab und unterstützt Mischen, Schleifen und Schichten.
• Schichten ermöglichen es, mehrere Animationen übereinander zu stapeln.
• Knochenfilter ermöglichen es einer Schicht, nur einen Teil des Skeletts zu beeinflussen.
• Animations-Rückrufe verbinden die Animationszeit mit Gameplay-Ereignissen.
• Animationsstecker befestigen Requisiten an animierten Knochen.

Wenn Sie die Starter-Player- oder Enemy-Vorlage inspizieren, verwenden Sie diese Struktur als Ihre Karte: Wurzel-Entity für Gameplay, Kind-Mesh-Entity für visuelle und animierte Elemente.