Skip to main content

UI and Theming

The dialogue UI is created at runtime from module settings and styled through a theme system.

DialogueUiService handles instantiation. It reads prefab references and theme configuration from ModuleSettings, creates the necessary Canvas and view components, and applies the active theme.

Module settings​

The following UI-related settings are configured in BardTreeLtd/Dialogue/Module Settings:

  • Prompt Prefab -- the "press to interact" prompt shown when looking at an NPC
  • Chat System Prefab -- the conversation panel that displays dialogue
  • Default Theme -- the DialogueUiTheme asset used for styling
  • Reference Resolution -- the canvas scaler reference resolution (default: 2560x1440)
  • Match Width Or Height -- how the canvas scaler blends between width and height matching

Typewriter settings​

Controls character-by-character text reveal:

  • Enabled -- whether text animates in or appears instantly
  • Characters Per Second -- reveal speed (default: 30)
  • Sync With Audio -- whether the typewriter paces itself to match the audio clip duration

When the player presses Advance during a typewriter animation, the text completes instantly.

Portrait settings​

Controls speaker portrait display:

  • Enabled -- whether portraits are shown in the speech panel
  • Default Portrait -- a fallback Sprite used when an agent has no portrait assigned

Individual agents can provide their own portrait through AgentChatService.

Overhead dialogue text settings​

Controls world-space text that appears above agents' heads during conversations:

  • Enabled -- whether overhead text is active
  • Headless Only -- when true, overhead text only appears for agent-to-agent conversations (not player conversations that already have a panel)
  • World Text Prefab -- optional custom prefab for the overhead text object
  • Head Offset -- position offset above the agent (default: 0, 2, 0)
  • Max Width -- text wrapping width
  • Font Asset -- TMP font to use
  • Font Size -- text size (default: 36)
  • Text Color -- the text colour
  • Show Background -- whether a background panel appears behind the text
  • Background Color -- the background colour (default: semi-transparent black)
  • Billboard To Camera -- whether the text always faces the camera
  • Fade In Out -- whether text fades in and out or appears/disappears instantly
  • Fade Duration -- how long the fade takes (default: 0.2s)

This is particularly useful for agent-to-agent conversations where no dialogue panel is shown but you want nearby players to see what NPCs are saying.

View components​

The UI is built from five view components:

DialoguePanelView​

The root panel that contains all other views. It manages show/hide state and applies the theme to child views.

DialogueSpeechView​

Displays the speaker name and current dialogue text. Styled with font, size, and colour from the theme.

DialogueOptionsView​

Manages the list of selectable dialogue options. Uses a pooled list of DialogueOptionItemView items that are activated and deactivated as needed. Handles layout, spacing, and selection highlighting.

DialogueProgressBarView​

Shows the countdown timer when timed options are active. Displays as a fill bar that decreases as time runs out.

DialoguePromptView​

The interaction prompt shown when the player is looking at a dialogue-capable NPC. Displays the input binding for the interact action.

Themes​

DialogueUiTheme is a ScriptableObject that defines the visual style of the dialogue UI. It implements IDialogueUiTheme and controls:

  • fonts and text sizes
  • text colours
  • background colours and sprites
  • spacing and minimum heights for options
  • progress bar colours

Theme resolution​

The theme is resolved with this precedence:

  1. an explicit override set at runtime
  2. the default theme from module settings
  3. a local fallback embedded in the prefab

DialogueUiThemeService manages this resolution. You can change themes at runtime using ApplyTheme() or RefreshTheme() on DialogueUiService.

Practical advice​

For a first setup, use the default prefabs and theme that ship with the module. Customise the theme asset to match your game's visual style once the conversation flow is working.

If the UI does not appear during a conversation, check that:

  • module settings has valid prefab references
  • the scene has a camera tagged MainCamera
  • DialogueUiService.Initialize() is being called during bootstrap

Next step​

Continue to Conversation Policies.

Last updated on