Dialogue Actors

Full API reference for DialoguePerformerMarkerComponent, ActorDefinition data model, and the performer registration and lookup system.
Categories:
Tags:

Dialogue Actors connect authored character data in the .dialoguedb asset to world-space entities in the level. The system has two halves:

  • ActorDefinition – The data side. Defined in the DialogueDatabase, it holds the actor’s name, portrait, and metadata.
  • DialoguePerformerMarkerComponent – The world side. Attached to an entity in the level, it registers a named performer with the Dialogue Manager so the sequencer can find it at runtime.

When a dialogue sequence references an actor by name, the sequencer looks up the matching performer entity through DialogueManagerRequestBus::GetPerformer(name). This links the authored text, portraits, and performance instructions to a specific entity in the world.

For usage guides and setup examples, see The Basics: GS_Cinematics.

DialoguePerformerMarkerComponent

Dialogue Performer Marker component in the O3DE Inspector

A component placed on any entity that represents a dialogue performer in the level. On Activate(), the marker registers itself with the Dialogue Manager by name. Multiple performers with the same name can exist in different levels, but only one should be active at a time within a single level.

Request Bus: PerformerMarkerRequestBus

Entity-addressed bus – each marker entity responds on its own address.

MethodParametersReturnsDescription
GetPerformerName–AZStd::stringReturns the performer’s registered name. This name must match the actor name in the dialogue database.
GetPosEntity–AZ::EntityIdReturns the entity to use as the performer’s position source. Typically the marker entity itself, but can point to a child entity for offset control.
GetPosPoint–AZ::Vector3Returns the performer’s current world-space position.
ShouldTrackTarget–boolReturns whether the performer entity should continuously track and face its dialogue target during a sequence.

ActorDefinition Data Model

The ActorDefinition is the authored data for a single character, stored inside the DialogueDatabase.

PropertyTypeDescription
TypeId{1A2B3C4D-5E6F-7A8B-9C0D-1E2F3A4B5C6D}
Actor NameAZStd::stringInternal lookup name. Must match the performer marker name in the level.
Display NameAZStd::stringThe name shown to the player in dialogue UI. Can differ from the internal name.
PortraitAsset referenceDefault portrait image. Overridden per-node in TextNodeData when needed.
Emotion CategoriesAZStd::vectorGroupings of emotional states (e.g. happy, angry, sad). Used to organize profile images and poses.
Profile Image SetsAZStd::vectorSets of portrait images keyed by emotion or attitude. The sequencer can switch profiles during dialogue.
Pose SetsAZStd::vectorSets of body poses and idle animations keyed by attitude. Referenced by performance nodes.

Performer Registration and Lookup

Registration Flow

  1. A DialoguePerformerMarkerComponent activates on an entity in the level.
  2. During Activate(), the component calls DialogueManagerRequestBus::RegisterPerformerMarker(name, entityId).
  3. The Dialogue Manager stores the mapping from name to entity ID.
  4. When the component deactivates, it unregisters itself.

Lookup Flow

  1. The sequencer processes a node that references an actor name (e.g. a TextNodeData with speaker “perry” or a PerformanceNodeData targeting “perry”).
  2. The sequencer calls DialogueManagerRequestBus::GetPerformer("perry").
  3. The Dialogue Manager returns the registered entity ID.
  4. The sequencer (or performance) can now query the performer’s position, facing, and tracking state through PerformerMarkerRequestBus.

Multiple Performers

The actorTargetId field on node data allows a sequence to target a specific instance of a performer when multiple entities share the same actor name. This supports scenarios like having the same NPC appear in multiple locations across different levels while keeping the same actor definition in the database.

Setup

  1. In your .dialoguedb asset, define an actor with a unique name (e.g. “perry”) using the Dialogue Editor.
  2. In your level, create an entity and attach a DialoguePerformerMarkerComponent.
  3. Set the marker’s performer name to match the actor name in the database (e.g. “perry”).
  4. Position the entity where the performer should appear in the world.
  5. Optionally, add child entities for position offsets or attach visual representation (mesh, animation) to the same entity.

The marker entity will self-register with the Dialogue Manager on activation. The sequencer can now find this performer when processing sequences that reference the matching actor name.

Script Canvas Examples

Getting a performer’s name and world position:

See Also

Get GS_Cinematics

GS_Cinematics — Explore this gem on the product page and add it to your project.