Debugging

The Dialogue system includes built-in debug tools for diagnosing conversation triggers, sense perception, chat flow, and runtime state.

Enabling debug mode

All debug features are gated behind a single master toggle in BardTreeLtd/Dialogue/Module Settings, under the Debug section:

• Enable Debug Mode -- turns on all debug features (must be enabled for any of the below to work)

Once enabled, individual channels can be toggled:

• Log Trigger Evaluation -- logs trigger checks and their outcomes
• Log Sense Perception -- logs perception queries between agents
• Log Chat Flow -- logs conversation navigation (node entered, option selected, conversation opened/closed)
• Draw Sense Gizmos -- draws perception cones and ranges on trigger sources in the Scene View
• Draw Conversation Links -- draws visual links between agents in conversation in the Scene View

Scene debug overlay

When debug mode is active, a Scene View overlay draws runtime state:

• Conversation links -- cyan lines connecting agents who are currently in conversation, labeled "IN CONVERSATION"
• Agent states -- labels above each agent showing their current state:
  • CHATTING (cyan) -- agent is in a conversation
  • PAUSED (red) -- agent's behaviour is paused
  • IDLE (green) -- agent is available
• Trigger evaluation results -- dotted lines showing what happened during the last trigger evaluation:
  • green -- conversation was triggered
  • red -- perception failed (target not in range or line of sight)
  • yellow -- probability roll failed
  • grey -- other failure (cooldown, requirements not met)

Results expire after 5 seconds to avoid clutter.

Console logging

Debug log messages are tagged by channel:

• [Dialogue.Trigger] -- trigger evaluation events
• [Dialogue.Sense] -- sense perception events
• [Dialogue.Chat] -- chat flow events

You can filter Unity's Console by these tags to isolate specific issues.

Common debugging scenarios

Conversations not triggering

1. Check that triggers are enabled in module settings
2. Verify the agent has a ConversationTriggerSource (or that Auto Attach is enabled)
3. Check cooldown timers -- the default is 30 seconds
4. Enable Log Trigger Evaluation and look for failure reasons
5. Check that the target agent has a headless dialogue tree assigned

Player cannot start conversation

1. Check that the agent is within detection range
2. Verify the detection mode matches your setup (raycast requires the agent to be in the centre of the screen)
3. Check that the agent has an IAgentService component
4. Check the detection layer mask includes the agent's layer
5. Enable Log Chat Flow and look for detection events

Camera not framing correctly

1. Verify the camera system is enabled in module settings
2. Check that a DialogueCameraSettings asset exists in Resources
3. Add a DialogueCameraFocusPoint component to the agent if auto-detection is not finding the head bone
4. Check the collision mask -- the camera may be blocked by geometry

Tokens not resolving

1. Look for [Token] Unresolved token warnings in the Console
2. Verify the blackboard key exists and has a value at the time the beat is displayed
3. Check the prefix is correct (bb, speaker, other, world)
4. For world tokens, verify CIVIL-AI-SYSTEM is installed (the fallback clock returns zero)

Practical advice

Keep debug mode disabled in builds and enabled only during development. The overlay and logging have minimal performance impact but produce noise that is not useful in shipping builds.

When reporting bugs, enable all debug channels and reproduce the issue. The log output provides the information needed to diagnose most problems.