Behavior Tree Insight Documentation

Recommended First Steps

1. Run full analysis when you want project-level BT, BB, and EQS review artifacts.
2. Take a snapshot before modifying an important Behavior Tree.
3. Run Decision Structure Diff when you want to compare two selected Behavior Trees.
4. Share Markdown or JSON reports with an AI assistant when you need structured review context.

Install the Plugin

1. Close Unreal Editor.
2. Copy the plugin folder into your project's Plugins folder.
3. Confirm the plugin folder is directly under <YourProject>/Plugins/.
4. Reopen the project in Unreal Editor.
5. If Unreal asks to rebuild modules, allow the rebuild.

Enable the Plugin

1. Open Edit > Plugins.
2. Search for Behavior Tree Insight.
3. Enable the plugin if it is not already enabled.
4. Restart the editor if Unreal asks you to do so.

Run Full BT Analysis

1. Open your Unreal Engine project.
2. Go to Tools > Run Behavior Tree Insight Analysis.
3. Wait for the progress notification to complete.
4. Open the generated reports under <YourProject>/Saved/BehaviorTreeInsight/.

Full analysis creates project-level Behavior Tree, Blackboard, and EQS review reports.

Take a BT Snapshot

1. Select exactly one Behavior Tree asset in the Content Browser.
2. Use Tools > Behavior Tree Insight > Take BT Snapshot, or right-click the selected Behavior Tree asset and choose Take BT Snapshot.
3. Open the generated snapshot folder under <YourProject>/Saved/BehaviorTreeInsight/Snapshots/[BT_Name]/[YYYY-MM-DD_NNN]/.

Snapshots are static review checkpoints. They do not record runtime behavior.

Run BT Decision Structure Diff

1. Select exactly two Behavior Tree assets in the Content Browser.
2. Use Tools > Behavior Tree Insight > Run BT Decision Structure Diff, or right-click the selected Behavior Tree assets and choose Run BT Decision Structure Diff.
3. Open the generated diff files under <YourProject>/Saved/BehaviorTreeInsight/Diff/.

Decision Structure Diff compares static structural evidence between selected Behavior Trees. It does not judge which version is better.

Generated reports are intended to be inspected by developers and may also be shared with AI assistants for technical discussion.

Review Boundaries

• Behavior Tree Insight performs static editor-side analysis.
• It does not simulate live AI execution, Blackboard values, perception state, or exact runtime branch selection.
• It does not infer AI personality, author intent, gameplay quality, or runtime truth.
• Snapshot and diff outputs are review evidence, not quality grades or automatic behavior approval.
• It does not modify Behavior Trees, Blackboards, EQS assets, gameplay logic, runtime behavior, assets, or project settings.
• Reports are intended to support human review, documentation, onboarding, regression checks, and AI-assisted technical discussion.

Static reports should be treated as evidence-based review material. Runtime behavior, branch conditions, dynamic data, and project-specific design intent may require manual verification inside Unreal Editor.

Do NOT Give AI Only The Full Project Export

When using Insight Ecosystem outputs with AI-assisted workflows, we strongly recommend providing both the full project export and a focused Runtime Package for the specific system currently being modified.

providing BOTH:
- the full project export
- a focused Runtime Package

This is extremely important for long Unreal Engine implementation sessions.

Why?

During large Blueprint-driven workflows, AI may gradually drift from:

system-level runtime reasoning

toward:

localized patch reasoning

especially during manual Blueprint wiring, runtime suppression work, BT/EQS modifications, montage-related implementation, and dispatcher-heavy systems.

The problem is often not lack of information. The problem is:

loss of topology focus

Recommended Workflow

1. Full Insight Export

This provides overall project structure, global topology, and cross-system visibility.

2. Focused Runtime Package

This stabilizes runtime ownership awareness, convergence tracking, orchestration understanding, and cleanup path awareness for the system currently being modified.

Example

For a melee combat modification, a Combat Runtime Package might include:

• related BTTasks
• related BTServices
• related Blackboard assets
• combat orchestration Blueprints
• related AnimBP sections
• related dispatcher / notify data
• related hidden_dependencies excerpts
• related comment_clusters excerpts

while excluding unrelated systems such as UI, unrelated locomotion, unrelated player systems, and unrelated vehicle systems.

Important

This is not primarily about reducing file size. It is about:

stabilizing the AI's runtime attention topology

In practice, this can significantly reduce local patch drift, screenshot anchoring, orchestration confusion, cleanup-path mistakes, and runtime ownership loss during long AI-assisted Unreal Engine sessions.

For more detailed discussion about AI reasoning drift, synchronization rules, structure-first workflows, and runtime orchestration safety, please see:

AI Workflow Discipline & Synchronization