Drive Gameplay with Structured Output

Structured output gives a deeper dimension to your gameplay with NPCs. Structured output is a mechanism through which the LLM backing your NPC returns user-defined, LLM instantiated structs to drive gameplay logic. 

Overview

This section customizes your persona_npc_behavior with a single structured output for your persona. The interactions_response struct:

• Records the number of times this NPC has interacted with the player.

• The current feeling the persona has about this interaction with the player.

• An array recording the history of the persona's feelings about all interactions with the player.

Structured output requires that you:

• Create a struct defining the structured output.

• Provide instructions for how the persona should fill the structured output struct.

• Define and subscribe to an event signaled upon receipt of structured output.

You can configure multiple structured outputs on a single persona at the same time and specify different subscriptions for each type of structured output for your persona.

Supported Types

Structured output supports the following Verse types as fields inside structs:

• int

• float

• bool

• enum

• message

Displaying Messages

Message types are redacted when printed to the log or in-game, but you can display message types using devices that are designed to display them, such as:

• billboard_device

• hud_message_device

• popup_dialog_device

Prerequisites

• Add an NPC to a Conversation

Add Structured Output to NPC Behavior Script

Below is a Verse script containing an expanded persona_npc_behavior in the section persona_npc_behavior.verse. This expands upon the code in the Add an NPC to a Conversation documentation including structured output. 

To amend the code in your existing persona_npc_behavior, follow these steps:

1. Ensure that you have your Verse Project open in VS Code:

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

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

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

3. 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 Changes. This section picks up immediately after where the script explanation in Add Persona to NPC Character left off.

persona_npc_behavior.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 }

Explanation of Script Changes

To add structured output to your NPC, follow these steps:

1. Define an interactions_response struct that counts the number of times the NPC and player have interacted. Also define a string instructing the LLM how to fill out the interactions_response struct. The InteractionsResponseSubscription cancelable subscription is set later once the persona_component is subscribed to structured output responses. You can use this to cancel response subscriptions and no longer handle receiving structured output from the LLM.

   Verse

   # Imports
   # ...
   
   # Log
   # ...
   
   # Structured Output
   
   interactions_response := struct:
       Number:int
   
   Expand code Copy full snippet(27 lines long)

2. Define an event to determine what happens when the LLM responds with a structured response. Name the event OnInteractionsResponse for when an interactions_response is received. These functions simply log the information they receive, but you change these to drive further gameplay events.

   Verse

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

3. These structured output types and event callbacks must be registered with the persona_component. Create a function AddStructuredOutput that adds the structured output facts to the persona and registers the appropriate events. This function retrieves the existing persona_component, modifies it with additional information about structured output, and subscribes to the structured output events.

   Verse

   persona_npc_behavior := class(npc_behavior):
   
   	# Fields
   	# ...
   
   	# Functions 
   	# ...
   
   	# Add more information to the existing persona_component on filling structured ouptut
          AddStructuredOutput(AdditionalFacts:string):void =
   
   Expand code Copy full snippet(26 lines long)

4. Add the structured output to the NPC Spawner OnBegin function.

   Verse

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

5. Lastly, it is good practice to cancel these subscriptions in the OnEnd event.

   Verse

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

Test Structured Output

The NPC is now configured with structured output. Every time the persona speaks, the interactions_response is signaled.

To test this behavior, navigate to the Menu Bar and select Launch Session. Look for the messages in the Output Log that signal structured output is received from the persona and the information it passes is being output to the log.

Here you can see the NPC persona response as it appears in the game:

And the corresponding structured output being logged in the Output Log under persona_log:

The messages in the log are redacted, but are displayable in-game using a device that supports message types as input as outlined in the Displaying Messages section of this page.