Player Conversations

Player conversations are the core interaction model. The player looks at an NPC, sees a prompt, confirms the interaction, and enters a dialogue flow.

How a conversation starts

The ChatSystem component handles detection and initiation. Each frame, it checks for nearby agents using one of three configurable detection modes:

• Raycast -- casts a ray from the centre of the camera (default)
• SphereCast -- casts a wider sphere from the camera centre (useful for less precise targeting)
• Proximity -- detects agents within a radius and angle cone regardless of where the player is looking

Detection settings are configured in BardTreeLtd/Dialogue/Module Settings, under the Agent Detection section:

• Detection Mode -- which method to use
• Max Distance -- how far the detection reaches (default: 5 units)
• Sphere Cast Radius -- the width of the sphere cast (when using SphereCast mode)
• Detection Angle -- the cone angle for proximity detection
• Detection Layer Mask -- which layers are checked
• Require Line Of Sight -- whether obstacles block detection

When a valid target is found, a prompt appears on screen (the "press to talk" indicator). When the player confirms the interaction, the conversation opens.

The conversation lifecycle

Once the player confirms:

1. any headless conversation the agent is in is ended first
2. a ChatConversationSession is created
3. the world pauses (if configured through the world pause policy)
4. the agent's control is acquired (stopping other activity)
5. the player's movement is disabled
6. the cursor is shown (if configured through the cursor policy)
7. conversation-scoped blackboard values are cleared
8. the dialogue camera enters conversation mode
9. the ConversationStarted event fires

The session then resolves the agent's chat tree and navigates to the entry node. Beat playback begins automatically, with text optionally using the typewriter effect to reveal characters one at a time.

Moving through nodes

ChatSystemService manages the conversation flow. It uses ChatNodeNavigator to resolve connections and DialogueNodeResolver to walk the graph.

When the player reaches the end of a node's beat groups:

• if there is one available connection, the conversation advances to the next node
• if there are multiple connections marked as options, the response UI appears
• if there are no available connections, the conversation handles the dead end gracefully

When the player selects an option, any blackboard effects on that connection are applied before navigating to the target node.

How a conversation ends

A conversation closes when:

• the runtime reaches an end node
• no available connections remain (dead end fallback)
• the conversation end policy triggers (for example, the player looks away)

On close:

1. the camera exits dialogue mode
2. the ConversationEnded event fires
3. agent control is released
4. player movement is restored
5. the cursor is restored to its previous state
6. the world resumes
7. conversation-scoped blackboard values are cleared

The entry point component

ChatSystem is a MonoBehaviour you place in the scene. It handles the update loop for detection and acts as the bridge between player input and the conversation runtime.

It does not need manual configuration beyond being present in the scene. The prompt and chat UI prefabs are instantiated at runtime from module settings through DialogueUiService.

Practical advice

For a first test:

• add ChatSystem to your scene
• make sure the scene has a camera tagged MainCamera
• create one chat tree with a few connected chat nodes
• assign the tree to an NPC agent
• press Play and walk up to the agent

If the prompt does not appear, check that the agent has an IAgentService component and is within raycast range.

Next step

Continue to Responses and Options.