Daj głos NPC-om w Unity dzięki ElevenAgents

Gracze mogą teraz podejść do postaci w twojej grze Unity i porozmawiać z nią na głos. Nowe SDK ElevenAgents dla Unity łączy scenę z agentem głosowym ElevenLabs. Nasłuchuje przez mikrofon gracza, odtwarza głos agenta przez AudioSource i obsługuje sesję przez API Conversation.

Ten sam kod działa w Edytorze, kompilacjach desktopowych i WebGL, a iOS, Android oraz XR są w becie.

Rozpocznij rozmowę

Sesja wymaga identyfikatora agenta utworzonego w panelu ElevenLabs, gdzie znajduje się prompt i głos. W naszym przykładzie GettingStarted, dołączonym do SDK, trigger collider wokół postaci otwiera sesję, gdy gracz wejdzie w jego obszar, i zamyka ją, gdy go opuści:

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 zwraca wynik, gdy połączenie jest otwarte, a urządzenia audio gotowe, oraz wybiera odpowiedni transport dla docelowej kompilacji. EndSession nie robi nic, jeśli sesja już się zakończyła.

Co zawiera SDK

Głosy dobiegające od postaci

Domyślnie głos agenta jest odtwarzany w 2D. Przekaż własne AudioSource jako OutputAudioSource, a głos będzie dobiegał od postaci.

GetOutputVolume() zwraca aktualny poziom głosu agenta od 0 do 1 na każdej platformie. Przykład używa go, by kostka podskakiwała podczas mówienia; możesz też w ten sposób sterować animacją ust.

Jeden agent, wiele postaci

Zmienne dynamiczne wypełniają placeholdery, takie jak {{mood}}, w prompcie i pierwszej wiadomości agenta, dzięki czemu każda postać może wysłać własne wartości przy rozpoczęciu sesji. Wartości mogą być ciągami znaków, liczbami lub wartościami logicznymi. W przykładzie żółta, szczęśliwa kostka i czerwona, zła kostka korzystają z jednego agenta:

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

Przy większych zmianach Overrides zastępują część konfiguracji agenta dla jednej sesji, na przykład pierwszą wiadomość lub głos. Każde nadpisanie trzeba najpierw włączyć w ustawieniach Security agenta.

Postaci, które wiedzą, co się dzieje

SendContextualUpdate informuje agenta o wydarzeniach w grze w trakcie rozmowy, bez przerywania mu i dodawania tury, której gracz nie wypowiedział:

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

Postaci, które działają w grze

Narzędzia klienckie pozwalają agentowi uruchamiać kod gry. Zdefiniuj narzędzie w ustawieniach agenta, a potem zarejestruj handler pod tą samą nazwą:

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

SDK deserializuje parametry narzędzia za pomocą Newtonsoft Json i wysyła agentowi to, co zwróci handler. Handlery mogą zwracać Awaitable dla zadań, które wymagają czasu, oraz zgłaszać ClientToolException, by przekazać agentowi przyczynę błędu.

Zdarzenia i sterowanie

Zdarzenia takie jak UserTranscriptReceived, AgentResponded, ModeChanged i Interrupted są wywoływane w głównym wątku Unity, więc możesz bezpośrednio aktualizować z nich UI. Metody obejmują wprowadzanie tekstu przez SendUserMessage, wyciszanie przez SetMicMuted, SetVolume, dane częstotliwości dla wizualizacji oraz zmianę urządzeń wejściowych i wyjściowych w trakcie sesji. Wszystkie znajdziesz w dokumentacji SDK Unity.

Obsługiwane platformy

SDK wybiera transport dla każdego celu.

• iOS i Android: poproś o dostęp do mikrofonu przed rozpoczęciem sesji.
• WebGL: włącz Use WebAssembly.Table w Publishing Settings. Jeśli ta opcja jest wyłączona, SDK przerwie kompilację i wyświetli instrukcje. Play Mode nie działa, gdy WebGL jest aktywnym celem kompilacji, więc testuj na platformie desktopowej.
• Audio WebGL: głos jest odtwarzany przez Web Audio API, więc niektóre ustawienia AudioSource, takie jak routing miksera i efekt Dopplera, nie są przenoszone. Sesje WebRTC ignorują OutputAudioSource.

Pełną listę znajdziesz w informacjach o kompatybilności.

Zacznij

1. Utwórz agenta w panelu ElevenLabs. Na pierwszy test wyłącz Authentication w jego ustawieniach Security, aby gra mogła połączyć się wyłącznie za pomocą identyfikatora agenta.
2. W Unity otwórz Window > Package Manager > + > Install package from git URL i przypnij wersję: https://github.com/elevenlabs/unity.git#v0.1.0
3. Zaimportuj przykład GettingStarted, wklej identyfikator agenta i kliknij Play.

Uwaga: przed wydaniem gry włącz ponownie Authentication. Twój serwer poprosi wtedy o krótkotrwały signed URL, a gra przekaże go jako SignedUrl zamiast AgentId. Nigdy nie umieszczaj klucza API ElevenLabs w kompilacji gry.

Przewodnik na początek zajmuje około 10 minut i kończy się kostką, która wita cię, gdy do niej podejdziesz. Pozostałe informacje znajdziesz w dokumentacji SDK Unity, a błędy i prośby o funkcje zgłaszaj w GitHub issues.