Donnez une voix à vos PNJ Unity avec ElevenAgents

Les joueurs peuvent désormais s’approcher d’un personnage dans votre jeu Unity et lui parler à voix haute. Le nouveau SDK Unity d’ElevenAgents connecte une scène à un agent vocal ElevenLabs. Il écoute via le microphone du joueur, diffuse la voix de l’agent via un AudioSource et gère la session via l’API Conversation.

Le même code fonctionne dans l’Editor, les builds desktop et WebGL. iOS, Android et XR sont en bêta.

Démarrer une conversation

Une session nécessite l’ID d’un agent que vous avez conçu dans le Dashboard ElevenLabs, où sont définis le prompt et la voix. Dans notre exemple GettingStarted, inclus dans le SDK, un collider de déclenchement autour du personnage ouvre la session lorsque le joueur s’approche et la ferme lorsqu’il s’éloigne :

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 renvoie une valeur une fois la connexion établie et les périphériques audio prêts, puis sélectionne le transport adapté à la cible de build. EndSession ne fait rien si la session est déjà terminée.

Contenu du SDK

Des voix qui viennent du personnage

Par défaut, la voix de l’agent est diffusée en 2D. Transmettez votre propre AudioSource comme OutputAudioSource pour que la voix provienne du personnage.

GetOutputVolume() renvoie le niveau actuel de l’agent, de 0 à 1, sur toutes les plateformes. L’exemple l’utilise pour faire rebondir le cube lorsqu’il parle, et peut aussi animer une bouche de la même manière.

Un agent, plusieurs personnages

Les variables dynamiques renseignent des espaces réservés tels que {{mood}} dans le prompt et le premier message de l’agent. Chaque personnage peut ainsi envoyer ses propres valeurs au démarrage de sa session. Les valeurs peuvent être des chaînes de caractères, des nombres ou des booléens. Dans l’exemple, un cube jaune joyeux et un cube rouge en colère partagent le même agent :

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

Pour des modifications plus importantes, Overrides remplacent une partie de la configuration de l’agent pour une session, comme le premier message ou la voix. Chaque remplacement doit d’abord être activé dans les paramètres Security de l’agent.

Des personnages au fait de la situation

SendContextualUpdate informe l’agent des événements du jeu au cours d’une conversation, sans l’interrompre ni ajouter un tour que le joueur n’a pas prononcé :

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

Des personnages qui agissent dans le jeu

Les outils client permettent à l’agent de déclencher du code de jeu. Définissez l’outil dans les paramètres de l’agent, puis enregistrez un gestionnaire sous le même nom :

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

Le SDK désérialise les paramètres de l’outil avec Newtonsoft Json et renvoie à l’agent ce que retourne le gestionnaire. Les gestionnaires peuvent renvoyer un Awaitable pour les tâches longues et lever une ClientToolException pour indiquer à l’agent la raison d’un échec.

Événements et contrôles

Des événements tels que UserTranscriptReceived, AgentResponded, ModeChanged et Interrupted sont déclenchés sur le thread principal de Unity, afin que vous puissiez mettre à jour l’interface utilisateur directement depuis ceux-ci. Les méthodes couvrent la saisie de texte avec SendUserMessage, la mise en sourdine avec SetMicMuted, SetVolume, les données de fréquence pour les visualiseurs, ainsi que le changement de périphériques d’entrée ou de sortie en cours de session. La documentation du SDK Unity les répertorie toutes.

Prise en charge des plateformes

Le SDK sélectionne le transport pour chaque cible.

• iOS et Android : demandez l’autorisation d’utiliser le microphone avant de démarrer une session.
• WebGL : activez Use WebAssembly.Table dans Publishing Settings. Si cette option est désactivée, le SDK fait échouer le build en indiquant comment procéder. Le Play Mode ne fonctionne pas lorsque WebGL est la cible de build active, testez donc sur une cible desktop.
• Audio WebGL : la voix est diffusée via l’API Web Audio. Certains paramètres de AudioSource, comme le routage du mixeur et le doppler, ne sont donc pas repris. Les sessions WebRTC ignorent OutputAudioSource.

Les notes de compatibilité contiennent la liste complète.

Démarrer

1. Concevez un agent dans le Dashboard ElevenLabs. Pour un premier test, désactivez Authentication dans ses paramètres Security, afin que le jeu puisse se connecter avec le seul ID de l’agent.
2. Dans Unity, ouvrez Window > Package Manager > + > Install package from git URL, puis épinglez la version : https://github.com/elevenlabs/unity.git#v0.1.0
3. Importez l’exemple GettingStarted, collez l’ID de votre agent et appuyez sur Play.

Avertissement : Avant de publier votre jeu, réactivez Authentication. Votre propre serveur demande alors une URL signée de courte durée, que le jeu transmet comme SignedUrl au lieu de AgentId. N’intégrez jamais votre clé API ElevenLabs dans un build de jeu.

Le guide de démarrage prend environ 10 minutes et se termine avec un cube qui vous salue lorsque vous vous approchez. Pour tout le reste, consultez la documentation du SDK Unity et envoyez les bugs ainsi que les demandes de fonctionnalités dans les issues GitHub.