> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/vision/vision-usage-examples.md).

# Vision usage examples

These examples show practical Blueprint patterns for **Environment Webcam**. Complete [Vision quick start](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/vision/vision-quick-start.md) first if you have not added vision to a character yet.

Each example includes a scenario, the setup to apply, the expected runtime behavior, and how to verify it.

### Auto-start vision on BeginPlay

**Scenario:** A training NPC at a fixed workstation should begin scene capture as soon as the level loads.

**Setup:** Select **Environment Webcam** in the character Blueprint. In the **Details** panel under **Convai | Vision**, enable `bAutoStartVision`. Assign **Convai Render Target** before entering Play mode.

**Expected behavior:** During `BeginPlay`, the component calls **Start**. When **Convai Render Target** is assigned, **Get State** returns `Capturing` and the chatbot can send frames during an active session.

**Verify:** Call **Supports Vision** on the chatbot and **Get State** on **Environment Webcam**. Both should report an active vision source in `Capturing` state.

### Manual start and stop

**Scenario:** A medical training simulation should use vision only during a procedure phase.

**Setup:**

1. On your procedure-start event, get a reference to **Environment Webcam** and call **Start**.
2. On your procedure-end event, call **Stop** on the same component.
3. Before calling **Start**, check **Get State** to avoid double-starts if the event can fire more than once.

**Expected behavior:** The component captures frames only during the active procedure phase. **Get State** returns `Capturing` after **Start** and `Stopped` after **Stop**.

**Verify:** Ask the character about a visible object only while the procedure is active. Outside that phase, responses should not reference scene content.

### Limiting capture FPS to reduce bandwidth

**Scenario:** A corporate onboarding simulation runs on a constrained network. Lower capture rate is acceptable.

**Setup:** In the **Details** panel, set **Maximum FPS** (`m_MaxFPS`) to `5`. Alternatively, call **Set Max FPS** with value `5` from a Blueprint initialization function.

**Expected behavior:** The chatbot reads `GetMaxFPS()` and throttles frame upload to approximately one frame every `0.2` seconds.

**Verify:** Compare response latency before and after the change. The **Output Log** should continue to show `SendImage: Sending raw image` at the reduced cadence.

### Checking whether a vision component is registered

**Scenario:** A UI indicator should show whether the chatbot has a valid frame source.

**Setup:** In the Event Graph or a widget tick function, call **Supports Vision** on `UConvaiChatbotComponent`. Use the boolean return value to drive the indicator.

**Expected behavior:** **Supports Vision** returns `true` when a component implementing `UConvaiVisionInterface` is registered or discoverable on the chatbot `Actor`.

**Verify:** Also call **Get State** on **Environment Webcam**. Registration alone is not enough for upload; the source must be in `Capturing` state.

### Triggering logic after capture starts

**Scenario:** A character should run setup logic only after **Environment Webcam** enters `Capturing`.

**Setup:** Bind **On Frame Ready** on **Environment Webcam** to a custom event. Use a boolean flag so the logic runs once.

```
// Blueprint pseudocode
bool bSetupComplete = false

OnFrameReady →
  if NOT bSetupComplete:
    bSetupComplete = true
    → trigger setup logic
```

**Expected behavior:** The setup logic runs once on the first tick that **On Frame Ready** fires while the component is capturing.

**Verify:** Confirm **Get State** returns `Capturing` before the custom logic runs.

### Switching the vision component at runtime

**Scenario:** Two characters in the same level each have their own **Environment Webcam**. When control switches to a different character, the active chatbot should use that character's frame source.

**Setup:** On the switch event:

1. Get the target chatbot's `UConvaiChatbotComponent` reference.
2. Get the desired **Environment Webcam** component reference on that character.
3. Call **Set Vision Component** on the chatbot and pass the webcam component.

**Expected behavior:** **Set Vision Component** returns `true` and replaces the previously registered source. The chatbot forwards frames from the new component on the next upload tick.

**Verify:** Call **Supports Vision** on the target chatbot and **Get State** on the new webcam. Ask about an object visible only to the new source.

### Next steps

{% content-ref url="/pages/8W9Lmm4Mqew1zEfyrsje" %}
[Vision Blueprint reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/vision/vision-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/P6Q0IslTrewgSnb1grWo" %}
[Troubleshoot vision](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/vision/troubleshoot-vision.md)
{% endcontent-ref %}

{% content-ref url="/pages/1zs9olIHfeqwXONkvpVT" %}
[Vision frame sources](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/vision/vision-frame-sources.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/vision/vision-usage-examples.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.