Character

​

Getting Started

​

Player setup

1. Add the Inworld Player component to an Actor or other blueprint in your level. In this template we attached the Inworld Player component to a custom Player Controller.
2. In the Details panel, setup the Player Profile defaults:
   • Name: The name of the player (that the Character will know the player as). By default, we use the name “Alex”.
   • Gender: The gender of the player.
   • Age: The age of the player (this could be interpreted as a number or stage of life).
   • Role: This is the player’s role (this can be interpreted in a number of ways, such as the player’s job or role in society. Used to give more context as to who the player is to characters).
3. Setup the Audio Capture config:
   • Capture Frequency - The frequency at which audio is captured (measured in cycles per second). Controls how frequently OnAudioCapture is fired.
   • Enable AEC - Enable Acoustic Echo Cancellation (AEC). This helps reduce game audio from being interpreted as player speech when captured by the microphone.
   • AECId - Ids the AEC primtive creation configuration (there is currently no creation config settings, just leave as Default)
   • AECConfig:
     • Echo Supression Level - AEC processing intensity (0.0-1.0, higher values provide stronger echo cancellation)
     • Noise Suppression Level - Noise suppression intensity (0.0-1.0, higher values provide stronger noise reduction)
     • Enabled Adaptive Filter - Enable adaptive filtering for better echo cancellation
   • Enable VAD - Enable Voice Audio Detection (VAD). This is useful for determining when the player is speaking for sending audio data.
   • VADId - Ids the VAD primtive creation configuration (there is currently no creation config settings, just leave as Default)
   • VADConfig:
     • Speech Threshold - Sensitivity threshold for detecting speech. This is a float value where higher thresholds make the detection more selective (fewer false positives), and lower thresholds make it more sensitive (detecting quieter speech). Valid range: 0.0 - 1.0 (default = 0.4)
   • VADBuffer Time - The amount of silence required before it is determined that the player has stopped speaking.
   • StreamingSTTComponentId - Identifier for the Streaming STT Creation Config settings for the Streaming STT component used for converting speech-to-text.
   • Start Mic Enabled - Whether to start the game with the microphone enabled.

​

Character setup

1. Start by creating a blueprint Actor that represents your character.
2. Add the necessary Inworld components to your actor:
   • InworldCharacter - for interfacing with the conversational AI system
   • InworldVoiceAudio - for playing character speech audio
   • InworldLipsync (optional) - for lip-syncing (experimental)
   • BP_ChatBubbleComponent (optional) - for displaying chat bubbles in world space
3. Setup the InworldCharacter component’s Id and Graph properties:
   • Id: The id of the conversation target. This is used to identify the conversation target in the Inworld Character Subsystem.
   • Emotion Graph Asset: The graph used to generate the character’s current emotional state.
   • Relation Graph Asset: The graph used to generate the character’s relationship to the player.
   • Dialogue Generation Graph Asset: The graph used to generate the character’s dialogue responses.
4. Setup the InworldCharacter component’s Inworld runtime data properties:
   Character Profile

   The Character Profile shapes who the character is and how the character responds.

   • Name: The name of the player (that the Character will know the player as). By default, we use the name “Alex”.
   • Role: The job this character does in the scene. This can be things like “Market Vendor” “Fan of the Player”, and “Witness”. Specific roles and titles can help the AI produce better results. For example, “World War 2 Private” would give the character more context than just “soldier”.
   • Pronouns: The pronouns the character uses to define themselves. For example: She/Her/Hers
   • Stage of Life: This is used for the character’s age or approximate age. For example: The user could enter 15 or teenager.
   • Hobbies and Interests: The pastimes and activities that the character enjoys.
   • Description: This provides details about a character’s current circumstances, backstory, general disposition, and how they present themselves to others. It is recommended you use evocative and descriptive language when writing a character’s description, instead of straightforwardly listing information. This helps the AI develop a fluid narrative around the character and their circumstances, encouraging the AI to visualize the character, interpret any descriptive elements, and craft its own dynamic portrayal. A dramatic, evocative writing approach results in more fully-realized and expressive responses from the AI when portraying the character. Things to include:
     • Backstory
     • Relationships with other characters
     • Specialty or unique skillset
     • Personal opinions
     • Current appearance
     • Things they have experienced
     • Favorite sayings
     • Things they hate
     • Things they love
   • Motivation: What goals and ambitions drive the character.
   • Flaws: A list of character flaws the bot has. Flaws can be as minor as the character being unable to spell “ballerina” to massive story changing traits. Like Description, it is recommend that you write character flaws in an evocative style. Some examples:
     • Allergic to peanuts
     • Secretly jealous of their sibling
     • Can’t talk about their favorite game without going on rants
   • Custom Dialog Style: Enabling Custom Dialogue Style opens an Adjectives and Colloquialism section. While you can add these in the default Dialog Style, this allows more specificity for character customization.
   • Adjectives: This allows you to describe your character’s overall dialog style. Some examples:
     • Formal well-spoken, straightforward, matter-of-fact. (computer, scientist, lawyer)
     • Blunt short, direct, candid, outspoken. (sports coach, celebrity chef)
     • Entertaining animated, comical, amusing, witty. (stand-up comedian, cartoon character, jester)
   • Colloquialism: List any colloquialisms that the character uses. Some examples:
     • Cool (for good or awesome)
     • Hit the nail on the head
     • Buddy
     • gonna
     • y’all
     • ain’t
   • Dialog Style: A condensed version of the Custom Dialog Style. Instead of the style being broken into multiple categories, it is condensed into one description box.
   • Example Dialog: To give the LLM a better chance at meeting your desired character response style, this can be used to give the LLM response examples in the voice of the character.
   • Personality Traits: Used if you want the character to have a specific personality type. Some examples:
     • Bubbly thoughtful, energetic. (influencer, entertainer, partygoer)
     • Inquisitive curious, exploratory, interested, prying. (detective, psychologist)
     • Commanding intense, determined, authoritative, dictatorial.(drill sergeant, personal trainer, ship captain)
     • Empathetic gentle, compassionate, understanding. (teacher, healer, animal rescuer)

   Voice

   The Voice determines what voice is used for the character audio.

   • Speaker Id: The ID of the voice you would like your character to use. For Inworld voices, you can check TTS Playground or use the List voices API for the complete list of options.
   • Language: Optional. The language the character will speak.

   Event History

   The Event History defines how the conversation history will be handled.

   • Speech Event Formatter: The string format to use for event records in the concatenated string representation of all stored events.
   • Delimiter: The delimiter to use for separating history records in the concatenated string representation of all stored events.
   • Capacity: The maximum amount of history entries that can be stored (oldest entries are replaced when capacity is reached).
   • Initial History Table: A data table containing rows of InworldEventHistoryEntry’s to populate a character with initial conversation history.

   Emotion State

   

   • Emotion Label: The character’s initial emotional state (default is Neutral)

   Relation State

   A character’s relation state defines its relationship to the player (e.g., Friend vs Archenemy).A character’s relation state is defined by a set of attributes:

   • Trust
   • Respect
   • Familiar
   • Flirtatious
   • Attraction

   Attributes are assigned integer values which can be positive or negative. A relationship label is then assigned based on attribute values. For example:

   • Friend is defined by: trust >= 10 && respect >= 5 && familiar >= 10 && flirtatious <= 5 && attraction >= 5
   • Archenemy is defined by: trust <= 0 && respect <= -20 && flirtatious <= 5 && attraction <= -20

   Knowledge

   Knowledge is used to provide additional information that a character can draw upon during a conversation. Unlike the Character Profile fields, the information in Knowledge is only made available to the character when it would be relevant to the conversation, such as when answering a specific question.Knowledge consists of maps of FInworldTextEmbedding Arrays (for runtime generated knowledge data) and Inworld Text Embedding Assets (for design time knowledge data).Initial Knowledge Map:

   • String (key) - the string identifier of the knowledge set.
   • Text Embedding Asset (value) - an asset of embedded text records which the Knowledge node will query to return the knowledge records most similar to the provided input.

   For information on how to create a Text Embedding Asset, see here.

   Knowledge Filters

   Knowledge filters can be used to restrict the types of knowledge the character has access to. This system can reduce unwanted hallucinations and cognition that may deviate from a character’s established parameters.

   • Knowledge Filter:
     • None - Character should hold detailed knowledge about most topics
     • Mild - Character should only hold explicitly specified knowledge and knowledge related to its expertise areas and time period
     • Strict - Character should only hold explicitly specified knowledge

   Goals

   A character’s Goals determine what a character wants to accomplish, enabling you to set specific triggers that prompt them to respond in a specific way during certain scenarios or interactions.A character’s Goals consist of two key elements:

   • Activation - How the goal is activated. Can either by directly triggered or through an intent being detected.
   • Action - The actions that occur once the goal is activated. Either an Instruction (e.g., Reveal that the password is 123) or Verbatim (e.g., “The password is 123!”).

   The Goals runtime data requires a Data Table of Row Type FInworldGoal:Inworld Goal:

   • Response Type:
     • Instruction - when the goal is activated the character will receive an instruction on how it should respond
     • Verbatim - when the goal is activated the character will be given a response to say verbatim
   • Instruction - the instruction for the character on how to respond (when the goal is activated)
   • Verbatim - the verbatim response for the character to respond with (when the goal is activated)
   • Repeatable - if this goal can be activated more than once
   • Intents - list of the names of intents which can activate this goal. See Intents below for more details on setting up intents.

   Intents

   Intents are sets of phrases that a character can activate based on player input. If player input is similar to one of the phrases in an intent, the intent will be matched and returned by the Intent node.Intents consists of maps of FInworldTextEmbedding Arrays (for runtime generated intent data) and Inworld Text Embedding Assets (for design time intent data).Initial Intents Map:

   • String (key) - the string identifier of the intent set.
   • Text Embedding Asset (value) - an asset of embedded text records which the Intent node will query to try to match intents to the provided input.

   For information on how to create an Embedded Intent Phrase Asset, see here.
   This information can be set directly on the blueprint instance in the level itself, or it can be referenced from an Inworld Character Config Data Table.
   Manual Configuration on Blueprint

   

   Data Table Configuration

   1. Enable the Use Data Table checkbox.
   2. Select the appropriate Inworld Character Config Data Table asset (or create a new one).
   3. Select the Character ID of the configured character from within the Data Table that you want to use.

   Inworld Character Config Data Table:
5. [Optional] Setup a Conversation Group
   If you would like to support multi-character or character-to-character conversations you will need to setup a Conversation Group. As an example we have created BP_ConversationGroup.
   MultiCharacter level from the Innequin template.
   The blueprint utilizes the Inworld Conversation Group component to create and manage the conversation. On BeginPlay characters are added to the conversation as they are ready: Within the level, in the details panel you can set the Inworld Characters you want added to the group. There are also settings for a basic automated response system:
6. Set the Player’s Conversation Target The conversation target can either be a single character or a conversation group. You can utilize the Inworld Character Subsystem to find registered conversation targets, with useful functions such as GetClosestConversationTarget to find the target nearest the player pawn:
7. Now you should be able to run the level and talk to your characters (just don’t forget to enable the microphone).

​

Technical Overview

​

Graphs

​

IG_SimpleDialogue

• Text - player input text
• Audio - player input audio

• Player Profile - player profile runtime data
• Character Profile - character profile runtime data
• Voice - voice runtime data
• Event History - event history runtime data

• Player Out (Text) - player input text
• Response Out (Text) - generated response text
• TTS (TTSOutput) - generated response text and audio output stream

1. The first section of the graph handles input. Input Section
   • Input enters via a Routing node.
   • A Routing node transfers data without mutating it, which is ideal here because we don’t want to change input data.
   • Based on the detected input type, route to a Speech-To-Text (STT) node to convert audio to text.
   • Once we have text, send it to both Player Out and the Simple Dialogue Prompt input.
   • Use Player Out if you want to capture what the player said.
2. The second section of the graph handles the LLM request. LLM Section
   • The custom Simple Dialogue Prompt node takes four inputs:
   • Input (text) (coming from input section)
   • Player Profile (runtime data for the player)
   • Character Profile (runtime data for the AI character)
   • Event History (history of interactions between player and character)
   The Process Default of Simple Dialogue Prompt Inside the Simple Dialogue Prompt, we extract strings from each input struct and feed them into a FormatText node to create the prompt.
   • The prompt is sent to the Dialog Generation LLM node.
   • The LLM is configured to stream responses (tokens are emitted as soon as they’re generated).
   • Use Response Out if you want to capture what the LLM said.
3. The third section handles text-to-speech output. TTS Section
   • The streamed output from Dialog Generation LLM is fed into Text Chunking.
   • Text Chunking aggregates tokens into words/sentences.
   • Once chunked, pass the text and Get Voice to TTS Request to create a text-to-speech request.
   • Get Voice is runtime data that specifies which voice ID to use.
   • Feed TTS Request into TTS to output audio as it arrives.
   • The TTS Audio is automatically buffered into the InworldVoiceAudio component. Which plays back the streamed audio.

​

IG_Dialogue

• Text - player input text
• Trigger - a goal to activate
• Action - action to perform

• Player Profile - player profile runtime data
• Character Profile - character profile runtime data
• Voice - voice runtime data
• Event History - event history runtime data
• Conversation State - conversation state runtime data
• Knowledge - knowledge runtime data
• Knowledge Filter - knowledge filters runtime data
• Relation - relation runtime data
• Emotion - emotion runtime data
• Goals - goals runtime data
• Intents - intents runtime data

• Player Out (SafetyResult) - player input text
• Response Out (SafetyResult) - generated response text
• Goal Out (Action) - action to perform
• TTS (TTSOutput) - generated response text and audio output stream

• Safety - for handling unsafe player input and generated dialogue.
• Goals - for activating predefined dialogue responses or instructions.
• Knowledge - for fetching relevant information known by the character and filtering the response.
• LLM Generation - for generating dialogue based on conversation context and character state.
• Text-to-Speech (TTS) - for converting generated dialogue to speech output.

​

IG_Safety

• Text - text to classify

• Safety Aggregator (SafetyResult) - the safety result (IsSafe: boolean, Text: string)

​

IG_KnowledgeFilter

• Query (Text) - the player’s query text
• Knowledge Records - a list of knowledge records
• Knowledge Filter - knowledge filter runtime data
• Character Profile - character profile runtime data
• Event History - event history runtime data

• Character Profile - character profile runtime data
• Knowledge Filter - knowledge filter runtime data

• Knowledge Filter Processing (Text) - the textual knowledge filter to add to the LLM prompt (e.g. “Make sure to respond as if {agent’s name} has poor knowledge on the topic, showing lack of confidence.”)

​

IG_SpeakerSelection

• Text - the player’s query text

• ConversationState - conversation state runtime data
• EventHistory - event history runtime data

• LLMResponse To Text (Text) - the index of the next speaker (as a string)

​

IG_Relation

• Character Profile - character profile runtime data
• Player Profile - player profile runtime data
• EventHistory - event history runtime data

• LLMResponse To Text (Text) - the relationship update (as a string) The output will be of the form:
  Copy

  - trust: [-2, -1, 0, +1, +2]
  - respect:  [-2, -1, 0, +1, +2]
  - familiar:  [-2, -1, 0, +1, +2]
  - flirtatious:  [-2, -1, 0, +1, +2]
  - attraction:  [-2, -1, 0, +1, +2]
  

​

IG_Emotion

• Character Profile - character profile runtime data
• EventHistory - event history runtime data

• LLMResponse To Text (Text) - the emotion label (as a string) ['NEUTRAL', 'CONTEMPT', 'BELLIGERENCE', 'DOMINEERING', 'CRITICISM', 'ANGER', 'TENSION', 'TENSE_HUMOR', 'DEFENSIVENESS', 'WHINING', 'SADNESS', 'STONEWALLING', 'INTEREST', 'VALIDATION', 'HUMOR', 'AFFECTION', 'SURPRISE', 'JOY', 'DISGUST']

​

Runtime Data

​

Player Profile

• Name (FString) - Player’s name for personalized address
• Gender (FString) - Player’s gender identity for appropriate character responses
• Age (FString) - Player’s age or age category for context-appropriate dialogue
• Role (FString) - Player’s role or position in the game world

// Direct usage - wrap as FInworldData_Struct for graph consumption
FInworldPlayerProfile playerProfile;
// ... populate profile data ...
FInworldDataHandle profileData = FInworldData_Struct(playerProfile);

// From UInworldBaseCharacterComponent::SendPlayerMessage_Implementation
FString MessageId = Execute_SendDataMessage(this, Message, 
    {{PlayerProfileRuntimeDataKey, FInworldData_Struct(PlayerProfile)}});

• Personalizing character responses based on player characteristics
• Maintaining player context across sessions
• Adapting conversation style to player demographics
• Lightweight player data that doesn’t require complex manipulation functions

​

Character Profile

• CharacterProfile - FInworldCharacterProfile structure defining character traits and behavior

• Get() - Retrieves the current character profile as const reference
• Set(CharacterProfile) - Updates the character profile with new data
• GetData() - Returns FInworldData_Struct(CharacterProfile) for graph consumption
• Initialize_Implementation() - Handles setup and validation logic

• Provides Blueprint-friendly functions (Set, Get)
• Supports initialization logic and validation
• Enables ExposeOnSpawn = "true" for Blueprint configuration
• Allows for future extension with complex manipulation methods

• Managing character personality data with functions that structs cannot provide
• Blueprint-friendly character configuration
• Complex initialization and validation logic
• Providing structured access to character profile data for LLM nodes

​

Voice

• Voice - FInworldVoice structure containing voice configuration settings

• Get() - Retrieves the current voice configuration as const reference
• Set(Voice) - Sets the voice configuration for this runtime data
• GetData() - Returns FInworldData_Struct(Voice) for graph consumption

• Blueprint-friendly voice configuration management
• Structured access to voice settings for TTS nodes
• Providing voice context during graph processing
• Managing character-specific voice characteristics with UObject functions

​

Knowledge

• InitialKnowledge - Map of initial knowledge assets automatically loaded during initialization

• Set(KnowledgeAssets) - Sets the initial knowledge assets for the runtime data
• AddKnowledgeTextEmbeddingAsset(Id, Knowledge, Replace) - Adds a new text embedding asset to the knowledge base
• AddKnowledgeTextEmbeddings(Id, Knowledge, Replace) - Adds text embeddings directly to the knowledge base
• RemoveKnowledge(Id) - Removes a specific knowledge set by its unique ID
• EnableKnowledge(Id) - Enables a specific knowledge set for retrieval operations
• DisableKnowledge(Id) - Disables a specific knowledge set from retrieval operations
• GetKnowledgeMapKeys() - Retrieves all knowledge set IDs currently stored
• GetData() - Returns knowledge data wrapped as FInworldDataHandle for graph consumption
• Initialize_Implementation() - Processes initial knowledge assets and loads text embeddings

• Defining what the character knows about specific topics using text embeddings
• Dynamically updating character knowledge during gameplay
• Controlling access to sensitive or context-specific information
• Managing domain-specific expertise through semantic search capabilities

​

Relation State

• Relation - The current relationship state including all dimensional metrics with Blueprint exposure

• GetRelation() - Retrieves the complete relationship state with all metrics
• GetRelationshipLabel() - Retrieves the primary relationship label derived from the metrics
• GetRelationshipLabelString() - Retrieves the relationship label as a human-readable string
• UpdateRelation(Relation) - Updates the relationship state with new relation data
• UpdateRelation(TextResponse) - Updates relationship state by parsing an AI-generated text response
• GetData() - Returns FInworldData_Struct(Relation) for graph consumption

• Tracking how relationships evolve over time through conversation dynamics
• Modifying character behavior based on current relationship status and history
• Creating dynamic social interactions that respond to relationship changes
• Implementing relationship-dependent dialogue options and character responses

​

Emotion State

• Emotion - The current emotional state of the character (defaults to NEUTRAL with Blueprint exposure)

• GetEmotion() - Retrieves the current emotion state structure
• GetEmotionLabelString() - Retrieves the emotion label as a human-readable string
• GetEmotionLabel() - Retrieves the current emotion label enum value
• SetEmotionLabel(EmotionLabel) - Sets the character’s emotion to a specific label
• UpdateEmotion(TextResponse) - Updates emotion state by parsing an AI-generated text response
• GetData() - Returns FInworldData_Struct(Emotion) for graph consumption

• Creating emotionally responsive characters with dynamic mood changes
• Influencing dialogue tone and behavior based on character emotional state
• Implementing dynamic emotional reactions to conversation events
• Adding personality depth through emotional expression and consistency

​

Event History

• SpeechEventFormatter - Template for formatting speech events (default: ”: ”)
• Delimiter - String used to separate events in the formatted history string (default: newline)
• Capacity - Maximum number of events to store (INDEX_NONE = unlimited)
• InitialHistoryTable - Optional data table with pre-populated history entries

• Set(EventHistoryTable) - Sets the initial event history data table
• AddGenericEvent(Event) - Adds a generic text event to the history
• AddSpeechEvent(Speech) - Records a speech event with agent name and utterance
• Clear() - Removes all stored events and resets the history
• GetHistoryString() - Returns formatted string containing all recorded events
• GetSpeechEvents() - Returns array of all recorded speech events
• GetHistoryEventData() - Returns structured event history data for processing
• GetData() - Returns FInworldData_EventHistory for graph consumption
• Initialize_Implementation() - Sets up event history system and processes initial data
• DebugDumpEventHistory() - Outputs debug information about current event history state

• Providing conversation context to AI systems during graph execution
• Enabling characters to reference past interactions and maintain continuity
• Creating memory-based character development and relationship building
• Implementing conversation flow tracking and history-dependent behavior

​

Intent

• InitialIntents - Map of initial intent assets loaded during initialization

• Set(IntentAssets) - Sets the initial intent assets for the runtime data
• AddIntentTextEmbeddingAsset(Id, Intent, Replace) - Adds a new intent using text embedding asset
• AddIntentTextEmbeddings(Id, Intent, Replace) - Adds text embeddings directly for intent matching
• RemoveIntent(Id) - Removes a specific intent identified by its unique ID
• EnableIntent(Id) - Enables a specific intent within the runtime data
• DisableIntent(Id) - Disables a specific intent within the runtime data
• GetIntentMapKeys() - Retrieves all intent set IDs currently stored in the runtime data
• GetData() - Returns intent data wrapped as FInworldDataHandle for graph consumption
• Initialize_Implementation() - Processes initial intent assets and loads text embeddings

• Understanding player goals and desires through semantic intent matching
• Triggering appropriate character responses based on detected player intent
• Managing context-sensitive intent recognition with enable/disable capabilities
• Implementing dynamic conversation flows based on detected intents and confidence scores

​

Goals

• GoalTable - Data table defining the goals of the character (must use FInworldGoal row structure)
• ParameterSourceObject - Weak pointer to object implementing IInworldGoalParameterInterface for dynamic parameter generation

• Set(GoalTable) - Sets the goals data table and loads its contents into the goals map
• TryGetGoal(GoalName, GoalOut) - Returns reference to an Inworld Goal by name
• TryGetGoalFromIntent(IntentName, GoalOut) - Returns first goal that has the specified intent
• CompleteGoal(GoalName) - Removes a goal from the goals map if it is not repeatable
• RemoveGoal(GoalName) - Removes a goal from the goals map
• AddGoal(Name, Goal) - Adds a goal to the goals map
• ClearAllGoals() - Removes all goals from the goals map
• SetParameterSourceObject(Source) - Registers a UObject implementing IInworldGoalParameterInterface as parameter source
• GetParameterSourceObject() - Returns pointer to the parameter source object
• GetGoalsMapKeys() - Retrieves all goal names currently stored in the goals map
• GetGoalsDataTable() - Returns pointer to the data table containing the goals
• GetData() - Returns FInworldData_Struct(goalsData) for graph consumption
• Initialize_Implementation() - Initializes the runtime data by loading goals from the configured data table

• Defining character motivations and intent-based objectives
• Creating goal-oriented dialogue and behavior systems
• Implementing quest-like character interactions with completion tracking
• Managing dynamic character objectives based on conversation context and game state

​

Conversation State

• ConversationState - FInworldConversationState containing conversation metadata

• GetConversationState() - Returns current conversation state
• SetConversationState(ConversationState) - Updates conversation state
• GetData() - Returns FInworldData_Struct(ConversationState) for graph consumption

• Managing multi-character conversations
• Tracking conversation flow and turn-taking
• Implementing conversation state-dependent behavior
• Coordinating between multiple AI participants

​

Knowledge Filter

• KnowledgeFilter - Knowledge filter configuration constraining character’s knowledge access with Blueprint exposure

• Set(KnowledgeFilter) - Updates the knowledge filter configuration
• GetKnowledgeFilter() - Retrieves the current knowledge filter configuration as const reference
• GetData() - Returns FInworldData_Struct(KnowledgeFilter) for graph consumption

• Limiting character knowledge based on story context and narrative requirements
• Implementing information security and access control for sensitive topics
• Creating knowledge-limited character variants for different scenarios
• Managing spoiler-free character interactions in story-driven experiences

​

FInworldData Types

• All graph data is FInworldData: Whether passed directly or via UObject containers, all runtime data ultimately becomes FInworldData
• FInworldData_Struct: A special type that can wrap any Unreal struct (like FInworldPlayerProfile) to make it FInworldData-compatible
• Direct vs Container usage: You can use these types directly in graphs, or manage them through UInworldGraphRuntimeData containers that provide functions

​

Basic Data Types

• Simple boolean data wrapper for graph processing
• Property: Bool (bool) - The boolean value

• 32-bit signed integer data wrapper for graph processing
• Property: Int (int32) - The integer value

• Single-precision floating-point data wrapper for graph processing
• Property: Float (float) - The floating-point value

• Unreal Engine object reference wrapper for graph processing
• Property: Object (TObjectPtr<UObject>) - The object reference

// Direct wrapping of any struct
FInworldPlayerProfile profile;
FInworldDataHandle handle = FInworldData_Struct(profile);

// Container usage (what UInworldGraphRuntimeData classes do internally)
FInworldDataHandle UMyRuntimeData::GetData()
{
    return FInworldData_Struct(myInternalStruct);
}

​

Architecture Summary

1. FInworldData is the foundation: All runtime data flowing through graphs is FInworldData or its derivatives
2. Two usage patterns:
   • Direct: Use FInworldData types directly, or wrap structs with FInworldData_Struct(myStruct)
   • Container: Use UInworldGraphRuntimeData classes for function-based management, which internally wrap their data as FInworldData via GetData()
3. FInworldData_Struct is the bridge: Enables any Unreal struct to become FInworldData-compatible
4. Consistent graph interface: Whether using direct types or containers, graphs receive FInworldDataHandle containing FInworldData

​

Components

​

IInworldConversationTarget Interface

• Conversation interruption handling
• Message processing (audio, text, and data)
• Integration with Inworld conversation system

• Individual character components (UInworldBaseCharacterComponent via UInworldConversationTargetComponent)
• Multi-character conversation groups (UInworldConversationGroup)
• Custom conversation handlers

// Interrupts the current conversation or ongoing speech
UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "Inworld")
void Interrupt();

// Sends a message to this conversation target
UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "Inworld")
FString SendMessage(const FInworldDataHandle& Message);

// Sends a message with player information
UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "Inworld")
FString SendPlayerMessage(const FInworldDataHandle& Message, const FInworldPlayerProfile& PlayerProfile);

// Sends a message with runtime data
UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "Inworld")
FString SendDataMessage(const FInworldDataHandle& Message, const TMap<FName, FInworldDataHandle>& RuntimeData);

• Player components can interact seamlessly with either individual characters or conversation groups
• Consistent message handling across different conversation target types
• Blueprint-friendly interface for conversation management
• Polymorphic behavior for different conversation scenarios

​

UInworldConversationTargetComponent

• Conversation target interface implementation (IInworldConversationTarget)
• Readiness state management
• Lifecycle event broadcasting
• Message handling abstraction
• Blueprint and C++ integration

// Gets the unique identifier for this conversation target
UFUNCTION(BlueprintCallable, Category = "Inworld")
const FString& GetId() const;

// Checks if the conversation target is ready and initialized
UFUNCTION(BlueprintCallable, Category = "Inworld")
bool IsReady();

// Unique identifier for this conversation target
UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Inworld")
FString Id;

// Whether the conversation target is ready and initialized
UPROPERTY(BlueprintReadOnly, Category = "Inworld")
bool bIsReady;

// Event fired when conversation target component is ready and initialized
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldConversationTargetReady OnConversationTargetReady;

// Event fired when a character response is generated
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldConversationCharacterMessage OnCharacterMessage;

// Event fired when a player message is received
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldConversationPlayerMessage OnPlayerMessage;

​

Inworld Player Components

​

Component Hierarchy

UInworldBasePlayerComponent (Abstract)
    ↳ UInworldSimplePlayerComponent
        ↳ UInworldPlayerComponent

​

UInworldBasePlayerComponent

• Text and audio message sending
• Conversation target management
• Microphone and voice activity detection
• Audio capture and processing
• Comprehensive event delegation system

// Sends a message to the current conversation target
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void SendMessage(const FInworldDataHandle& Message);

// Sets the current conversation target for this player
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void SetConversationTarget(TScriptInterface<IInworldConversationTarget> NewConversationTarget);

// Gets the current conversation target
UFUNCTION(BlueprintCallable, Category = "Inworld")
TScriptInterface<IInworldConversationTarget> GetConversationTarget();

// Removes the current conversation target
UFUNCTION(BlueprintCallable, Category = "Inworld")
void RemoveConversationTarget();

// Enable/disable microphone
UFUNCTION(BlueprintCallable, Category = "Inworld")
void SetMicrophone(bool Enabled);

// Called when audio is captured from the microphone (commonly overridden)
virtual void OnAudioCapture(const UInworldAudioCapture* AudioCapture, const FInworldData_Audio& AudioData, bool VAD);

UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldPlayerReady OnPlayerReady;

UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldPlayerMessage OnPlayerMessage;

UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldPlayerAudioCapture OnPlayerAudioCapture;

UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldConversationTargetUpdate OnConversationTargetUpdate;

// Configuration settings for audio capture
UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Audio")
FInworldAudioCaptureConfig AudioCaptureConfig;

// Time buffer for Voice Activity Detection in seconds
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Audio")
float VADBufferTime{0.6f};

// Identifier for the Streaming STT Creation Config settings
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Audio")
FString StreamingSTTComponentId{"Default"};

// Whether to start with microphone enabled
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Audio")
bool bStartMicEnabled{true};

​

UInworldSimplePlayerComponent

• Player profile integration
• Enhanced messaging with profile context
• Ready-to-use basic implementation
• Spawnable in Blueprint editor

// Sends a message to the player's conversation target with profile context
virtual void SendMessage(const FInworldDataHandle& Message) override;

// Player profile data used to personalize interactions
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld")
FInworldPlayerProfile PlayerProfile;

• Name (FString) - Player’s name for personalized address
• Gender (FString) - Player’s gender identity for appropriate character responses
• Age (FString) - Player’s age or age category for context-appropriate dialogue
• Role (FString) - Player’s role or position in the game world

​

UInworldPlayerComponent

• Complete player interaction suite
• Trigger system for goal-based interactions
• Custom parameter support
• Advanced conversation control

// Sends a trigger to initiate goal-driven interactions
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void SendTrigger(FName GoalName, const TMap<FString, FString> Parameters);

• Activate specific character behaviors, goals, or conversation paths
• Include custom parameters to provide context and customize the interaction
• Control advanced AI interactions through goal-driven conversations

// Blueprint example - using FName for GoalName as per the API
TMap<FString, FString> TriggerParams;
TriggerParams.Add("location", "tavern");
TriggerParams.Add("mood", "friendly");
PlayerComponent->SendTrigger(FName("greet_player"), TriggerParams);

​

Inworld Character Components

​

Component Hierarchy

UInworldConversationTargetComponent (Abstract) - see above
    ↳ UInworldBaseCharacterComponent (Abstract)
    ↳ UInworldSimpleCharacterComponent
        ↳ UInworldCharacterComponent
    ↳ UInworldConversationGroupComponent

​

UInworldBaseCharacterComponent

• Conversation target implementation (extends UInworldConversationTargetComponent)
• Audio and text message handling via data handles
• Speech synthesis and viseme blending
• Character graph integration for dialogue generation
• Runtime data management system
• Comprehensive event system for speech and conversation events
• Character data table support

// Gets all runtime data for this character (C++ override)
virtual void GetRuntimeData(TMap<FName, FInworldDataHandle>& OutRuntimeData) const;

// Gets all runtime data and its associated type for this character
UFUNCTION(BlueprintPure, Category = "Inworld|Graph", meta = (DisplayName = "Get Runtime Data with Type"))
virtual TArray<FRuntimeDataInfo> GetRuntimeDataAndType() const;

// Applies data from an FInworldCharacterConfig struct to this component's properties
virtual void ApplyCharacterData(const FInworldCharacterConfig& Data);

// Returns the specific type of this component (e.g., Simple or Full)
virtual EInworldComponentType GetComponentType() const;

// Sends a message to this character
virtual FString SendMessage_Implementation(const FInworldDataHandle& Message) override;

// Sends a message to this character with player information
virtual FString SendPlayerMessage_Implementation(
    const FInworldDataHandle& Message, const FInworldPlayerProfile& PlayerProfile) override;

// Sends a message to this character with runtime data
virtual FString SendDataMessage_Implementation(
    const FInworldDataHandle& Message, const TMap<FName, FInworldDataHandle>& RuntimeData) override;

// Called when dialogue generation produces a result (commonly overridden)
UFUNCTION(BlueprintNativeEvent, Category = "Inworld") 
void OnDialogueGenerationResult(const FString& ExecutionId, const FString& NodeId, const FInworldDataHandle& DataHandle);

// Event fired during character speech playback with viseme data
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldCharacterUtterancePlayback OnUtterancePlayback;

// Event fired when character starts speaking
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldCharacterUtteranceStart OnUtteranceStart;

// Event fired when character speech is interrupted
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldCharacterUtteranceInterrupt OnUtteranceInterrupt;

// Event fired when character completes speaking
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldCharacterUtteranceComplete OnUtteranceComplete;

// If true, initialize properties from DataTable using Character ID
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld")
bool bUseDataTable = false;

// The Data Table containing character definitions for this component
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld")
TSoftObjectPtr<UDataTable> CharacterDataTable;

// The ID (Row Name) of the character to load from the CharacterDataTable
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld")
FName CharacterID;

// Reference to the dialogue generation graph asset
UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Inworld|Graph")
TObjectPtr<UInworldGraphAsset> DialogueGenerationGraphAsset;

// Runtime instance of the dialogue generation graph
UPROPERTY(BlueprintReadOnly, Category = "Graph")
TObjectPtr<UInworldGraph> DialogueGenerationGraph;

// Audio component for character voice playback
UPROPERTY(BlueprintReadOnly, Category = "Audio")
TWeakObjectPtr<UInworldVoiceAudioComponent> InworldCharacterAudioComponent;

​

UInworldSimpleCharacterComponent

• Character profile and personality configuration
• Voice and speech settings
• Event history tracking for context
• Conversation state management
• Spawnable in Blueprint editor
• Complete basic character functionality

// Updates the event history by adding a new speech event entry
UFUNCTION(BlueprintCallable, Category = "Inworld|Event History")
void AddHistoryEvent(const FInworldEventSpeech& EventHistoryEntry) const;

// Clears the character's event history data, resetting all stored interactions
UFUNCTION(BlueprintCallable, Category = "Inworld|Event History")
void ClearHistory() const;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_CharacterProfile> CharacterProfile;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_Voice> Voice;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_EventHistory> EventHistory;

// Event fired when dialogue is generated and ready
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldCharacterDialogueResponse OnDialogueResponse;

​

UInworldCharacterComponent

• Emotion state tracking and emotional responses
• Relationship state management with dynamic character relationships
• Knowledge base and knowledge filtering
• Goal system with completion tracking
• Intent recognition and processing
• Advanced TTS output processing and buffering

// Checks if this character is currently part of a conversation group
UFUNCTION(BlueprintCallable, Category = "Inworld")
bool IsInConversationGroup();

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_EmotionState> EmotionState;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_RelationState> RelationState;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_Knowledge> Knowledge;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_KnowledgeFilter> KnowledgeFilter;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_Goals> Goals;

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld|Manual Config")
TObjectPtr<UInworldGraphRuntimeData_Intent> Intents;

// Event fired when a character goal is completed
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldGoalComplete OnGoalComplete;

​

UInworldConversationGroupComponent

• Multi-character conversation management
• Speaker selection graph integration
• Participant management (add/remove characters)
• Event history tracking
• Blueprint accessible conversation control

// Adds a character to the conversation group
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void AddCharacter(UInworldCharacterComponent* CharacterComponent);

// Removes a character from the conversation group
UFUNCTION(BlueprintCallable, Category = "Inworld")  
virtual void RemoveCharacter(FString CharacterId);

// Gets all character participants in the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
TArray<UInworldCharacterComponent*> GetParticipants();

// Manually invokes the next character response in the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void InvokeNextResponse(const FString& CharacterId = "");

// Gets the current player target for the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
UInworldBasePlayerComponent* GetPlayerTarget();

// Gets the current state of the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
FInworldConversationState GetConversationState();

// Clears the group's event history data
UFUNCTION(BlueprintCallable, Category = "Inworld|Event History")
void ClearHistory(bool IncludeCharacters = false) const;

// Inworld graph for intelligent speaker selection in multi-character conversations
UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Graph")
TObjectPtr<UInworldGraphAsset> SpeakerSelectionGraphAsset;

// Event fired when a character is added to the conversation
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldCharacterAddedToConversation OnCharacterAdded;

// Event fired when a character is removed from the conversation
UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldCharacterRemovedFromConversation OnCharacterRemoved;

​

Inworld Conversation Group (UObject)

​

Key Features

• Multi-character conversation management - Coordinates multiple AI participants
• Intelligent speaker selection system - AI-driven selection of appropriate responders
• Message broadcasting - Distributes messages to all participants
• Conversation state and history tracking - Maintains context across interactions
• Player target integration - Connects with player components
• Event system - Comprehensive monitoring of conversation activities
• Dynamic participant management - Add/remove characters during conversations

​

Core Functions

// Creates a new conversation group asynchronously (Blueprint version)
UFUNCTION(BlueprintCallable, Category = "Inworld", meta = (WorldContext = "WorldContextObject"))
static void CreateConversation(UObject* WorldContextObject, UObject* Owner, 
                              FOnInworldConversationGroupCreated Callback,
                              UInworldGraphAsset* SpeakerSelectionGraphAsset = nullptr);

// Creates a new conversation group asynchronously (C++ version)
static void CreateConversation(UObject* WorldContextObject, UObject* Owner, 
                              FOnInworldConversationGroupCreatedNative NativeCallback,
                              UInworldGraphAsset* SpeakerSelectionGraphAsset = nullptr);

// Adds a character to the conversation group
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void AddCharacter(UInworldCharacterComponent* CharacterComponent);

// Removes a character from the conversation group
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void RemoveCharacter(FString CharacterId);

// Gets all character participants in the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
TArray<UInworldCharacterComponent*> GetParticipants();

// Sets the player target for this conversation group (C++ only)
virtual void SetPlayerTarget(UInworldBasePlayerComponent* PlayerComponent);

// Removes the current player target from this conversation group (C++ only)
virtual void RemovePlayerTarget();

// Gets the current player target for the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
UInworldBasePlayerComponent* GetPlayerTarget();

// Sends a message to the conversation group
virtual FString SendMessage_Implementation(const FInworldDataHandle& Message) override;

// Sends a message to the conversation group with player information
virtual FString SendPlayerMessage_Implementation(
    const FInworldDataHandle& Message, const FInworldPlayerProfile& PlayerProfile) override;

// Sends a message to the conversation group with runtime data
virtual FString SendDataMessage_Implementation(
    const FInworldDataHandle& Message, const TMap<FName, FInworldDataHandle>& RuntimeData) override;

// Cancels the current message and interrupts all characters in the group
virtual void Interrupt_Implementation() override;

// Manually invokes the next character response in the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
virtual void InvokeNextResponse(const FString& CharacterId = "");

// Gets the current state of the conversation
UFUNCTION(BlueprintCallable, Category = "Inworld")
FInworldConversationState GetConversationState();

// Clears the group's event history data
UFUNCTION(BlueprintCallable, Category = "Inworld|Event History")
void ClearHistory(bool IncludeCharacters = false) const;

​

Events

UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldConversationPlayerMessage OnPlayerMessage;

UPROPERTY(BlueprintAssignable, Category = "Inworld")
FOnInworldConversationCharacterMessage OnCharacterMessage;

​

Properties

// Instruction text provided to AI for next response generation
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld")
FString NextResponseInstruction{"consider all individuals present in the conversation."};

// Event history runtime data for tracking conversation context
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inworld")
TObjectPtr<UInworldGraphRuntimeData_EventHistory> EventHistory;

​

Usage Pattern

// 1. Create conversation group
UInworldConversationGroup::CreateConversation(this, this, 
    FOnInworldConversationGroupCreatedNative::CreateLambda([this](UInworldConversationGroup* Group, bool Success)
    {
        if (Success && Group)
        {
            ConversationGroup = Group;
            
            // 2. Add characters to the conversation
            Group->AddCharacter(Character1Component);
            Group->AddCharacter(Character2Component);
            Group->AddCharacter(Character3Component);
            
            // 3. Set player target
            Group->SetPlayerTarget(PlayerComponent);
            
            // 4. Set up event bindings
            Group->OnPlayerMessage.AddDynamic(this, &AMyActor::OnPlayerSpoke);
            Group->OnCharacterMessage.AddDynamic(this, &AMyActor::OnCharacterSpoke);
            
            // 5. Send messages to the group using IInworldConversationTarget interface
            FInworldData_Text TextMessage;
            TextMessage.Text = "Hello everyone!";
            FInworldPlayerProfile PlayerProfile;
            PlayerProfile.Name = "Player";
            Group->SendPlayerMessage(TextMessage, PlayerProfile);
        }
    }));

​

Usage Guidelines

​

Choosing the Right Components

• Basic player interactions are sufficient
• Player profile personalization is needed
• Simple text/audio messaging is the primary requirement
• No advanced trigger system is needed

• Full-featured player interactions are required
• Goal-driven conversations are needed
• Trigger system with custom parameters is necessary
• Maximum flexibility and control is desired

• Basic AI character functionality is sufficient
• Character profile and voice settings are needed
• Event history tracking is desired
• Advanced AI features are not necessary

• Advanced AI capabilities are required
• Emotion and relationship tracking are needed
• Conversation state management is important
• Goal-driven behavior and intent recognition are necessary
• Complex multi-graph AI processing is required

• Multiple AI characters need to participate in conversations
• Intelligent speaker selection is required
• Complex multi-participant dialogue management is needed
• Group conversation state tracking is important

​

Best Practices

1. Choose the appropriate component level based on feature requirements
2. Configure all necessary runtime data before beginning play
3. Set up event bindings early in component initialization
4. Assign player profiles and character profiles for personalized interactions

1. Use direct FInworldData types (like FInworldData_Bool) for simple data
2. Use UInworldGraphRuntimeData containers for complex data that needs manipulation functions
3. Ensure all runtime data is properly initialized before graph execution
4. Use FInworldData_Struct to make any Unreal struct graph-compatible

1. Always set a conversation target before sending messages
2. Handle conversation target changes in your UI system
3. Use conversation groups for multi-character scenarios
4. Clean up targets when switching contexts

1. Monitor speech events for responsive UI feedback
2. Configure voice settings appropriately for each character
3. Handle microphone permissions on different platforms
4. Provide visual feedback for audio capture and playback status

1. Configure appropriate runtime data for character behavior
2. Set up goals and intents for character behavior patterns
3. Use emotion and relationship states to create dynamic interactions
4. Use player triggers strategically for scripted story moments
5. Leverage conversation groups for multi-character scenarios