Spatial awareness quick start

Turn on spatial awareness, tune the distance bands for your level's scale, and confirm what a character actually receives.

This guide turns on spatial awareness for your project, tunes the distance bands to match your level's scale, and confirms — with the Convai Debug Overlay — that a chatbot actually receives the sentences the system generates.

Prerequisites

• The Convai Unreal Engine plugin is installed.
• At least one UConvaiChatbotComponent is placed in the level.
• At least one other Actor in the level has a UConvaiObjectComponent, so there is something for the chatbot to be told about.

Confirm the master switch is on

1

Open Project Settings

Go to Edit > Project Settings > Plugins > Convai and expand the Spatial Awareness category.

2

Confirm Enable Spatial Awareness is checked

Enable Spatial Awareness (bEnableSpatialAwareness) defaults to checked. If it is unchecked, no proximity, line-of-sight, or relation facts are generated for any chatbot in the project — check it now.

Tune the distance bands for your level's scale

Spatial awareness buckets every subject a chatbot can perceive into "close by," "some distance away," or "far away" using two thresholds, both in centimeters. The defaults assume a human-scale level; a much larger or smaller level needs different values.

1

Set Nearby Distance

Nearby Distance (NearbyDistance, default 1000.0 cm) is the ceiling under which a subject reads as "close by." Set it to roughly the range at which a character in your level should treat something as within arm's reach or a few steps away.

2

Set Moderate Distance

Moderate Distance (ModerateDistance, default 4000.0 cm) is the ceiling under which a subject reads as "some distance away." Beyond it, a subject reads "far away." Keep ModerateDistance larger than NearbyDistance — the system does not enforce the ordering for you.

Both distances have the edit condition bEnableSpatialAwareness, so they are greyed out until the master switch is on.

Confirm the chatbot is set to receive surroundings

The project settings above decide what the spatial system computes; each chatbot's own preferences decide what it actually receives.

1

Select the chatbot's Convai Chatbot component

In the character Blueprint or level Actor, select the UConvaiChatbotComponent.

2

Confirm Receive Surroundings is on

Expand Convai | Spatial Awareness (Advanced Display) and confirm bReceiveSurroundings is checked. It defaults to true. If it is off, this chatbot never receives surroundings facts regardless of the project settings above.

Verify what the character receives

Enter Play mode, open the Convai Debug Overlay with Ctrl+Alt+K, and select the chatbot.

Check the SURROUNDINGS panel for the object with the UConvaiObjectComponent from your prerequisites. Its row shows the verbatim sentence the chatbot receives — for example, "the crate is close by, in front of you." This is the exact text delivered to Convai, not a summary, so it is the fastest way to confirm your distance-band tuning produced the phrasing you expect.

If the row shows the object at the wrong band, adjust NearbyDistance or ModerateDistance and re-enter Play mode to see the change reflected immediately.

For every panel, glyph, and label the overlay shows, see Convai Debug Overlay reference.

Next steps

How spatial awareness worksSpatial awareness settings referenceTroubleshoot spatial awareness