Skip to main content

Character Mutations


Character Mutations allow you to make temporary modifications to the Agent fields of a character which can affect their emotions, outlook, or general mannerisms. These changes expire when the current session does, so are useful when creating momentary changes to a character in response to player actions or in-game events.

Mutations are part of the Goals system, and allow you to modify the currently active character as an Action within their Goals.

To enable or disable a character Goal within Unity or Unreal, see: Enable Goals

Goals and Multiple Actions

It is possible to specify multiple actions as a part of a single Goal. When this occurs, mutations are then applied to the character after the remaining actions are executed, in order.

For example, if a goal has two actions such as: “greet the player”, and “set_motivation: ‘sell sword to the player’”, then the motivation field would be updated after the character greets the player.

Functional Boundaries

This section outlines the functional boundaries and characteristics of character mutations.

Variability Across Sessions

  • Mutations are scoped to the session.
  • You can apply various mutations to the same character across different sessions. 
  • Mutations are not retained beyond the current session, and are permanently lost when the session expires.

Mutation Application

  • Multi-Field Mutation: A single mutation within the goal may mutate multiple fields.
  • Sequential Execution: When a goal comprises multiple actions, mutations are applied after executing all other actions in the specified order. For example: if a goal includes actions such as greeting the player and then setting a motivation, the mutation affecting the motivation field would occur post-greeting.
  • Direct Values or Templates: Each mutation field must contain either the Exact Value to set or a Template. If a Template is used, it is compiled using known trigger parameters. The compiled results are validated before being applied to mutate the character field.
  • Reset: There is no function to reset a field to its original value after a mutation. To reset a field to its original value, you must explicitly call a mutation with the Original Value.

Field References

This chart details the field references related to character mutations.

set_motivationString512 chars
set_personality: negative_positive aggressive_peaceful cautious_open introvert_extravert insecure_confidentString, numberInteger 1-9 inclusive, or strings “1”-”9”.Each field may be specified or omitted separately. If no field specified - there would be no effect.
set_mood: sadness_joy anger_fear disgust_trust anticipation_surpriseString, numberInteger 1-9 inclusive, or strings “1”-”9”.This is not a constant ‘mood’ setting it can be considered the ‘initial mood’ for the character. It is used to set up an emotional state at the start of conversation. Also it sets up ‘target emotion’. Character emotions will slowly slide towards the target emotion during the conversation.
set_mood: emotional_fluidityString, floatFloat value from -1.0 to 1.0 inclusive. Or string representation of the same value.-1 means that emotions would not change. +1 emotions change quite quickly.
set_character_nameString512 chars
set_core_descriptionString1024 chars
set_pronounsString, enumPossible values: UNSPECIFIED, SHE/HER, HE/HIM, THEY/THEM,Case insensitive. UNSPECIFIED has the same behavior as THEY/THEM
set_alternate_namesList of strings10 elements max, 512 chars max eachCharacter nicknames
set_example_dialogueString512 charsExample dialog is a single large string.
set_wikipedia_urlString512 charsNo URL validation
set_character_traitsList of strings10 elements max, 512 chars max eachIf not set - character traits will be populated automatically from ‘personality’.
set_hobbies_and_interestsList of strings10 elements max, 512 chars max each
set_character_roleString512 chars
set_custom_dialogue_style: set_adjectivesList of strings3 elements max, 512 chars max eachcustom_dialogue_style is mutually exclusive with dialogue_style. Only one of them may be used at the same time. There is a hidden variable that tells which one to use. Therefore, if mutation contains only set_custom_dialogue_style - custom_dialog_style will become ‘enabled. If only set_dialogue_style - dialogue_style will be used. If both - no modifications will be applied.
set_custom_dialogue_style: set_colloquialismString512 chars
set_flawsString512 chars
set_voice_data: set_voiceString512 charsVoice names are validated against TTS service at runtime, attempts to set up an non-existent voice will be ignored
set_voice_data: set_pitchFloat, StringFloat in range -0.5 to 1.5 inclusive, to string representation
set_voice_data: set_talking_speedFloat, StringFloat in range 0.5 to 1.5 inclusive, string representation
set_relationshipString, enumUNKNOWN, ARCHENEMY, ENEMY, ACQUAINTANCE, FRIEND, CLOSE_FRIEND, DATE, RELATIONSHIP, LIFE_PARTNERValues are case insensitive. Values are mapped back to relationship state variables. Relationship state itself is hidden and not modifiable.
set_relationship_primitives: trust, respect, familiar, flirtatious, attractionNumberInteger from -1000 to 1000 inclusive.Each field may be specified or omitted separately.
enable_goalsList of strings200 elements max, 512 char each200 - is a limit to the number of goals we can have in a single agent. enable_goals should contain goals names, case sensitive. If the goal with the given name does not exist - it will be silently ignored.
disable_goalsList of strings200 elements max, 512 char each
set_profile_variables: id valueList of objects10 elements max, 512 char on id 512 char on valueAllow only the modification of existing profile variables. Unknown variables will be silently ignored.
enable_common_knowledgeList of strings100 elements max, 512 chars eachContains common_knowledge ids, not common knowledge names. Common knowledge names are not unique.
disable_common_knowledgeList of strings100 elements max, 512 chars each
set_scene_descriptionString1024 charsReplacement for scene triggers.
add_personal_knowledgeList of strings10 elements max, 400 chars eachAdds items to the personal knowledge of agents for the current session.
remove_personal_knowledgeList of strings10 elements max, 400 chars eachBlocks the similar knowledge items from personal and common knowledge.

Common Knowledge ID

Unique Common Knowledge IDs can be found in URL of each Knowledge section within Inworld Studio.


Personal Knowledge Mutations

Personal Knowledge Mutations allow you to add knowledge to characters through the use of Facts, and if needed, also block specific types knowledge from a character's awareness.

This consists of two references, found in the Field References chart above: add_personal_knowledge and remove_personal_knowledge

Duplicate Facts

If the same fact is entered in both in the Added and Removed section, then it is regarded as if it were Removed.

Facts are Additive

Newer facts do not replace older facts, they simply add to the overall pool of facts for a character.

For example, if you apply an add_personal_knowledge that includes Fact 1 and Fact 2, and then later add another add_personal_knowledge that includes Fact 3 and Fact 4, the character now knows all four facts.

Replacing Facts

When replacing a fact within a knowledge mutation, you must first use the Remove option to remove the old one before using the Add option to add your new one.

Fact Limit

The total limits for collected facts are as follows:

  • 20 for Added
  • 20 for Removed

If you add a 21st fact, the 1st fact is marked as "expired,” and you will receive a custom event informing you this has occurred.

Fact Parameters

The parameters for Facts are shown below:

  1. workspaces/workspace_id/characters/agent_id
  2. Executes user-defined event: inworld.brain.inspect.mutation
  3. With parameters: { mutable_personal_knowledge_items_expired: ["fact_1"], }


Templates in mutations are similar to those used in Goals, allowing for dynamic content generation.

These templates are based on a syntax that uses Placeholders within Strings to insert variable values.

Text vs Non-Text Mutations

Mutations may impose specific restrictions on templates that vary based on the type of data being manipulated:

Text Mutations

These mutations support complex templates with multiple variable references and no restrictions.

For example, a template might combine characters, items, and prices in a single sentence.

# Example of a text mutation template:
set_motivation: "{{character}} wants to sell {{p.item}} to the player. It costs {{p.price}} gold."

Non-Text Mutations

These mutations are limited to templates with a single variable reference, focusing on straightforward, single-value changes.

# Example of a non-text mutation template:
set_dialogue_style: "{{p.dialogue_style}}"

Validation and Runtime Handling

Design-Time Validation: Templates are checked for correctness during the design phase. Any templates with errors cannot be saved.

Runtime Processing: During execution, non-text field templates are rendered and parsed into their respective types, such as enumerations or specific value formats.

In the example above for Non-Text Mutations, validation and processing is set as the _example_dialog_style_ enum.

Developers working with the character are responsible for ensuring parameter values are correctly set.

⚠️ Note: If a value cannot be parsed, runtime errors are propagated to the client.

Mutable Fields YAML

Provided below is an example of YAML with all mutable fields specified.

 - name: "test"
       - "trg"
     - character_changes:
         set_emotion: AFFECTION
         set_motivation: "motivation"
         set_dialogue_style: "Bubbly"
           negative_positive: 2
           aggressive_peaceful: 3
           cautious_open: 4
           introvert_extravert: 5
           insecure_confident: 6
           sadness_joy: 1
           anger_fear: 2
           disgust_trust: 3
           anticipation_surprise: 4
           emotional_fluidity: 0.2
           relationship_fluidity: 1
         set_character_name: "name"
         set_core_description: "descr"
         set_pronouns: he/him
           - "name1"
           - "name2"
         set_example_dialogue: "hey"
         set_wikipedia_url: "url"
           - "trait1"
           - "trait2"
         set_life_stage: EARLY_SCHOOL
           - "hobby1"
           - "hobby2"
         set_character_role: role
             - "adj"
           set_colloquialism: "set_colloquialism"
         set_flaws: "flaws"
           set_voice: "some voice"
           set_pitch: 1.0
           set_talking_speed: 1.1
         set_relationship: "relationship"
             trust: -100
             respect: -50
             familiar: 0
             flirtatious: 50
             attraction: 100
           - "goal1"
           - "goal2"
           - id: "id"
             value: "new value"
           - "id_to_add"
           - "id_to_remove"
         set_scene_description: "scene2"

Enable Goals

As previously mentioned, mutations are part of the goals system. To take advantage of the Mutations feature, goals must be Enabled.

To Enable and Disable goals for the Unity SDK and Unreal SDK, follow the steps below.

Enable and Disable Goals in Unreal

To Enable a goal in the Unreal SDK, a trigger must be sent with the name of the goal:

inworld.goal.enable.{name-of-goal}Enables an existing goal on the server.
inworld.goal.disable.{name-of-goal}Disables an existing goal on the server.

Enable and Disable Goals in Unity

The Unity SDK includes a wrapper function for enabling or disabling goals.

This wrapper automatically sends the necessary trigger, as shown below:

EnableGoalEnables an existing goal on the server.goalName: The name of the goal to enable.
DisableGoalDisables an existing goal on the server.goalName: The name of the goal to disable.