Dales voz a los NPC de tu juego de Unity con ElevenAgents

Ahora, jugadores pueden acercarse a un personaje de tu juego de Unity y hablar con él en voz alta. El nuevo SDK de Unity de ElevenAgents conecta una escena con un agente de voz de ElevenLabs. Escucha a través del micrófono del jugador, reproduce la voz del agente mediante un AudioSource y ejecuta la sesión a través de la API Conversation.

El mismo código funciona en el Editor, las compilaciones de escritorio y WebGL; iOS, Android y XR están en beta.

Inicia una conversación

Una sesión necesita el ID de un agente que hayas creado en el panel de ElevenLabs, donde se guardan el prompt y la voz. En nuestro ejemplo GettingStarted, incluido con el SDK, un collider de activación alrededor del personaje abre la sesión cuando el jugador entra y la cierra cuando sale:

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 se devuelve cuando la conexión está abierta y los dispositivos de audio están listos, y elige el transporte adecuado para el destino de compilación. EndSession no hace nada si la sesión ya ha terminado.

Qué incluye el SDK

Voces que proceden del personaje

De forma predeterminada, la voz del agente se reproduce en 2D. Pasa tu propio AudioSource como OutputAudioSource para que la voz proceda del personaje.

GetOutputVolume() devuelve el nivel actual del agente, de 0 a 1, en todas las plataformas. El ejemplo lo usa para que el cubo se balancee mientras habla, y también puede controlar una animación de la boca.

Un agente, muchos personajes

Las variables dinámicas rellenan marcadores como {{mood}} en el prompt y el primer mensaje del agente, para que cada personaje pueda enviar sus propios valores al iniciar su sesión. Los valores pueden ser cadenas, números o booleanos. En el ejemplo, un cubo amarillo y feliz y otro rojo y enfadado comparten un agente:

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

Para cambios mayores, Overrides sustituyen parte de la configuración del agente para una sesión, como el primer mensaje o la voz. Primero debes activar cada override en los ajustes de Seguridad del agente.

Personajes que saben lo que ocurre

SendContextualUpdate informa al agente sobre eventos del juego durante la conversación, sin interrumpirlo ni añadir un turno que el jugador no haya dicho:

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

Personajes que actúan en el juego

Las herramientas de cliente permiten que el agente active código del juego. Define la herramienta en los ajustes del agente y, después, registra un controlador con el mismo nombre:

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

El SDK deserializa los parámetros de la herramienta con Newtonsoft Json y devuelve al agente lo que retorne el controlador. Los controladores pueden devolver un Awaitable para tareas que llevan tiempo y lanzar una ClientToolException para indicar al agente por qué algo ha fallado.

Eventos y controles

Eventos como UserTranscriptReceived, AgentResponded, ModeChanged y Interrupted se activan en el hilo principal de Unity, así que puedes actualizar la interfaz directamente desde ellos. Los métodos incluyen entrada de texto con SendUserMessage, silenciar con SetMicMuted, SetVolume, datos de frecuencia para visualizadores y cambiar los dispositivos de entrada o salida durante la sesión. La documentación del SDK de Unity los enumera todos.

Compatibilidad con plataformas

El SDK elige el transporte para cada destino.

• iOS y Android: solicita permiso para usar el micrófono antes de iniciar una sesión.
• WebGL: activa Use WebAssembly.Table en Publishing Settings. Si está desactivado, el SDK hace que la compilación falle con instrucciones. El modo Play no funciona cuando WebGL es el destino de compilación activo, así que prueba en un destino de escritorio.
• Audio de WebGL: la voz se reproduce mediante la API Web Audio, por lo que algunos ajustes de AudioSource, como el enrutamiento del mezclador y el doppler, no se aplican. Las sesiones de WebRTC ignoran OutputAudioSource.

Las notas de compatibilidad incluyen la lista completa.

Empieza

1. Crea un agente en el panel de ElevenLabs. Para una primera prueba, desactiva Authentication en sus ajustes de Security, para que el juego pueda conectarse solo con el ID del agente.
2. En Unity, abre Window > Package Manager > + > Install package from git URL y fija la versión: https://github.com/elevenlabs/unity.git#v0.1.0
3. Importa el ejemplo GettingStarted, pega el ID de tu agente y pulsa Play.

Advertencia: Antes de publicar el juego, vuelve a activar Authentication. Tu propio servidor solicitará entonces una URL firmada de corta duración, y el juego la pasará como SignedUrl en lugar de AgentId. No incluyas nunca tu clave de API de ElevenLabs en una compilación del juego.

La guía de inicio tarda unos 10 minutos y termina con un cubo que te saluda cuando te acercas. Para todo lo demás, consulta la documentación del SDK de Unity y envía errores y solicitudes de funciones a las issues de GitHub.