CIVIL-AI-SYSTEM Integration

When both CIVIL-DIALOGUE-SYSTEM and CIVIL-AI-SYSTEM are installed, an integration layer coordinates the two modules automatically.

This page explains what the integration provides and what changes compared to running Dialogue standalone.

The integration assemblies

There are two, and which one owns a feature depends on which direction the dependency runs:

Assembly	Registrar	Order	Direction
Assets/BardTreeLtd/Integrations/CivilAI.Dialogue/	CivilAIDialogueIntegrationRegistrar	300	Teaches Dialogue about CivilAI agents.
Assets/BardTreeLtd/Integrations/Dialogue.CivilAI/	DialogueCivilAIIntegrationRegistrar	301	Teaches CivilAI when to refuse a conversation.

Both run after the CivilAI registrar (Order 100) and the Dialogue registrar (Order 200), so all services from both modules are available when the integration wires up.

What the integration provides

Agent control during conversations

The integration registers CivilConversationAgentControlPolicy as a multi-registration for IConversationAgentControlPolicy.

When a conversation starts, this policy pauses the agent's CivilAI behaviour tree. When the conversation ends, the behaviour tree resumes. This prevents agents from walking away, switching tasks, or performing work actions while they are in a conversation.

Without CivilAI, a no-op fallback is used and agents are not paused.

Agent tokens

CivilAgentTokenResolver is registered twice, as speaker and as other, adding four tokens that read live agent state. They resolve only when the participant is a CivilAI agent; otherwise the token is left in the text.

Token	Resolves to
{speaker.status}	The agent's current status, lowercased with underscores as spaces.
{speaker.job}	The name of the job at the top of the agent's work behaviour.
{speaker.need}	The agent's highest need.
{speaker.active_need}	The need the agent is currently acting on.

The same four are available on other. This is what lets a line read "You look like you could use a drink" without authoring a variant per need. See Token System.

Conversation availability

CivilAgentDialogueAvailabilityPolicy is registered as an IConversationAvailabilityCheck. Before a conversation starts, it inspects the agent's active behaviour tree and can refuse -- so an agent mid-task is not interrupted by a passer-by, or by the player.

The rules come from a DialogueNodeMapping asset, which maps behaviour node IDs to two settings blocks.

DialogueNodeSettings blocks conversation while a node is anywhere in the active tree:

Field	Effect
blockPlayerConversation	Refuse player-initiated conversations.
blockHeadlessConversation	Refuse agent-to-agent conversations.

JobDialogueSettings applies to the top node of the tree and can override trigger tuning per job, each field gated by its own override flag:

Field	Effect
overridePlayerConversation / allowPlayerConversation	Allow or refuse player conversations.
overrideHeadlessConversation / allowHeadlessConversation	Allow or refuse headless conversations.
overrideCooldown / cooldownSeconds	Replace the global trigger cooldown.
overrideProbability / probability	Replace the global trigger probability.

Job overrides are checked first and short-circuit the node scan, so a job that explicitly allows conversation wins over a node that would block it.

A trigger volume can bypass all of this with Ignore Availability Checks, which is how a scripted story beat interrupts an agent that would otherwise refuse.

Barks

From CIVIL-AI-SYSTEM 0.14.0, Civil AI agents can bark: say short lines on their own. The integration makes barks use the dialogue system's overhead text bubble, through DialogueBarkPresentationService, so barks and conversation lines look the same.

• The bubble's look comes from the Overhead Text settings. Civil AI's module settings show the same appearance settings on its Barks tab, and changing them there changes them here.
• Enabled and Headless Only don't affect barks. Barks have their own Show Text setting.
• When the typewriter is on, a bark stays up until its line has finished typing.
• Barks give way to conversations: no bark starts during one, a bark stops when one begins, and participants stay quiet for a while after it ends.

See Barks in the CIVIL-AI docs.

Flowchart editor extension

DialogueCivilAIFlowchartExtension adds a CivilAI settings group to the flowchart editor, so the node mapping above is authored alongside the behaviour rather than in a separate asset window.

World clock

CIVIL-AI-SYSTEM is the canonical owner of IWorldClock when installed. The Dialogue module can consume this shared service for time-aware features.

When running standalone, the Dialogue registrar registers a fallback IWorldClock implementation that returns zero. This means time-dependent dialogue features will not function without CivilAI, but the system will not crash.

Item catalogue

The Dialogue editor checks for item collections through the shared IItemCatalog service before displaying its graph view. In practice, this means CivilAI item collections (item name, type, and size collections) need to be set up before the Dialogue editor works correctly.

This is why most combined projects should treat CivilAI setup as the foundation and Dialogue as a layer added on top.

Conversation triggers and sense

When CivilAI is installed, conversation trigger proximity detection can use the CivilAI sense system (ISenseProvider). This provides perception-profile-based spatial awareness rather than simple distance checks.

Setup order for combined projects

If you are using both modules:

1. set up BardTreeModuleBootstrap in the scene
2. configure CivilAI module settings and item collections
3. verify CivilAI agents spawn and simulate correctly
4. configure Dialogue module settings
5. create dialogue content and assign trees to agents
6. test conversations

For detailed CivilAI setup, see the Getting Started guide in the CIVIL-AI docs. For Dialogue-specific setup within a combined project, see the Dialogue Setup guide.

Running standalone

Dialogue works without CivilAI. The key differences when running standalone:

• agent behaviour trees are not paused during conversations (no behaviour trees exist)
• world clock returns zero (no world time simulation)
• item catalogue is not available (the Dialogue editor may show a warning)
• conversation triggers use simpler proximity detection

For standalone setups, use Shared + Dialogue as your install combination and configure dialogue agents directly without CivilAI population regions or buildings.

Practical advice

For most users building a medieval town with interactive NPCs, Shared + CivilAI + Dialogue is the recommended setup. The integration layer handles coordination automatically and you do not need to wire anything manually.

If you are building a project focused purely on conversation (a visual novel, an interview simulator, a dialogue prototype), standalone Dialogue is a valid and simpler starting point.