Unreal plugin

Blueprint API

Everything is exposed to Blueprint — no C++ required.

The IAMX character component surfaces its entire runtime surface as Blueprint-callable nodes and bindable events. If you can drag a wire, you can build a fully conversational character: connect it to the cloud brain, open the mic, feed it context, let it call your gameplay logic, and react to everything it says and hears. Every node below lives on the IAMX Component you add to your Actor — no engine source edits, no C++ module, no build step.

Every action node has a matching event. Call a node to make something happen; bind an event to know when it happened. The two halves of this page mirror each other — start with the tables, then wire the events at the bottom.

The reference below is grouped by area. Node names are written exactly as they appear in the Blueprint node search — type the name into the graph's right-click menu and it will surface on any Actor carrying an IAMX Component. For the C++-facing view of the same surface, and for the panel-driven config that feeds these nodes, see /docs/quickstart and /docs/install.

Session & mic

These nodes control the two independent channels every character has: the conversation session (the link to the cloud brain that thinks and speaks) and the microphone (the audio input that lets a player talk to it). They are deliberately separate — you can hold a live session open while the mic stays closed, and you can open the mic without a session for pure transcription. Interrupt sits between them, cutting speech the instant new input arrives.

Node	What it does	Typical trigger
`Start Conversation`	Connects the character to the cloud brain and begins a live session. Loads the active personality, memory and context, and readies speech output.	Player enters trigger volume, presses "Talk", or level starts
`End Conversation`	Disconnects the session cleanly, flushes memory, and returns the character to idle. Safe to call even if no session is open.	Player walks away, dialogue ends, or level unloads
`Start Listening`	Opens the microphone and begins capturing player speech. Voice is transcribed and routed into the open session automatically.	Push-to-talk key down, or auto after the character finishes speaking
`Stop Listening`	Closes the microphone and finalizes any in-flight transcription. The last utterance is submitted as the player's turn.	Push-to-talk key up, silence timeout, or manual cutoff
`Interrupt Speech`	Cuts the character off mid-sentence — stops audio playback and halts the pending response instantly so a new turn can begin.	Player starts talking over the character (barge-in), or urgent gameplay event

You do not have to manage the mic yourself in voice-activated or push-to-talk interaction modes — the component opens and closes it for you. Reach for Start Listening / Stop Listening when you want frame-perfect control, e.g. binding the mic to a held button or a proximity gesture.

A minimal voice loop

Event BeginPlay
    └─► Start Conversation

InputAction Talk (Pressed)
    └─► Start Listening

InputAction Talk (Released)
    └─► Stop Listening        // player's turn is submitted here

Event EndPlay
    └─► End Conversation

Input & state

Voice is optional. Send Text Input feeds a turn to the character as if the player had spoken it — perfect for on-screen chat boxes, scripted lines, quest triggers, or accessibility. The state queries let your Blueprint branch on exactly what the character is doing right now, so you can drive UI, animation and gameplay in lock-step with the conversation.

Node	Returns	Use it to
`Send Text Input`	—	Submit a text turn instead of voice. Drives the exact same pipeline as a spoken sentence — the character thinks, speaks and animates in response.
`Is In Conversation`	`bool`	Check whether a session is currently open. Gate UI, camera framing, or "press to talk" prompts on this.
`Is Speaking`	`bool`	Check whether the character is producing audio right now. Show a talking indicator, duck ambient audio, or suppress the mic.
`Is Listening`	`bool`	Check whether the mic is open and capturing. Drive a live "listening…" UI ring or waveform.
`Is Processing`	`bool`	Check whether a turn is being thought through (between input received and speech starting). Show a thinking spinner.

The four state queries are cheap and safe to poll every frame on Event Tick, but the matching events (see below) are almost always the cleaner choice — bind once, react on the edge, and skip the per-frame branch entirely.

Text-driven chat without a mic

OnTextCommitted (your chat box)
    └─► Branch (Is In Conversation?)
            True  ─► Send Text Input  [ Text = committed string ]
            False ─► Start Conversation ─► Send Text Input

Personality & context

A character is more than a voice — it has a mood and a live picture of the world it lives in. These nodes let you shape that at runtime without editing the base personality. Set Context Fact is the workhorse: inject a fact ("the store closes at 6pm", "the player is holding a red keycard", "today's special is the ramen") and the character will weave it naturally into what it says. Update Character and Load From Panel API hot-swap the entire configuration on the fly.

Node	What it does	Example
`Set Mood`	Shifts the character's tone and disposition for the rest of the session — cheerful, terse, formal, anxious, and so on.	Boss becomes hostile after the player picks the wrong dialogue branch
`Set Context Fact`	Injects a single runtime fact into the character's working knowledge. Facts persist for the session and influence every subsequent turn.	`Set Context Fact("store_hours", "We're open until 6pm today")`
`Update Character`	Hot-reloads the character's full configuration — personality, voice, actions, appearance mapping — without ending the session.	Swap a greeter into a support specialist mid-visit
`Load From Panel API`	Pulls the latest character config live from the IAMX panel and applies it. Lets operators tune a live character from the dashboard at iamx.live with no redeploy.	Marketing updates today's promo copy in the panel; the kiosk reflects it seconds later

Context facts are additive and stay in scope until the session ends or you overwrite the same key. Re-using a key replaces the previous value; a fresh key adds to the pile. Keep keys stable and human-readable so you can overwrite them cleanly — set Context Fact("queue_length", …) beats a new random key every frame.

The panel is the source of truth

Anything you can set with Set Mood, Set Context Fact or Update Character can also be authored in the panel and pulled with Load From Panel API. The recommended pattern is: author the stable personality and actions in the panel, then use the Blueprint nodes only for facts that are genuinely runtime — inventory, time of day, live gameplay state. See /docs/quickstart for the panel-first workflow.

Actions & scene

This is where the character stops being a talking head and starts affecting your game. Actions are gameplay functions you expose to the AI — it decides, in natural conversation, when to call them, and your Blueprint runs the result. Scene registration gives the character awareness of what is physically around it, so it can look at, talk about, and reason over the objects and actors in the level.

AI-callable actions

Node	What it does
`Register Action`	Defines an action the AI is allowed to call — a name, a description the model reads, and typed parameters. When the character decides to use it, you receive `On Action Triggered` with the arguments filled in.
`Unregister Action`	Removes a previously registered action so the AI can no longer call it. Use it to gate abilities behind game state (e.g. only allow `open_door` once the player has the key).

Event BeginPlay
    └─► Register Action
          Name        = "give_item"
          Description  = "Hand the player an item from the shop shelf"
          Parameters   = [ item_name : string, quantity : int ]

// later, when the character decides to act:
On Action Triggered  (Name = "give_item", Args = { item_name:"potion", quantity:2 })
    └─► your Blueprint spawns the item, plays a sound, updates inventory

Scene awareness

Node	What it does
`Register Scene Object`	Tells the character about a point of interest — a label, a description and a world location. The character can reference it, gesture toward it and reason about it.
`Register Scene Actor`	Binds awareness to a live Actor in the level so its position updates as it moves. Ideal for NPCs, props the player carries, or moving vehicles.
`Set Attention Object`	Directs the character's focus (gaze and orientation) to a registered object or actor, so it naturally looks at what it is talking about.
`Play Gesture`	Triggers a named body gesture — wave, point, nod, shrug — layered over the character's current animation.

Scene objects power both perception and framing. Once registered, an object can surface through On Perceived Object when it becomes relevant, and Set Attention Object will steer the character's look-at toward it. Register the handful of things that matter for the scene — you don't need to register the whole level.

Emotion

The character runs a continuous emotional model that drives facial performance and vocal delivery automatically. Most of the time you leave it alone. When you want authored control — a scripted beat, a cutscene, a designer override — these nodes let you force, reset and read the emotional state directly.

Node	What it does
`Force Set Emotion`	Overrides the character's emotional state to a specific emotion at a chosen intensity, and holds it there until you reset. Use for scripted dramatic beats.
`Reset Emotion`	Releases the override and hands control back to the automatic emotional model, blending smoothly from the current expression.
`Get Emotion Score`	Returns the current intensity of a named emotion as a normalized value. Drive VFX, music, lighting or gameplay off the character's real-time feeling.

// Cutscene: force fear, then release control back to the AI
Sequence
  ├─► Force Set Emotion (Emotion = "fear", Intensity = 0.9)
  │      └─► (play scripted line)
  └─► Delay 3.0 ─► Reset Emotion

// Gameplay: swell the music when the character is genuinely happy
Event Tick
  └─► Get Emotion Score ("joy") ─► Set Music Intensity

Pair Get Emotion Score with the On Emotion State Changed event: poll the score for continuous values (a dial, a shader parameter) and bind the event for discrete reactions (a state transition, a line of UI).

Podcast & multi-NPC

IAMX characters can talk to each other, not just to a player. The podcast and NPC-conversation nodes orchestrate autonomous dialogue between two or more characters — a hosted show, a debate, ambient banter between shopkeepers — while the player watches or chimes in. Inject Audience Comment lets a player (or your gameplay) drop a line into the room that the speakers will react to naturally.

Node	What it does
`Start Podcast`	Begins a structured, ongoing exchange between the participating characters around a topic — turns are taken automatically, each character in its own voice and personality.
`Stop Podcast`	Ends the exchange gracefully, letting the current speaker finish before the characters return to idle.
`Start Npc Conversation`	Kicks off a direct back-and-forth between two characters — a scripted or emergent scene where they respond to each other rather than to a player.
`Stop Npc Conversation`	Ends the character-to-character exchange and releases both participants.
`Inject Audience Comment`	Drops a comment into an active podcast or NPC conversation as if from the audience. The speakers acknowledge and respond to it in-character.

Event StartShow
    └─► Start Podcast
          Participants = [ HostCharacter, GuestCharacter ]
          Topic        = "The future of city transit"

OnChatMessageFromViewer
    └─► Inject Audience Comment  [ Text = viewer message ]

Event EndShow
    └─► Stop Podcast

Every character in a podcast is a full IAMX character with its own emotion model, gestures and voice — so all the events below fire per-character. Bind On Sentence Spoken on each participant to drive captions or a "now speaking" indicator.

Events you can bind

The other half of the API. Every event here is a red-node delegate you can bind in the graph (or assign at runtime). They fire on the exact frame the described thing happens, carrying the relevant payload. Bind the ones you need and let the character drive your UI, animation, audio and gameplay reactively — no polling required.

Session & speech lifecycle

Event	Fires when	Payload
`On Conversation Started`	A session opens and the character is ready to talk.	—
`On Conversation Ended`	A session closes, for any reason.	—
`On Speaking Started`	The character begins producing audio for a response.	—
`On Speaking Stopped`	The character finishes speaking (or is interrupted).	—
`On Listening Started`	The microphone opens and capture begins.	—
`On Listening Stopped`	The microphone closes and capture ends.	—

Turn & transcript

Event	Fires when	Payload
`On Response Ready`	A full response has been produced and is about to be spoken.	Full response text
`On Sentence Spoken`	Each individual sentence begins playing — ideal for streaming captions in time with the voice.	Sentence text
`On Player Speech Transcribed`	The player's spoken turn has been transcribed to text.	Transcribed player text

On Sentence Spoken is the caption event — it fires sentence-by-sentence, synced to audio, so subtitles land exactly as each line is heard. Use On Response Ready when you want the whole reply up front (e.g. logging or a chat transcript panel).

Actions

Event	Fires when	Payload
`On Action Triggered`	The AI decides to call one of your registered actions. This is where your gameplay logic runs.	Action name + typed arguments
`On Action Received`	An action call has been received from the brain and acknowledged — fires alongside/ahead of the trigger for routing and logging.	Action name + raw arguments

Emotion

Event	Fires when	Payload
`On Emotion State Changed`	The character's dominant emotion changes.	New emotion + intensity

Perception, presence & identity

Event	Fires when	Payload	Tier
`On Person Detected`	A real person is recognized in front of the character.	Person identifier	Paid — face recognition
`On Person Gone`	A previously detected person is no longer present.	Person identifier	Paid — face recognition
`On Identity Verified`	A person's identity is confirmed through the secure verification flow.	Verified identity result	Enterprise
`On Perceived Object`	A registered scene object or actor becomes relevant to the character's awareness.	Object reference / label	—
`On Attention Changed`	The character shifts its focus to a different object or actor.	New attention target	—

On Person Detected, On Person Gone and On Identity Verified depend on presence and identity features that are gated by plan. They compile and bind on every project, but only fire when the corresponding capability is enabled for your account. Everything else on this page works on every tier.

Putting the events together

On Conversation Started      ─► show HUD, frame camera on character
On Listening Started         ─► show live "listening" ring
On Player Speech Transcribed ─► append player line to chat log
On Response Ready            ─► append character line to chat log
On Sentence Spoken           ─► drive synced subtitles
On Speaking Stopped          ─► auto Start Listening (hands-free loop)
On Emotion State Changed     ─► swap music stem / lighting mood
On Action Triggered          ─► run gameplay (give item, open door, …)
On Conversation Ended        ─► hide HUD, return character to idle

Where to go next

Quickstart

Wire your first character end-to-end in a fresh level. See /docs/quickstart.

Install

Add the plugin, connect the panel, and pick an interaction mode at /docs/install.

Live demo & panel

Try a character and author config in the dashboard at iamx.live.

Building something with these nodes? Share it on the forum, read deeper walkthroughs on the blog, or grab the latest build from GitHub releases. The full plugin source lives at github.com/iamxlive/iamx-unreal-plugin.