Skip to main content

Goals

Goals v3​

A character's Goals determine what a character wants to accomplish, and how. The Goals v3 system allows you to specify in plain language when the character should begin pursuing a specific goal and when it should consider the goal accomplished. By doing so, the character can guide the dialogue towards achieving the set goal.

This area includes a YAML Interface that allows you to enter the various goals associated with the character.

The Goals System​

Goals v3 combines traditional state machine dialog management with AI technology, blending the predictability and configurability of state machine systems with the flexibility and ease of configuration provided by AI.

By harnessing the power of natural language processing and AI, Goals v3 allows for the creation of intelligent virtual characters that can understand, process, and respond to user inputs in a human-like manner.

Goals v2 vs v3​

Within the Goals system, you have the option of selecting either 2.0 and 3.0 using the drop-down menu provided. Goals Dropdown

The v2 goals system is legacy, so it is recommended all new characters use the v3 goals, which are covered by this guide.

How Goals Work​

Goals serve as pivotal markers that drive the behavior of virtual characters.

These markers can be activated and completed based on specified conditions that you set. When a goal is activated, the character utilizes a Motivation, which is described in natural language. The original character's motivation is then replaced with the new one, from the active goal, and remains in effect for the entire duration that the goal is active.

This system ensures characters respond and act in alignment with any objectives and motivations assigned to them, creating dynamic and engaging conversational experiences where characters actively work towards accomplishing predefined goals within the dialogue.

One Goal at a Time​

  • Single Active Goal: No more than one goal can be active at any one time. This ensures focused progress and efficient resource allocation.

  • Automatic Goal Switching: Note that in some cases, even when you have an active goal that has not been completed, the system may decide to activate a different goal. In such instances, the current active goal will be abandoned without completion, and a new goal will be activated.

Goals Basics​

A goal is structured into three configurable parts that define its behavior: Activation, Motivation, and Completion.

Activation​

Optional Activation is governed by an activation_condition, that specifies when the goal should be triggered, and an on_activation function that modifies the character's state and emit triggers for client logic handling. If the goal is equipped with an Activation only, the system will prompt the character to generate a response / say nothing / say verbatim, execute the actions outlined in the Activation phase, and autocomplete the goal.

Motivation​

Optional Motivation provides instructions to the character on how to proceed while the goal is active, enabling the character to navigate dialogue effectively with the player in pursuit of the goal.

Completion​

Optional Completion, structured with a completion_condition and an on_completion function, determines when the goal can be marked as achieved and outlines any subsequent actions to be taken. In scenarios where a goal has only the Completion, it is required to set completion_without_activation: true. This configuration indicates that the goal can be completed without prior activation. Goals with this setup are assigned the lowest priority during the evaluation process.

Goal Lifecycle​

Goal evaluation occurs twice in every interaction.

The first evaluation takes place upon Receiving Player Input, and the second occurs after the Character Has Replied.

Activation of a goal can only occur during the first evaluation step, based on the activation condition. Goal completions, on the other hand, can occur during both evaluation steps.

Once the system senses that "goals must be completed" or identifies a single particular goal that should be activated, it executes the corresponding function, which can be either on_completion or on_activation.

This iterative process repeats during each interaction throughout the dialogue with the character.

Configuring a Goal​

To configure a goal for a character, open their profile and navigate to their Advanced tab.

Then, select Goals from the options provided.

Select Goals

This takes you to the Goals interface where you can press the Edit button to open a YAML editor to implement any goals as needed.

Select Goals

Intent​

Intent object allows to define intent name which could be later used in the goal object as a condition for goal activation or goal completion.

Intent Fields​

NameDescription
nameName of the intent.
training_phrasesList of training phrases for this intent.

Intent Example​

intents:
  - name: 'quest_request'
    training_phrases:
      - 'How can I increase my attack damage?'
      - 'What equipment should I have for the next quest?'
      - 'Where can I get a weapon around here?'
      - 'What items do you have to increase strength?'
      - "What's the best weapon I can get?"

Goals​

The content within a Goal determines what a character wants to accomplish, and how.

Goal Fields​

General​
NameDescription
MotivationMotivation of character while goal is active.
RepeatableFalse by default, can this goal be activated/completed after completion.
Completion_Without_ActivationFalse by default, allows to make goals completable without activation.
Extracted_Entities​
NameDescription
NameName of the entity to use in this goal conditions and mutations. See Entities for more info on how to configure entities for your workspace. Note: Only entities with regex or dictionary rules could be used here.
Activation_Condition​

Note: condition fields are concatenated in the following logical expression: [Required_Goals] and [Logical_Expression] and ([Trigger] or [Intent] or [Detect])

NameDescription
Required_GoalsRequire certain goals to be completed, works as a prerequisite for the goal.
Logical_ExpressionJinja style logical expression for this goal to be activated.
TriggerClient-side trigger which can activate the goal.
IntentIntent which can activate the goal.
DetectAnalyses recent history of conversation and tries to detect certain situations.
On_Activation​
NameDescription
Say_VerbatimExact text to be said by the AI without generation.
Say_NothingIf true, then no answer from character.
Say_InstructionInstruction for the AI to generate a response.
MutationsExecute selected mutation. See Mutations for full list of mutations.
Send_TriggerSends a trigger to the client.
RandomRepresents a random selection of behaviors, see: Example.
Random_WeightDetermining the probability of this option being chosen. It is 1 by default.
Completion_Condition​

Note: condition fields are concatenated in the following logical expression: [Required_Goals] and [Logical_Expression] and ([Trigger] or [Intent] or [Detect])

NameDescription
Required_GoalsRequire certain goals to be completed, works as a prerequisite for the goal.
Logical_ExpressionJinja style logical expression for this goal to be completed.
TriggerClient-side trigger which can complete the goal.
IntentIntent which can complete the goal.
DetectAnalyses recent history of conversation and tries to detect certain situations.
On_Completion​
NameDescription
MutationsExecute selected mutation. See Mutations for full list of mutations.
Send_TriggerSends a trigger to the client.
RandomAllows for the randomization various functions, see: Example
Random_WeightUsed to specify weight of given random element.
If you have previously used Goals v2:
  • Goals 3.0 no longer supports disable/enable_goals functionality.
  • Goals 3.0 now utilizes set_variables instead of set_profile_variables.

Logical Expressions​

Within Inworld's Goals system, you may specify logical expressions for activation and completion conditions using Jinja-style Logical Expressions, including logical operators and syntax.

Refer to the following guidance when using logical expressions in Goals:

  1. Logical Operators

  • and, or, not: You can use these Jinja logical operators.

  • Example: logical_expression: "p.account_type.value is defined and p.account_type.value != ''"

  1. Comparisons

  • You can use comparison operators like ==, !=, <, >, <=, >=.

  • Example: logical_expression: "c.age.value is defined and c.age.value >= 18"

Variables/Namespaces​

There are two namespaces prefixes for variables that can be used in the Goals configuration:

  1. Trigger Parameters Namespace You may refer trigger parameters in logical expression or other fields using the 'p.' Prefix.

Example:

goals:
## Goal receives trigger with parameters, which are used in character utterance
## Example: "trigger_with_params" trigger sent from the client with params {"param1": "Inworld", "param2": "Goals v3"}
  - name: "output_parameters"
    activation_condition:
      trigger: "trigger_with_params"
    on_activation:
      say_verbatim: "I like {{p.param1}} and {{p.param2}}!" # character says "I like Inworld and Goals v3!"
  1. Character State Namespace To refer character related state (such as extracted entities) you may use 'c.' Prefix. Example:
goals:
  - name: play_guess_color
    motivation: "Ask user to guess the color."
    extracted_entities:
      - name: color
    on_activation:
      say_instruction: "Ask user to try to guess the color you have in mind."
    completion_condition:
      logical_expression: "c.color.value == 'red'"
    on_completion:
      send_trigger: "correct_color"

Goal Example​

goals:
  - name: sword_offer
    motivation: "Offer the sword to {{player}} and explain its benefits. Answer in brief lines. "
    on_activation:
      say_instruction: "Greet {{player}} and offer a sword for sale."
      send_trigger: sword_offer_activated
    completion_condition:
      detect: "{{player}} shows interest in buying the sword, by commenting something or asking something about the sword"
    on_completion:
      send_trigger: sword_offer_completed

Goal Interdependencies​

In the realm of goal management, the Required_Goals and Logical_Expression features serve as valuable tools for handling goal dependencies.

In situations where a group of goals must remain inactive until a specific event occurs—such as a client-side trigger or the completion of another goal — the Required_Goals list and Logical_Expression come into play. This functionality allows for the strategic control and synchronization of goal progression within the system.

## Guess the color game

goals:
  - name: play_guess_color
    motivation: "Ask user to guess the color. Your color is red. You can give a hint to user after multiple tries but do not say the color."
    extracted_entities:
      - name: color
    on_activation:
      say_instruction: "Ask user to try to guess the color you have in mind."
    completion_condition:
      logical_expression: "c.color.value == 'red'"
    on_completion:
      send_trigger: "correct_color"

  - name: say_goodbye
    repeatable: true
    activation_condition:
      required_goals: [play_guess_color]
    on_activation:
      say_instruction: "Congrats {{player}}! You won. My color was indeed {{c.color.value}}."
      send_trigger: finish_game

Goals v3 Use-Case Example​

Provided below is an example showcasing the Goals system's dynamic states, specifically the flexibility of detect.

goals:
  - name: ask_for_number
    motivation: "Ask for the correct number until guessed correctly."
    activation_condition:
      required_goals: [instructions_given]
    on_activation:
      say_instruction: "Ask for the guessed number."
    completion_condition:
      detect: "Correctly guesses a number above 5."
    on_completion:
      send_trigger: game_won

Random Example​

Example of using random section on each start trigger to get different random outcomes.

goals:
  - name: random_goal
    repeatable: True
    activation_condition:
      trigger: "start"
    on_activation:
      random:
        - send_trigger: random1
          say_instruction: say random 1
          weight: 123
        - send_trigger: random2
          say_instruction: say random 2
          ## weight is not required, 1 by default.
    on_completion:
        random:
          - send_trigger: complete1
            weight: 1
          - send_trigger: complete2
            weight: 2

Natural Language Detect Triggers​

In this example, Detect provides broad flexibility in the definition of the goal's completion, allowing for a natural language definition of the goal's completion trigger.

This goal can also be made a prerequisite for activating the next goal. In this specific example, ensuring the subsequent game begins only after the current game is won by guess the number correctly.

Sample Goals v3 YAML​

The examples below showcase how to structure the various elements of Goals 3.

intents:
  - name: "quest_request"
    training_phrases:
      - "Do you have any quests for me?"
      - "What quest should I take on next?"
      - "What quests can I take on here?"
      - "Are there any quests I can take to help me level up?"
      - "Give me a quest"

  - name: "ask_for_weapon"
    training_phrases:
      - "How can I increase my attack damage?"
      - "What equipment should I have for the next quest?"
      - "Where can I get a weapon around here?"
      - "What items do you have to increase strength?"
      - "What's the best weapon I can get?"

goals:
  - name: "greeting"
    motivation: "Greet the player when they enter the shop"
    repeatable: false
    activation_condition:
      trigger: "greeting"
    on_activation:
      say_verbatim: "Welcome to the Shop of Curiosities and Wonders! Are you new around these parts?"
      send_trigger: "greeting_goal_activated"

  - name: "pitch_weapon"
    motivation: "Guide the player to find a weapon"
    repeatable: true
    activation_condition:
      intent: "ask_for_weapon"
    on_activation:
      say_verbatim: "Tell {player} to visit Queen Bee to get a javelin made with a honeybee's stinger."
      mutations:
        set_emotion: "JOY"
      send_trigger: "pitch_weapon_goal_activated"

  - name: "give_quest"
    motivation: "Offer a quest to the player"
    repeatable: true
    activation_condition:
      intent: "quest_request"
      trigger: "give_quest"
    on_activation:
      random:
        - say_instruction: "Give a quest to retrieve the ancient candy recipes that were stolen by Lord Toffee!"
          send_trigger: "give_quest_goal_activated"
          weight: 20
        - say_instruction: "Give a quest to rescue the princess from the clutches of the dragon"
          send_trigger: "give_quest_goal_activated"
          weight: 50
        - say_instruction: "Give a quest to uncover who destroyed Candycane Tower"
          send_trigger: "give_quest_goal_activated"
          weight: 30

Goals v2​

Notice

We encourage using Goals 3.0 for new characters and experiences as the new Goals 3.0 system provides more control and flexibility to create more engaging and dynamic interactions. Our support team is available to assist with any questions you might have.

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.

This area includes a YAML Interface that allows you to enter the various goals associated with the character.

interface

New Goals Require New Session​

Note that when adding new goals or making changes to the existing goals of a character, these changes will not be active until a new session is started.

How Goals Work​

The Goals system leverages contextual intents as activation conditions, passing real-time information from a client to a character through a set of parameters, which then control when a character delivers a pre-scripted line.

All of these features are defined in a flexible code editor, written in YAML Syntax.

YAML Syntax​

YAML is a human-friendly data serialization language that structures information in a format both humans and machines can understand.

Within YAML, syntax indentation matters, as it denotes structure. In addition, sequences such as arrays or lists are denoted by a hyphen (-), and key-value pairs are separated by a colon (:).

The basic structure of a YAML file is shown below:

Key: Value
List:
  - Item1
  - Item2
Dictionary:
  Key1: Value1
  Key2: Value2

To learn more about YAML, see: The YAML Project

Goals Key Concepts​

A character's Goals consist of three key elements, which are all Required for the system to function:

  • Goal
  • Activation
  • Action

There are also a number of Optional parameters within Activations and Actions, covered in the sections below.

Goal​

Required. The Goal operates as a 'consequence mechanism' which gets triggered by an Activation event that initiates a specific Action. This mechanism also monitors the achievement of a character's Goals, issuing a signal to the client upon the completion of a Goal.

For example, if you have a Goal to have a character suggest a quest to the player, your Activation condition might be the player asking about available quests. When this Intent is recognized, the Goal is activated, and the character begins executing the associated actions - in this case describing the quest and instructing the player on how to start it. Once the character finishes these actions, the Goal is marked as completed, and a Trigger is sent to the client.

Example of a Goal:

goals:
  - name: 'give_quest'
    repeatable: True
    actions:
      - instruction: 'give {player} a quest to retrieve the ancient candy recipes that were stolen by Lord Toffee'
        character_changes:
         set_emotion: 'VALIDATION'
    activation:
      intent: 'quest_request'
      trigger: 'give_quest'

Activation​

Required. The event that triggers the Goal. An activation can include up to two components: an Intent and a Trigger. Each Activation must include at least one Intent or Trigger, but does not require both.

Intent
Optional. An Intent utilizes a real-time detection engine that scans the player's conversation to identify any intentions that align with those predefined in Training_Phrases. When a match is identified, the Intent is activated and its name is passed to the Goal, triggering it. Note that multiple Intents can trigger the same Goal.

You can only leverage the Intent feature within the Goals & Actions tool to establish an intent detection system.

Trigger
Optional. A Trigger is a user-specified parameter used to initiate the Goal.

Activation by Intent and Trigger:

activation:
  intent: 'quest_request'
  trigger: 'give_quest'

Intent setup:

intents:
  - name: 'quest_request'
    training_phrases:
      - 'How can I increase my attack damage?'
      - 'What equipment should I have for the next quest?'
      - 'Where can I get a weapon around here?'
      - 'What items do you have to increase strength?'
      - "What's the best weapon I can get?"

Multiple Intent examples setup:

activation:
  intent: ['quest_request','second_quest_request']

# Another way to represent multiple intents triggering the same goal
activation:
  intent:
    - 'quest_request'
    - 'second_quest_request'

Action​

Required. The Action is a set of responses that occur after an Activation condition has been met. Action types include control over character dialogue via Instruction or Say_Verbatim, and client/server communication via Send_Trigger and leveraging parameters within dialogue actions.

An Action cannot include both Instruction and Say_verbatim at the same time - it must use one or the other.

For character state changes, see: Character Mutations

Instruction
Optional. The Instruction field provides specific guidance on how a character should respond after a Goal has been activated. The character will follow the instruction while maintaining their own unique personality.

When writing an Instruction with a direct command (that starts with a verb) it is recommended you phrase it as if you were giving a direct command to an actor.

Say_Verbatim
Optional. This is a text string that characters will recite exactly as written after a Goal has been activated.

Giving an action Instruction and Set_Emotion:

actions:
  - instruction: "tell {player} to visit Queen Bee to get a javelin made with a honeybee's stinger"
    character_changes:
      set_emotion: 'JOY'

Giving an action Say_Verbatim:

actions:
  - say_verbatim: 'Welcome to the Shop of Curiosities and Wonders! Are you new around these parts?'

Send_Trigger
Optional. This is a user-defined name that sends a signal back to the developer when a Goal is fired. It can be used in conjunction with the intent detection system to receive a signal when a custom Intent is detected.

Set_Emotion
Optional. This is a Mutation that allows you to set an emotion for the character. When activated, an Set_Emotion influences the character's emotions from the point when it is triggered. This emotion change lasts until either the session ends or the character's emotions are mutated again. Set_Emotion must be preceded by Character_Changes.

Activation Intent and actions Send_Trigger:

goals:
  - name: "pitch_weapon"
  activation:
    intent: "ask_for_weapon"
  actions:
    - instruction: "tell {player} to visit Queen Bee to get a javelin made with a honeybee's stinger"
      character_changes:
        set_emotion: "JOY"
      send_trigger: "ask_for_weapon_detected"

Random
Optional. This feature assigns a Probability (a number between 0 and 1) to an Action item such as an Instruction, Say_Verbatim, or Set_Emotion. When a Goal is activated, the Action item is then executed based on this Probability.

In the example on the right, the character has a 20%/50%/30% chance of giving different quests.

If random is used, then say_verbatim, instruction, and set_emotion must all be nested under random with assigned probabilities.

Giving actions using Random:

actions:
  - random:
      - probability: 0.2
        instruction: 'give a quest to retrieve the ancient candy recipes that were stolen by Lord Toffee!'
      - probability: 0.5
        instruction: 'give a quest to rescue the princess from the clutches of the dragon'
      - probability: 0.3
        instruction: 'give a quest to uncover who destroyed Candycane Tower'

Customizable Parameters when Changing an Action​

If needed, you can write Say_Verbatim and Instruction with parameters that inject real-time information from the client (delivered through the Trigger) to an action at runtime. These parameters can only be used within the context of the Goals file.

An example of this process is shown below:

  • Step 1: Write the goal as shown below. 
    goals:
      - name: 'pitch_weapon'
        activation:
          intent: 'ask_for_weapon'
          trigger: 'pitch_weapon'
        actions:
          - instruction: "tell {player} to visit {{p.place}} to get a javelin made with a honeybee's stinger"
            character_changes:
              set_emotion: 'JOY'
            send_trigger: 'ask_for_weapon_detected'
  • Step 2: Developers send a request message that includes the Trigger. For example, in API, send: "triggerEvent": { "trigger": f'{workspace_id}/triggers/pitch_weapon', 'parameters':[{"name":"place", "value":"California"}]}
  • Step 3: The Goal instruction is then added to the character's prompt, resulting in: instruction: "tell {player} to visit California to get a javelin made with a honeybee's stinger"

In this example, the Instruction field incorporates a parameter that determines the location the player is encouraged to visit.

Additional Parameters for a Goal​

Repeatable
Optional. Goals can be employed once per conversation session. Setting Repeatable to "True" allows for multiple uses of the same Goal.

Enabled_by_Default
Optional. Goals can be disabled at the start of conversation and then enabled later by a Character_Changes Mutation.

YAML Sample Code​

Shown below is an example of a YAML script within a character's Goals:

# intents can be created to help orchestrate character behavior based on when a user says something similar to what is defined
intents:
  # intent name is the resource value that can be used as an activation condition for a goal
  - name: 'quest_request'
    # training phrases should include examples of what an end user could say to trigger the intent
    training_phrases:
      - 'Do you have any quests for me?'
      - 'What quest should I take on next?'
      - 'What quests can I take on here?'
      - 'Are there any quests I can take to help me level up?'
      - 'Give me a quest'

  - name: 'ask_for_weapon'
    training_phrases:
      - 'How can I increase my attack damage?'
      - 'What equipment should I have for the next quest?'
      - 'Where can I get a weapon around here?'
      - 'What items do you have to increase strength?'
      - "What's the best weapon I can get?"

# goals get activated by an activation event and initiate a specific action.
goals:
  - name: 'greeting'
    # activations composed of trigger (client-invoked) or intent
    activation:
      trigger: 'greeting'
    # actions include instruction, say_verbatim, emotion_change, and send_trigger
    actions:
      - say_verbatim: 'Welcome to the Shop of Curiosities and Wonders! Are you new around these parts?'
        character_changes:
          enable_goals:
            - "give_quest"

  - name: 'pitch_weapon'
    activation:
      intent: 'ask_for_weapon'
    actions:
      - instruction: "tell {player} to visit Queen Bee to get a javelin made with a honeybee's stinger"
        character_changes:
          set_emotion: 'JOY'
        send_trigger: 'ask_for_weapon_detected'

  - name: 'give_quest'
    repeatable: True
    enabled_by_default: False
    activation:
      intent: 'quest_request'
      trigger: 'give_quest'
    actions:
      - random:
          - probability: 0.2
            instruction: 'give a quest to retrieve the ancient candy recipes that were stolen by Lord Toffee!'
          - probability: 0.5
            instruction: 'give a quest to rescue the princess from the clutches of the dragon'
          - probability: 0.3
            instruction: 'give a quest to uncover who destroyed Candycane Tower'

Non-Invoke Conversation​

There may be scenarios where you wish to activate a certain Goal without prompting the character to speak immediately, such as when deferring a character's response by one or more conversation turns.

This allows for more natural pacing and smoother interactions, preventing the character from abruptly interrupting the flow of the conversation. For these use-cases, you can employ a Non-Invoke Conversation by using an Array in the Actions field.

When defining actions as an Array, subsequent items within the Array are executed turn-by-turn until fully completed. This means that the character won't immediately act on the next item in the Array until the next player response.

Example of a Non-Invoke Conversation​

Consider a scenario where a character needs to detect a player's intent but also has a set of instructions to give the player.

Instead of delivering everything at once, the character waits for the player to speak, providing the specified instructions upon the player's next interaction.

goals:
  - name: 'acknowledge_and_instruct'
    activation:
      intent: 'player_action'
    actions:
      - send_trigger: 'player_action_detected'
      - instruction: 'tell {player} to meet the elder at the village center for further guidance.'

In the example above, when the intent Player_Action is detected, the first action that the system executes sends a trigger named player_action_detected back.

Then, when the player interacts again, the character executes the instruction: "tell {player} to meet the elder at the village center for further guidance."

Entity Extraction​

Entities are matched against a player's query. Any matches (values) can be injected into the Instruction of a character's Goal, and then returned as a parameter of a custom event, which is sent when the Goal is activated.

Entities are not connected to Intent matching, but instead run in parallel with it wherever intents and entities are predicted from the player's speech.

From there, Intent Matching is used to activate the Goal, and Entity Matching is used to insert into the action's template, returning it back to the client in a custom event if the specified entity is a Goal action.

Types of Entities​

There are two (2) types of entity entries available in the YAML: Map Entries and Regex Entries

1. Map Entries​

These entries specify a set of Synonyms, which are words or phrases that are matchable from the player's speech.

When a matched synonym is detected, the Value (machine-readable ID) associated with it is returned in a parameter of a custom event.

The Display_Name is non-unique human readable description, used in LLMs and other natural language tools.

entities:
- name: "fruit"
  map_entries:
    - value: "apple"
      display_name: "apple"
      synonyms:
        - "green apple"
        - "red apple"
    - value: "orange"
      display_name: "orange"
      synonyms:
        - "orange"
        - "blood orange"

Fuzzy_Match attributes are also available on the MapEntry.

These entries allow for some deviations in the match from a specified entry synonym.

entities:
- name: "fruit"
  map_entries:
    - value: "apple"
      display_name: "apple"
      synonyms:
        - "green apple"
        - "red apple"
      fuzzy_match: True

In the example above, if the player's speech has "I want to eat green apple" where the player mistyped apple, it should still be matched with fuzzy_match=True and it won't be matched without it.

⚠️ Use the fuzzy_match=True attribute at your own risk, as it has the potential to produce false positive matches.

2. Regex Entries​

Regex entities allow you to specify regex templates that extract structured data from user utterances.

In the example below, you can see a contact entity with phone_number and email regex entries. These entities are returned to the client by sending a trigger as part of a goal action.

entities:
  - name: "contact"
    regex_entries:
      - value: "phone_number"
        display_name: "phone_number"  
        template: '(\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4})'
      - value: "email"
        display_name: "email"
        template: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
     
goals:
  - name: entity
    repeatable: true
    activation:
      motivation: "{player} mentions about their contact info"
    actions:
      - instruction: "say they will contact them later at {{p.contact.text}}, making sure to confirm the exact value of the contact information"
        send_trigger: "contact_trigger"
        trigger_params:
          - name: contact
            value: '{{p.contact.text}}'

Both Regex and Map entity entries have an optional description attribute where you can provide the explanation of the entry.

Accessing Numeric Parameters​

To access a numeric parameter values in within a Regex entry, assure you use the .text type identifier to convert the numbers to string text. Refer to the image below for an example:

Regex

Escaped Characters in Regex Entities​

When using Escaped Characters within a Regex entity, use single quotations (') instead of double quotations (").

If double quotations are used instead of single quotations, an Invalid Escape Sequence error occurs.

Escaped Characters include the following:

  • \t inserts a tab
  • \b inserts a backspace
  • \n inserts a new line
  • \r carriage return
  • \f form feed
  • \' inserts a single quote
  • \" inserts a double quote
  • \\ inserts a backslash

Sample Entity Extraction YAML​

# intents can be created to help orchestrate character behavior based on when a user says something similar to what is defined 
intents:
  # intent name is the resource value that can be used as an activation condition for a goal
  - name: "start_race"
    # training phrases should include examples of what an end user could say to trigger the intent
    training_phrases:
      - "lets go racing!"
      - "i want to start a race"
      - "i want to race"

  - name: "confirm_race"
    training_phrases:
      - "yup thats right"
      - "lets do it!"
      - "yes thanks"
      - "confirmed!"
      - "green light!"
      - "2 players on jungle please green light"
      - "lets go with 4 players on the cloud map. green light!"
      - "lets do a 4 player race on the desert map. green light!"
 
entities:
- name: "number_of_players"
  map_entries:
    - value: "1"
      display_name: "1"
      synonyms:
        - "one" 
    - value: "2"
      display_name: "2"
      synonyms:
        - "two"
        - "two of us"
        - "me and my friend" 
    - value: "3"
      display_name: "3"
      synonyms:
        - "three"
    - value: "4"
      display_name: "4"
      synonyms:
        - "four"
- name: "map"
  map_entries:
    - value: "jungle"
      display_name: "jungle"
    - value: "forest"
      display_name: "forest"
    - value: "desert"
      display_name: "desert"
    - value: "clouds"
      display_name: "cloud"

# goals get activated by an activation event and initiate a specific action.
goals:
  - name: "green_light"
    activation:
      trigger: "green_light"
    actions:
      - say_verbatim: "Let's race! Starting a {{p.number_of_players}} player race in the {{p.map}}... 3,2,1 here we go!"
        send_trigger: "race_started"
  - name: "start_race"
    # activations composed of trigger (client-invoked), intent, or motivation
    activation:
      trigger: "start_race"
      intent: "start_race"
    # actions include instruction, say_verbatim, emotion_change, and send_trigger
    actions:
      - instruction: "Always tell {player} to say 'green light!' along with the number of players and the map to start the race"
  - name: "confirm_race"
    activation:
      trigger: "confirm_race"
      intent: "confirm_race"
    actions:
      - send_trigger: "green_light"
        trigger_params:
          - name: "number_of_players"
            value: "{{p.number_of_players}}"
          - name: "map"
            value: "{{p.map}}"
  - name: "bump"
    activation:
      trigger: "bump"
    actions:
      - instruction: "insult {player}'s driving ability with a witty one-liner because they just crashed into your car while racing!"