Entities

An Entity can be either a concept or a collection of objects related to the game world that are used within the context of a character's goals to define key parameters of a goal, such as a color, fruit, or name. This guide covers what entities are and how to use them within a character's goals.

Technical Details

Entities are defined at the workspace-level and work similarly to programming language Variable Types.

Each entity contains both (1) a type declaration, and (2) a reference to the list of values. Type declaration is the same for all entity types, while reference data source may vary between types.

Entity Basics

The Entities system populates named entities from game state and player inputs to provide contextual responses and structured data. This system classifies objects in the game world, storing data accessible to all characters in a scene.

Entities can include various types such as Items, Regex, and Dictionary.

Uses of Entities

Entities are primarily used for Entity Extraction in conjunction with Dictionary or Regex Matching Rules.

Anatomy of an Entity

An entity contains the following information:

• Name: Required Identifier for the entity in workspace that is used as a part of API-resource name.

• Display Name: Required Human-readable name, Used in prompts and text replies for LLMs and other natural language tools.

• Description: Optional Describes entities.

• Matching Rules: Optional Design-time definition of how to get an entity match. There are 2 possible rules: dictionary_rules or regex_rules.

  • Dictionary Rules: Optional There is a display name and a list of synonyms defined at design time. There is a grammar matcher that will allow to detect those.

  • Regex Rules: Optional Entities allow you to specify regex templates that extract structured data from user utterances.

Resource Name

The Resource Name for entities must follow one of the two following formats:

1. Full Resource Name: workspaces/<workspaceName>/entities/<entityName>

2. Short Name: <entityName>

Entity Lifecycle

When game session starts, the list of entities from Design Time is stored in the session state.

This means any new changes to entities made within Studio are only be available for new sessions with no previous state.

Creating Entities in Inworld Studio

To use Entities within Inworld Studio, perform the steps below.

1. Open Variables

Using the left panel, open the Variables tab.

2. Define Entities

Next, click the Edit button within the Entities interface.

Use this interface to enter any actionable objects you want the characters to interact with.

Once you have entered any entities you need, press the Save button in the top-right.

Example Entities

The examples below show a number of entities formatted in the correct way.

Use this as a reference when crafting your own entities.

entities:
  - name: fruits
    display_name: Fruits
    description: Collection of various fruits
  - name: magical_potion
    display_name: Magical Potions
    description: Collection of various magical potions
  - name: number
    display_name: phone number
    description: Character's phone number
    regex_rules:
      - regex_pattern: "{0-9}"
        name: phone_number
  - name: street_address
    display_name: Street Address
    description: Street address of characters' homes, where they eat, sleep, and
      hang out with family and friends.
    dictionary_rules:
      - display_name: 101 Pine Lane
        synonyms:
          - my home
          - that blue house
        use_fuzzy_matching: false
        name: pine_lane
      - display_name: 500 Walnut Way
        synonyms:
          - grandma's place
          - white house down the road
        use_fuzzy_matching: false
        name: walnut_way

Creating Entity Items During Runtime

An entity item is an in-game instance of an entity.

Entity Item Anatomy

An entity item contains:

• ID: Required Unique identifier used for an entity item during a game session.

• Display Name: Required The entity item's human-readable name.

• Description: Required Describes the entity item.

• Properties: Optional Properties for the given item(format is map<string, string>).

• Entities: Optional The list of entities that current item belongs to.

Managing Entity Items

To add, update, or remove entity items during an active game session, the game client sends from the client to the server to perform an item-related operation.

All related operations are grouped under the packet ItemsOperationEvent.

Each operation is confirmed with an OperationStatusEvent, sent from the server to the client. Once the operation packet is sent, the client may assume that it is "done" and send follow-up packets to the server; the client does not need to wait for operation confirmation.

For example, if the client sends CreateItemsOperation and then immediately sends ItemsInEntitiesOperation with the same entity IDs, the second operation will be successful without waiting for the first operation confirmation.

Entity Item Examples

The section below provides examples of entity items in use.

Create Entity

When the game client wants to add new entity item, it sends the CreateOrUpdateItemsOperation in event ItemsOperationEvent.

{
  "entitiesItemsOperation": {
    "createOrUpdateItems": {
      "items": [
        {
          "id": "mosquito_1a20b102-d208-4c00-bbc0-c66527e1189d",
          "displayName": "mosquito",
          "description": "Big mosquito"
        }
      ],
      "addToEntities": [
        "workspaces/{workspace-id}/entities/enemy"
      ]
    }
  }
}

The item's ID (mosquito_1a20b102-d208-4c00-bbc0-c66527e1189d in the above example) is generated by the game client to identify the item during the game session.

Confirm Packet

The example below shows the confirmation as the system receives the packet.

{
  "result": {
...
    "operationStatus": {
      "status": {
        "code": 0,
        "message": "Success",
        "details": []
      }
    }
  }
}

Remove Entity

During the game, when you need to remove entity item(s) from session, the game client should send ItemsOperationEvent event with RemoveItemsOperation and follow request payload.

{
...
  "entitiesItemsOperation": {
    "removeItems": {
      "itemIds": [
        "mosquito_1a20b102-d208-4c00-bbc0-c66527e1189d"
      ]
    }
  }
}

Modify Entity

If during the game need to modify entity item's entities then need to send ItemsOperationEvent event with ItemsInEntitiesOperation, see the example below.

{
...
  "entitiesItemsOperation": {
    "itemsInEntities": {
      "itemIds": [
        "mosquito_1a20b102-d208-4c00-bbc0-c66527e1189d"
      ],
      "entityNames": [
        "workspaces/{workspace-id}/entities/unknown-enemy"
      ],
      "type": 1
    }
  }
}

Supported Operations

The following itemsInEntities operations are supported:

• ADD = 1: Add entity(s) to entity item.

• REMOVE = 2: Remove entity(s) from entity item.

• REPLACE = 3: Replace existing entity(s) with provided.

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: Dictionary Rules and Regex Rules.

1. Dictionary Rules

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.

Dictionary Rules entity entry have an optional description attribute where you can provide the explanation of the entry.

entities:
  - name: street_address
    display_name: Street Address
    description: Street address of characters' homes, where they eat, sleep, and hang out with family and friends.
    dictionary_rules:
      - display_name: 101 Pine Lane
        synonyms:
          - my home
          - that blue house
        use_fuzzy_matching: false
        name: pine_lane
      - display_name: 500 Walnut Way
        synonyms:
          - grandma's place
          - white house down the road
        use_fuzzy_matching: false
        name: walnut_way

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

entities:
  - name: fruit
    display_name: Fruits
    description: Collection of various fruits
    dictionary_rules:
      - display_name: apple
        synonyms:
          - green apple
          - red apple
        use_fuzzy_matching: true
        name: apple

In the example above, if the player's speech has "I want to eat a green aple" where the player mistyped apple, it should still be matched with use_fuzzy_matching: true and it won't be matched without it.

warning

Use the *use_fuzzy_matching: true attribute at your own risk, as it has the potential to produce false positive matches.

2. Regex Rules

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.

The following example illustrates the process of creating an entity using Regex Rules and demonstrates how to integrate it into your goals.

entities:
  - name: contact
    display_name: Contact information
    description: Contact information of the player
    regex_rules:
      - regex_pattern: (\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4})
        name: phone_number
      - regex_pattern: "[a-zA-Z0-9._%-]@[a-zA-Z0-9.-]\\.[a-zA-Z]{2,}"
        name: email

goals:
  - name: entity
    repeatable: true
    extracted_entities:
      - name: contact
    activation_condition:
      logical_expression: "c.contact.value is defined and c.contact.value!=''"
    on_activation:
        say_instruction: "say they will contact them later at {{c.contact.text}}, making sure to confirm the exact value of the contact information"
        send_trigger: "contact_trigger"
        trigger_params:
          - name: player_contact
            value: '{{c.contact.value}}'

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:

Create an entity:

entities:
  - name: player_balance
    display_name: Player Balance
    description: The amount of currency or coins a player has in their inventory
    regex_rules:
      - regex_pattern: (\$?[0-9]+|[0-9]+\$?|[0-9]+ dollars?)
        name: currency_amount

Use the entity in your goals:

goals:
- name: "balance_check"
  activation_condition:
    detect: "{{player}} chats about their balance"
    logical_expression: "c.player_balance.value=='currency_amount'"
  on_activation:
    say_instruction: "Tell {{player}} their balance is {{c.player_balance.text}}"

Escaped Characters in Regex Entities

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