Progression and Timing

Progression controls when and how the conversation moves from one beat group to the next.

The ProgressionSystemService manages timed auto-advancement and countdown timers. Each beat group carries ProgressionData that configures its timing behaviour.

Progression modes

There are several ways a beat group can advance:

• player-driven -- the player presses the advance input to move forward
• auto-progress -- the beat group advances automatically after its duration elapses
• wait-for-line -- the beat group waits for audio or animation to finish before advancing

These can be combined. A beat group can wait for its audio to finish and then advance automatically, or it can wait for the player regardless of how long the audio is.

Duration calculation

A beat group's content duration is the length of the longest beat in it:

• audio beats contribute their clip length
• animation beats contribute their clip length
• text, mood, and camera beats contribute nothing

That last point matters when you are authoring. A text beat has no duration of its own -- an audio clip is as long as the clip, but a line of text is as long as the reader needs, which is not a property of the asset. A text-only beat group therefore has a content duration of zero, and everything that keeps it on screen comes from the reading hold.

Reading hold

The reading hold is the time a beat group lingers after its content has finished. Without it, a text-only group set to auto-progress would advance the moment the line finished appearing, and the player would never get to read it.

It is configured in BardTreeLtd/Dialogue/Module Settings, under UI > Reading Hold:

Setting	Default	What it does
Enabled	on	Turn the whole hold off to advance as soon as content finishes.
Minimum Hold	0.7s	Always hold at least this long, however short the line.
Reading Speed	18 cps	Characters per second used to size the hold. Lower is slower and more generous.
Revealed Hold Factor	0.35	Fraction of the reading time still owed when the player watched the line appear.
Maximum Hold	4s	Upper bound, so one very long line cannot stall the conversation.

Longer lines are held longer, within the minimum and maximum you set. Tune the pace with Reading Speed and use the two bounds to stop very short lines flashing past or very long ones stalling the conversation.

The revealed hold factor is what stops voiced and typewritten lines from feeling padded. A line the player watched appear -- typed out, or paced by an audio or animation beat -- needs less time at the end than one that landed instantly, because they have been reading along. Lower the factor if lines feel like they linger after the voice has stopped.

An auto-progressing group waits for its content duration and then the reading hold.

Headless conversations

Agent-to-agent conversations have no dialogue panel, so their pacing is derived from the typewriter and reading hold settings rather than from anything on screen. They stay readable when overhead text is on, and keep a believable rhythm even when nobody is watching.

Countdown timers

Some conversations need the player to decide within a time limit. This is configured through ProgressionData on the beat group's outgoing options:

• timeLimit -- how long the player has to choose
• defaultSelect -- which option is auto-selected when time runs out

When a time limit is active, a progress bar appears through DialogueProgressBarView, showing the remaining time as a fill bar. If the player does not choose before the timer expires, the default option is selected automatically.

When to use each mode

• player-driven -- best for dialogue choices and important moments where the player should control the pace
• auto-progress -- best for NPC monologues or ambient dialogue where the conversation should flow without input
• wait-for-line -- best when you have audio and want the line to finish naturally before options appear
• timed options -- best for moments of tension or urgency where the player must act quickly

Practical advice

Default to player-driven progression. It gives the player full control and avoids situations where text advances before they finish reading. Add auto-progression for polish once the content and flow are established.

Timed options are effective for dramatic moments but frustrating if overused. Reserve them for conversations where urgency is part of the narrative.

Reference

• Progression Service

Next step

Continue to Agent-to-Agent Conversations.