Add an NPC to a Conversation

Prerequisites

• Create a persona

Now that you have created your first persona and refined its personality and knowledge through interacting with it in the Prompt Editor, you can add your NPC to a conversation. To converse with an NPC in game, you must:

• Define a new npc_behavior in Verse.

• Add your npc_behavior to your NPC Character Definition.

• Add your NPC Character Definition to an NPC Spawner.

• Ensure you have Voice Chat Enabled as Voice Chat is required to converse with persona NPCs.

Create an Empty NPC Behavior

To set up a custom NPC Behavior in Verse, follow these steps:

1. In the Menu Bar, select Verse > Verse Explorer.

2. In the Verse Explorer, right-click on your project name and choose Add new Verse file to project to open the Create Verse Script window.

3. In the Create Verse Script window, click NPC Behavior Basic to select it as your template.

4. Name the NPC Behavior persona_npc_behavior under Configure.

5. Select Create to create your Verse file.

The persona_npc_behavior is where you can define and add a persona_component to your NPC through Verse. All NPCs spawned by NPC Spawners are agents and have an associated entity. This associated entity is how you add Scene Graph Components, such as the persona_component to an NPC agent.

NPC Behaviors are defined in Verse inheriting from the base npc_behavior class. For more information about NPC Behaviors, see the Understanding NPC Behaviors page.

Edit your Persona NPC Behavior

Verse is required to add your NPC persona as a conversation target for the player. Without adding your NPC as a conversation target for your player, you cannot converse with your NPC persona.

Below is a Verse script defining the persona_npc_behavior in the section persona_npc_behavior.verse. To add this Verse code to your empty persona_npc_behavior, follow these steps:

• In the Menu Bar, select Verse > Open Project in VS Code…

• Once VS Code opens, find your persona_npc_behavior.verse file in the VS Code Explorer.

• Copy and paste the content of persona_npc_behavior.verse below into your Verse file in your project.

• Compile your Verse code either in the UEFN Toolbar or within VS Code.

For a step-by-step walkthrough of the Verse script, follow the steps under Explanation of Script.

persona_npc_behavior.verse

using { /Fortnite.com/AI }
using { /Fortnite.com/Playspaces }

using { /UnrealEngine.com/Conversations }
using { /UnrealEngine.com/Temporary/Diagnostics }

using { /Verse.org/Chat }
using { /Verse.org/SceneGraph }
using { /Verse.org/Simulation }

Explanation of Script

1. Import the necessary modules.

   Verse

   using { /Fortnite.com/AI }
   using { /Fortnite.com/Devices }
   using { /Fortnite.com/Playspaces }
   
   using { /UnrealEngine.com/Conversations }
   using { /UnrealEngine.com/Temporary/Diagnostics }
   
   using { /Verse.org/Chat }
   using { /Verse.org/SceneGraph }
   using { /Verse.org/Simulation }

   Copy full snippet(10 lines long)

2. Create a log channel. This is a good practice for logging. See Debugging and Troubleshooting in Verse for more information on logging.

   Verse

   persona_log := class(log_channel){}

   Copy full snippet(1 line long)

3. Add a logger to log any relevant messages to report errors, warnings, and important debug messages.

   Verse

   persona_npc_behavior := class(npc_behavior):
   
   	Logger:log = log{Channel := persona_log}
   

   Copy full snippet(3 lines long)

4. To ensure that your player can converse with your NPC as soon as play begins, you need to add the NPC as a conversation for your player. Define a new AddPlayerAsConversationTarget function. To add an NPC as a conversation target for a player, the NPC persona must belong to a team that the player belongs to and be added to a voice chat channel that the player belongs to. The simulation entity contains information about available voice channels.

   Verse

   persona_npc_behavior := class(npc_behavior):
   
   	# Fields
   	# ...
   
   	# Functions
   
          # Add the Player as a conversation target for this NPC 
          AddPlayerAsConversationTarget(Player:player):void=
              if:
   
   Expand code Copy full snippet(30 lines long)

5. Once play ends, NPCs should be cleared out as potential conversational targets for players. Define a new RemovePlayerAsConversationTarget function.

   Verse

   persona_npc_behavior := class(npc_behavior):
   
   	# Fields
   	# ...
   
   	# Functions
   	# ...
   
      	# Remove Player as a conversation target
       	RemovePlayerAsConversationTarget(Player:player):void=
   
   Expand code Copy full snippet(12 lines long)

6. Override OnBegin to automatically add this NPC as a conversation target for players.

   Verse

   persona_npc_behavior := class(npc_behavior):
   
   	# Fields
   	# ...
   
   	# Functions 
   	# ...
   
   	# NPC Behavior Events 
   	
   
   Expand code Copy full snippet(14 lines long)

7. Lastly, override OnEnd to remove this NPC as a conversation target for players.

   Verse

   persona_npc_behavior := class(npc_behavior):
   
   	# Fields
   	# ...
   
   	# Functions 
   	# ...
   
   	# NPC Behavior Events
   	# ...
   
   Expand code Copy full snippet(15 lines long)

Add NPC Behavior to NPC Character Definition

To add your persona_npc_behavior to your NPC Character Definition, follow these steps:

1. Navigate to your PersonaNPCDefinition in the Content Drawer.

   

2. Select the PersonaNPCDefinition to open for editing.

3. Under NPC Character Behavior, select Verse Behavior > persona_npc_behavior.

   

4. Ensure you save your changes to your NPC Character Definition before closing the tab.

Once your NPC Character Definition is added to an NPC Spawner, your NPC persona is automatically added as a conversation target for your player.

Add NPC Spawner with NPC Character Definition

To spawn an NPC with your customized persona, you must add an NPC Spawner to your level and add your PersonaNPCDefinition. To add an NPC Spawner Device, drag your PersonaNPCDefinition from the Content Drawer into the Viewport.

Converse with your NPC

To converse with your NPC, launch a session and start the game. Press the key or button on your input device indicated on-screen and converse with your NPC!

Team Engagement and Agent Group

You can also use Verse to create experiences where a team of players interact with LLM agents. Verse handles the interactions between multiple players and the LLM agents using CreateAudioTeamAndAddPlayers(), AddMember(), and AddChatChannel(). Below is a complete script that shows how these functions are used to determine when players and LLMs can interact using structs as the guiding principle for interactions. 

team_conversation.verse

using { /Fortnite.com/AI }
using { /Verse.org/Simulation }
using { /Verse.org/SceneGraph }
using { /UnrealEngine.com/Conversations }
using { /Verse.org/AgentGroup }
using { /Verse.org/Chat }
using { /Fortnite.com/Playspaces }


team_member_info := class(has_voice_member_info){}

Explanation of Team Conversation Script

1. The necessary modules  are imported for the LLM behavior and group chat capabilities.

   Verse

   using { /Fortnite.com/AI }
   using { /Verse.org/Simulation }
   using { /Verse.org/SceneGraph }
   using { /UnrealEngine.com/Conversations }
   using { /Verse.org/AgentGroup }
   using { /Verse.org/Chat }
   using { /Fortnite.com/Playspaces }
   

   Copy full snippet(7 lines long)

2. The following classes are used to create a chat channel and handle player prompts.

   Verse

   team_member_info := class(has_voice_member_info){}
   
   team_agent_group := class(agent_group(team_member_info)) {}
   
   new_npc_behavior_basic := class(npc_behavior):
   

   Copy full snippet(5 lines long)

3. TeamName is the name provided for the Team Voice Channel. The channel uses two variables to determine who is in the chat group and the contents of the chat.

   The OptionAgentGroup variable stores the agent group used to create the voice channel. This group can be used to create additional voice channels or get current players into a conversation.

   The second variable named OptionVoiceChannel stores the VoiceChannel that contains the players and the LLMs. This variable holds the entirety of the conversation.

   Verse

       #Team name for the Team Voice Channel we are creating.
   
       TeamName<localizes>:message = "Persona Chat"
   
       #Variable that stores the agent group we are using to create the voice channel. We can use this group to create new channels or get current players in a conversation.
   
       var OptionAgentGroup:?agent_group(team_member_info) = false
   
       #Variable that stores the Voice Channel that our players and NPC will be inside of. This is what actually holds the conversation.
   
   
   Expand code Copy full snippet(11 lines long)

4. A series of helper functions are created to set players as the conversation targets, remove an NPC from the conversation, and remove the player from the conversation.

   Verse

       #Helper function to set players as our conversation targets.
   
       AddPlayerAsConversationTarget(Player:player):void=
   
           if:
               NPCEntity := GetEntity[]
               NPCAgent := GetAgent[]
               TeamVoiceChannel := OptionVoiceChannel?
   
           then:
   
   Expand code Copy full snippet(42 lines long)

5. Under OnBegin, a function named CreateAudioTeamAddPlayer() is used to create the channel and add all the players when the component is created.

   Verse

       OnBegin<override>()<suspends>:void=
   
           #Create the Audio channel and add all the players when the Component is created.
   
           CreateAudioTeamAndAddPlayers()
   
   

   Copy full snippet(6 lines long)

   You can expand the OnBegin functionality by creating a persona manager that uses one specific NPC to greet players as they begin the game. The manager can be added to a special zone in the game and target a specific NPC with a greeting prompt when a player is detected.

   For example:

   Verse

       # This function runs when the NPC is spawned in the world and ready to follow a behavior.
   
       OnBegin<override>()<suspends>:void=
           Volume.AgentEntersEvent.Subscribe(AddPlayerToConvo)
           Volume.AgentExitsEvent.Subscribe(RemovePlayerFromConvo)
   
           FindManager()
   
           if(PersonaComponent := 
   
   

   Expand code Copy full snippet(17 lines long)

6. The OnEnd<override>() : void= function is used to end a conversation. The function uses a print log to print a message that reads “Goodbye, NPC!” when the conversation is over.

   Verse

       OnEnd<override>():void=
   
           Print("Goodbye, NPC!")
   
   

   Copy full snippet(4 lines long)

7. A function called CreateAudioTeamAndAddPlayers() creates the Agent group, audio channel, and adds all players and LLMs to the channel and sets them all as targets for the conversation.

   You could alter this function to target one player by using the function CreateAudioTeamAndAddPlayer().

   An if statement determines which LLM NPC and player enters the channel, then searches for the appropriate persona_component for the LLM character.

   A then statement creates a new Agent Group with the team_member_info_data and adds the players and NPCs to the conversation by creating a channel for the Agent Group.

   Verse

       #Function to create an Agent group, an Audio Channel, add all players and NPC to the agent group and channel, and set them all as Targets for the conversation.
   
       #Alternatively, if you would like for this example to use 1 player, refer to the function CreateAudioTeamAndAddPlayer()
   
       CreateAudioTeamAndAddPlayers():void =
   
           if:
               NPCEntity := GetEntity[]
               NPCAgent := GetAgent[]
               SimEntity := NPCEntity.GetSimulationEntity[]
   
   Expand code Copy full snippet(31 lines long)

8. A for statement searches for the players and the LLM characters in the playspace and adds them to their respective groups (Player or NPCAgent).

   A new voice channel is then added to the Audio Chat system and saves the AgentGroup and VoiceChannel for use in other helper functions and any changes you may want to make.

   Next all players that were added to the chat are set as targets for the NPC conversations.

   Verse

               #Go through all of the players in the playspace and add them to the group.
   
               for(Player:Players):
   
                   TeamGroup.AddMember(Player, team_member_info{})
   
               #Also add the NPC to this new agent group.
   
               TeamGroup.AddMember(NPCAgent, team_member_info{})
   
   
   Expand code Copy full snippet(24 lines long)

9. Using the same function as above, you can create one-on-one conversations for a single player instead of multiple players using CreateAudioTeamAndAddPlayer().

   Verse

       #Same functionality as function above but passes a single player instead of multiple. Use this for single player experiences or 1on1 conversations.
   
       CreateAudioTeamAndAddPlayer(Player:player):void =
   
           if:
               NPCEntity := GetEntity[]
               NPCAgent := GetAgent[]
               SimEntity := NPCEntity.GetSimulationEntity[]
               Players := 
   
   
   Expand code Copy full snippet(30 lines long)

10. Compile your code to save your Verse file.

Next Up

• 

  Drive Gameplay with Structured Output

  Explore how to use Verse to refine NPC conversations and behaviors.