Skip to main content

Goals

The Goals section enables you to set specific triggers, prompting your character to respond in a certain way during particular scenarios or interactions. This section contains several elements that can be customized to your needs.

Auto-migration from Goal 1.0 to 2.0

Great news! We've made significant progress on our auto-migration feature. It facilitates the seamless and automatic conversion of your Goals 1.0 settings into YAML for Goals 2.0. We're diligently testing this tool to ensure its efficiency and accuracy. We value your patience and look forward to making this transition as smooth as possible for you. For more details, please check out our migration records. If you have questions, concerns, or feedback, feel free to email us at support@inworld.ai.

Goals 2.0​

Introduction​

Our Goals 2.0 system includes several new powerful features, including the ability to leverage contextual intents as activation conditions, passing realtime information from a client to a character via parameters, and controlling when a character should deliver a pre-scripted line verbatim. All of these features can be defined in a flexible code editor in YAML syntax.

YAML Syntax​

YAML is a human-friendly data serialization language often used for configuration files and data exchange between languages with different data structures. YAML structures data in a format that both humans and machines can understand.

When using YAML syntax, remember that indentation matters - it's used to denote structure. Also, sequences (like arrays or lists) are denoted by a hyphen (-), and key-value pairs are separated by a colon (:).

Here is a basic structure of a YAML file:

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

To learn more about YAML, check out the YAML project.

Concept Definitions​

In the “Goals 2.0” feature, there are three key elements: goal, activation, and action.

Goalrequired

The goal operates as a 'consequence mechanism' which gets activated by an activation event and initiates a specific action. It allows developers to have better control of characters in runtime.

In addition to facilitating character interactions, the goal system monitors the achievement of goals, issuing a distinct signal to the client upon a goal's completion.

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 - perhaps 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.

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

The event that triggers the goal. It is made up of two components: intent and trigger.

⚠️ The activation must include at least one intent or trigger.

  • intentoptional

    This utilizes our real-time intent detection engine, which scans the player's conversation to identify intents 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. You can also have multiple intents triggering the same goal

Note: Developers can only leverage the intent feature within the Goals & Actions tool to establish an intent detection system.

  • triggeroptional

    This is a user-specified parameter sent to our server 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'
Actionrequired

This consists of a set of responses that will happen after an activation condition has been met.

Action types include control over character dialogue via instruction and say_verbatim, and client/server communication via send_trigger and leveraging parameters within dialogue actions.
Note: For character state changes, see Character Mutations.

⚠️ The action cannot include both instruction and say_verbatim at the same time.

Spoken Actions

  • instructionoptional

    This field is used to provide specific guidance on how your character should respond after a goal has been activated. Your character will follow the instruction while still maintaining their own unique personality.

    Tip: Write your instruction with a direct command (that starts with a verb) for optimal performance. Phrase them as if you were giving a direct command to an actor!

  • say_verbatimoptional

    This is a text string that characters will recite exactly as written.

Giving actions instruction and emotion_change:

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

Giving actions say_verbatim:

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

Client/Server Communication

  • send_triggeroptional

    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 our intent detection system to receive a signal when a custom intent is detected.

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"
      emotion_change: "JOY"
      send_trigger: "ask_for_weapon_detected"

Randomize Actions

  • randomoptional

    This feature assigns a probability (a number between 0 and 1) to an action item (such as instruction, say_verbatim, or emotion_change). When a goal is activated, the action item is executed based on this probability.

In this 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 emotion_change must all be nested under random with assigned probabilities.

Giving actions 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 changing action in runtime​

Write your say_verbatim and instruction with parameters that can be used to inject realtime information from the client (delivered through the trigger) to an action at runtime.

For example:

  • Step 1: Write the goal as: 
    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"
            emotion_change: 'JOY'
            send_trigger: 'ask_for_weapon_detected'
  • Step 2: Developers send a request message that includes the trigger. E.g., 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 instance, the instruction field incorporates a parameter that determines the location the player is encouraged to visit.

Additional Parameters for goal

  • repeatableoptional

    Default: False. Goals can be employed once per conversation session. Setting repeatable to True allows for multiple uses of the same goal.

YAML Sample Code​

Here is an example of how to use YAML with the “Goals 2.0”:

# 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?'

  - 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"
        emotion_change: 'JOY'
        send_trigger: 'ask_for_weapon_detected'

  - name: 'give_quest'
    repeatable: True
    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 might be scenarios where you want to activate a certain goal without prompting the character to speak immediately - maybe defer a character's response by one or more conversation turns. This allows for more natural pacing and smoother interactions, preventing the character from interrupting the flow of the conversation abruptly. 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 array items will be 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.

Here's an example: 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, and then provides the instructions upon the next player's 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 this setup:

  • When the intent "player_action" is detected, the first action the system will execute is sending a trigger named "player_action_detected" back to the developer.

  • Next, when the player interacts again, the character will execute 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 and their matches (values) can be injected into the instruction of the goal and returned as a parameter of a custom event sent when goal is activated. Entities are not really connected to intent matching at the moment but instead run in parallel with it where 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 and return it back to the client in a custom event, if the specified entity is a goal action.

There are two types of entity entries available in the YAML now:

  1. Map entities are where you specify a set of “synonyms” (words/phrases) that are matchable from the player’s speech. If there is a matched synonym found, we return the “value” associated with it in a parameter of a custom event
entities:
- name: "fruit"
  map_entries:
    - value: "apple"
      display_name: "apple"
      synonyms:
        - "green apple"
        - "red apple"
    - value: "orange"
      display_name: "orange"
      synonyms:
        - "orange"
        - "blood orange"

There is also a fuzzy_match attribute that is available on the MapEntry. It allows 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

If the player's speech has "I want to eat green aple" where the player mistyped apple, that 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. It has the potential to produce false positive matches.

  1. Regex entries are where you can specify Regex templates to use structured match:
entities:
- name: "phone"
  regex_entries:
    - value: "us_phone"
      display_name: "US phone"
      template: "^\([0-9]{3}\)[0-9]{3}-[0-9]{4}$"
    - value: "fr_phone"
      display_name: "French phone"
      template: "^(?:(?:(?:\+|00)33[ ]?(?:\(0\)[ ]?)?)|0){1}[1-9]{1}([ .-]?)(?:\d{2}\1?){3}\d{2}$"

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

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!"