Verleihen Sie Ihren Unity-NPCs mit ElevenAgents eine Stimme

Spieler können jetzt zu einem Charakter in Ihrem Unity-Spiel gehen und mit ihm sprechen. Das neue ElevenAgents Unity SDK verbindet eine Szene mit einem ElevenLabs-Sprachagenten. Es hört über das Mikrofon des Spielers zu, gibt die Stimme des Agenten über eine AudioSource wieder und führt die Sitzung über die Conversation API aus.

Derselbe Code läuft im Editor, in Desktop-Builds und in WebGL. iOS, Android und XR befinden sich in der Beta.

Gespräch starten

Eine Sitzung benötigt die ID eines Agenten, den Sie im ElevenLabs-Dashboard erstellt haben und der den Prompt sowie die Stimme enthält. In unserem im SDK enthaltenen GettingStarted-Beispiel öffnet ein Trigger Collider um den Charakter die Sitzung, wenn der Spieler ihn betritt, und schließt sie, wenn er ihn verlässt:

private Conversation activeConversation;

private void OnTriggerEnter(Collider other) => _ = StartTalkingAsync();
private void OnTriggerExit(Collider other) => _ = StopTalkingAsync();

private async Awaitable StartTalkingAsync()
{
    var options = new ConversationOptions { AgentId = agentId };
    activeConversation = await Conversation.StartSessionAsync(options);
}

private async Awaitable StopTalkingAsync()
{
    if (activeConversation == null)
        return;
    await activeConversation.EndSession();
    activeConversation = null;
}

StartSessionAsync wird zurückgegeben, sobald die Verbindung geöffnet und die Audiogeräte bereit sind, und wählt den passenden Transport für das Build-Ziel. EndSession tut nichts, wenn die Sitzung bereits beendet ist.

Was das SDK enthält

Stimmen, die vom Charakter kommen

Standardmäßig wird die Stimme des Agenten in 2D wiedergegeben. Übergeben Sie Ihre eigene AudioSource als OutputAudioSource, dann kommt die Stimme stattdessen vom Charakter.

GetOutputVolume() gibt auf jeder Plattform den aktuellen Pegel des Agenten von 0 bis 1 zurück. Das Beispiel nutzt ihn, um den Würfel beim Sprechen wippen zu lassen. Auf dieselbe Weise kann er eine Mundanimation steuern.

Ein Agent, viele Charaktere

Dynamische Variablen füllen Platzhalter wie {{mood}} im Prompt und in der ersten Nachricht des Agenten. So kann jeder Charakter beim Start seiner Sitzung eigene Werte senden. Werte können Strings, Zahlen oder boolesche Werte sein. Im Beispiel teilen sich ein gelber, fröhlicher Würfel und ein roter, wütender Würfel einen Agenten:

var options = new ConversationOptions
{
    AgentId = agentId,
    OutputAudioSource = audioSource,
    DynamicVariables = new Dictionary<string, object>
    {
        ["color"] = "red",
        ["mood"] = "angry",
    },
};

Für größere Änderungen ersetzen Overrides Teile der Konfiguration des Agenten für eine Sitzung, etwa die erste Nachricht oder die Stimme. Jede Überschreibung muss zuvor in den Security-Einstellungen des Agenten aktiviert werden.

Charaktere, die wissen, was passiert

SendContextualUpdate informiert den Agenten während eines Gesprächs über Spielereignisse, ohne ihn zu unterbrechen oder einen Zug hinzuzufügen, den der Spieler nicht gesagt hat:

activeConversation.SendContextualUpdate("The player picked up the cellar key.");

Charaktere, die im Spiel handeln

Client-Tools ermöglichen es dem Agenten, Spielcode auszuführen. Definieren Sie das Tool in den Einstellungen des Agenten und registrieren Sie dann einen Handler unter demselben Namen:

activeConversation.RegisterTool<OpenDoorParams, string>("open_door", parameters =>
{
    DoorRegistry.Open(parameters.DoorId);
    return $"Door {parameters.DoorId} is open.";
});

Das SDK deserialisiert die Parameter des Tools mit Newtonsoft Json und sendet alles, was der Handler zurückgibt, an den Agenten zurück. Handler können für zeitaufwendige Aufgaben ein Awaitable zurückgeben und eine ClientToolException auslösen, um dem Agenten mitzuteilen, warum etwas fehlgeschlagen ist.

Ereignisse und Steuerung

Ereignisse wie UserTranscriptReceived, AgentResponded, ModeChanged und Interrupted werden auf dem Hauptthread von Unity ausgelöst, sodass Sie die UI direkt darüber aktualisieren können. Methoden decken Texteingaben mit SendUserMessage, Stummschalten mit SetMicMuted, SetVolume, Frequenzdaten für Visualisierungen sowie das Wechseln von Ein- oder Ausgabegeräten während einer Sitzung ab. Die Unity-SDK-Dokumentation führt sie alle auf.

Plattformunterstützung

Das SDK wählt für jedes Ziel den passenden Transport.

• iOS und Android: Fordern Sie die Mikrofonberechtigung an, bevor Sie eine Sitzung starten.
• WebGL: Aktivieren Sie Use WebAssembly.Table in den Publishing Settings. Wenn die Option deaktiviert ist, lässt das SDK den Build mit entsprechenden Anweisungen fehlschlagen. Der Play Mode funktioniert nicht, solange WebGL das aktive Build-Ziel ist. Testen Sie daher auf einem Desktop-Ziel.
• WebGL-Audio: Die Stimme wird über die Web Audio API wiedergegeben. Daher werden einige Einstellungen von AudioSource, etwa Mixer-Routing und Doppler, nicht übernommen. WebRTC-Sitzungen ignorieren OutputAudioSource.

Die Kompatibilitätshinweise enthalten die vollständige Liste.

Erste Schritte

1. Erstellen Sie einen Agenten im ElevenLabs-Dashboard. Deaktivieren Sie für einen ersten Test Authentication in den Security-Einstellungen, damit das Spiel allein mit der Agent-ID eine Verbindung herstellen kann.
2. Öffnen Sie in Unity Window > Package Manager > + > Install package from git URL und fixieren Sie die Release-Version: https://github.com/elevenlabs/unity.git#v0.1.0
3. Importieren Sie das GettingStarted-Beispiel, fügen Sie Ihre Agent-ID ein und drücken Sie Play.

Warnung: Aktivieren Sie Authentication wieder, bevor Sie veröffentlichen. Ihr eigener Server fordert dann eine kurzlebige signierte URL an, und das Spiel übergibt sie als SignedUrl statt als AgentId. Speichern Sie Ihren ElevenLabs-API-Schlüssel niemals in einem Spiel-Build.

Die Anleitung für erste Schritte dauert etwa 10 Minuten und endet mit einem Würfel, der Sie begrüßt, wenn Sie sich nähern. Alles Weitere finden Sie in der Unity-SDK-Dokumentation. Fehler und Funktionswünsche können Sie über GitHub Issues senden.