Skip to main content

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​

The duration of a beat group is calculated from the longest beat it contains:

  • audio beats provide their clip length
  • animation beats provide their clip length
  • text-only groups use a configured fallback duration from progression data

When auto-progress is enabled, the system waits for this calculated duration before advancing.

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.

Next step​

Continue to Agent-to-Agent Conversations.

Last updated on