Consequence includes a runtime subtitle UI system that can be used as provided or customized for your project's own visual style and gameplay requirements.
The system is built around two main widget classes:
ConsequenceSubtitleWidget
The parent widget that manages active subtitle lines, dialogue choices, subtitle settings, and communication with the Consequence System.
ConsequenceSubtitleLineWidget
A child widget representing an individual displayed subtitle line.
Both classes are Blueprintable, allowing projects to customize their appearance and behavior without modifying the Consequence plugin.
Subtitle behavior is configured in:
Project Settings → Plugins → Consequence Runtime Settings
The main settings are:
Auto Create Consequence Subtitle Widget
When enabled, Consequence automatically creates the configured Subtitle Widget when a new game world starts and adds it to the viewport.
Subtitle Widget Class
Specifies which ConsequenceSubtitleWidget Blueprint class Consequence should create.
This can be the supplied Consequence widget Blueprint or your own Blueprint child class.
Print Debug String Subtitles
Displays simple debug subtitles without relying on the normal subtitle widget. This can be useful while initially integrating or debugging dialogue.
See Engine Settings for more information.
To customize your project's subtitle UI, create a Widget Blueprint inheriting from:
ConsequenceSubtitleWidget
Your layout can contain the visual hierarchy appropriate for your project, but the parent Consequence widget needs references to:
ConsequenceSubtitleLineWidget instancesDuring construction of your Blueprint, call:
Initialize Subtitle Widget
and supply those references.
The parent Consequence Subtitle Widget then manages those widgets as dialogue starts, changes, and ends.
Set your new Widget Blueprint as the Subtitle Widget Class in Consequence Runtime Settings.
If Auto Create Consequence Subtitle Widget is enabled, Consequence will create it automatically at runtime.
Each displayed subtitle Line is represented by a Widget Blueprint inheriting from:
ConsequenceSubtitleLineWidget
Inside the Widget Blueprint, create the visual elements you want to use for the subtitle.
During construction, call:
Initialize Subtitle Line
and provide references to the widgets used for:
Optional indicator widgets can be styled however your project requires.
The parent Consequence Subtitle Widget initializes each Line Widget and supplies its current subtitle data when that slot is needed.
Each displayed subtitle receives a Consequence Subtitle Data structure containing runtime information about the Line.
This includes:
This gives custom subtitle Blueprints access to both the authored dialogue data and the gameplay context in which it is being displayed.
When a Line Widget receives new subtitle data, Consequence calls:
Set Line Data
The widget's display can then be refreshed through:
Update Line Display
The default update process handles subtitle visibility and distance attenuation, text and closed-caption processing, speaker names, Scratch VO and Radio indicators, subtitle tiers, and directional VO presentation.
Override Update Line Display if your project needs additional presentation behavior.
If you override the function, preserve any parent behavior that your implementation still relies upon.
The parent Subtitle Widget exposes several Blueprint-overridable stages for preparing displayed subtitle text.
Perform Gender Parsing resolves Unreal gender-aware text using runtime values for HeroGender, SpeakerGender, and TargetGender.
Perform Speaker Name Processing allows the displayed Character name to be modified before presentation. By default, Consequence hides the speaker name when the Line uses the Character configured as the SFX Character.
Perform Text Processing applies gender parsing and closed-caption processing before the dialogue is displayed.
These hooks allow projects to adapt Consequence subtitle output without changing the underlying authored dialogue.
Gender parsing can use the Consequence Scripting Manager to determine runtime gender information for:
Implement the corresponding functions in your project's Consequence Scripting Manager if your game requires variable runtime genders.
See Consequence Scripting Manager and Localization for more information.
The parent Subtitle Widget exposes runtime controls for:
Get / Set Subtitles Enabled controls whether normal subtitles are displayed.
Get / Set Closed Captions Enabled controls closed-caption presentation separately from normal dialogue subtitles.
Get / Set Direction Indicator Enabled controls whether directional VO indicators are active.
These settings can be connected directly to your game's accessibility, audio, or UI settings.
Changing any of these settings automatically refreshes all currently active subtitle Lines.
Lines marked Always Subtitle are displayed even when normal subtitles are disabled.
Each Subtitle Line Widget provides:
Set Scratch VO Indicator Visibility
This is called as the Line display is updated and allows your Blueprint to show a project-specific indicator when the current Line is using Scratch VO.
For example, development builds may display a small label or icon to make it clear that temporary audio is being heard.
The appearance of that indicator is entirely controlled by your Widget Blueprint.
Each Subtitle Line Widget provides:
Set Radio Indicator Visibility
By default, the Radio Indicator is shown when the current Line includes the Radio Audio Processor.
Override this function to customize how your project represents radio, communications, or otherwise processed dialogue.
The indicator itself can be any Widget supplied when calling Initialize Subtitle Line.
Closed-caption information can be included directly in dialogue using square brackets.
For example:
[door slams] Where are you going?
When closed captions are disabled, bracketed text is removed from the displayed subtitle.
When closed captions are enabled, bracketed text is displayed in parentheses:
(door slams) Where are you going?
For Chinese, Japanese, and Korean cultures, Consequence uses fullwidth parentheses for closed-caption text.
If a Line contains only closed-caption text and closed captions are disabled, the subtitle Line is hidden entirely.
Subtitle tiers provide a general-purpose way to vary subtitle presentation according to project-specific rules.
Override Determine Subtitle Tier in your Consequence Scripting Manager to assign a Tier to the current subtitle.
Then override Handle Subtitle Tier in your ConsequenceSubtitleLineWidget Blueprint to update its appearance based on that Tier.
For example, different tiers could use different placement, emphasis, opacity, sizing, or other presentation rules.
The meaning of each Tier is defined by your project.
Consequence subtitle widgets can optionally display directional information pointing toward the Actor who is currently speaking.
Enable or disable this behavior at runtime using Get / Set Direction Indicator Enabled.
Each Subtitle Line Widget can contain a Directional Indicator Widget supplied through Initialize Subtitle Line.
While directional VO is enabled, Consequence calculates the horizontal direction from the player camera to each active speaking Actor and calls Update Directional Indicator with the resulting angle.
Override this function in your Line Widget Blueprint to convert that angle into your desired visual presentation, such as rotating an arrow toward the speaker.
The default Consequence implementation calculates speaker direction but does not perform on-screen / off-screen detection. Projects requiring that distinction can override On Directional VO Tick Timer in the parent Subtitle Widget to provide custom behavior.
Consequence can automatically hide subtitles when the speaking Actor is too far from the player.
Separate attenuation distances can be configured for:
These are set using Foreground Subtitle Attenuation and Background Subtitle Attenuation in Consequence Runtime Settings.
Distance is measured between the speaking Actor and the Hero Actor returned by the Consequence Scripting Manager.
Set an attenuation value to 0 or below to disable distance-based subtitle attenuation for that category.
Lines marked Always Subtitle bypass subtitle distance attenuation.
The parent Consequence Subtitle Widget can also manage the UI used to display Consequence dialogue Choices.
Create each choice entry as a Widget Blueprint inheriting from ConsequenceChoiceWidget.
During construction, call Initialize Choice Widget and provide the Text or Rich Text Widget that should display the Choice text.
When Consequence presents a set of Choices, the parent Subtitle Widget calls Set Choice Text on each visible Choice Widget.
The default Subtitle Widget implementation supports up to four simultaneously displayed Choices. Choice Widgets beyond the number of available Choices are automatically collapsed.
While Choices are displayed, the normal subtitle Lines panel is hidden and the Choices panel is shown. Once a Choice is selected or the Choice set is cancelled, the Choices panel is hidden and the subtitle Lines are shown again.
Handle Choice Input accepts the index of the Choice to select and forwards the corresponding Line UID to Make Choice.
Make Choice then broadcasts the selected Line UID back to the Consequence System.
Projects can override these functions if they require a different input or presentation model.
The Line Widgets supplied to Initialize Subtitle Widget act as the available display slots for simultaneous subtitles.
When a new subtitle begins, Consequence places it in the first unused Line Widget.
When a subtitle ends, any later active subtitles are shifted to fill the newly available slot.
The number of Line Widgets configured in your parent Subtitle Widget therefore determines how many simultaneous subtitle Lines the default implementation can display.
You are not required to use Consequence's supplied visual design.
The Blueprint classes are intended to act as the integration layer between Consequence runtime dialogue and your project's UI.
A typical custom integration is:
ConsequenceSubtitleWidget.ConsequenceSubtitleLineWidget.Initialize Subtitle Line from each Line Widget to supply its UI elements.Initialize Subtitle Widget from the parent Widget to supply its Line and Choice Widgets and parent panels.You can then override only the presentation hooks your game requires while leaving Consequence to manage dialogue events, active subtitle data, and Line selection.