Circular Dependencies¶

Circular dependencies occur when assets reference each other in a loop. Asset Atlas detects these chains and helps you understand and resolve them.

What Are Circular Dependencies?¶

A circular dependency is when Asset A depends on Asset B, which depends on Asset C, which depends back on Asset A:

A → B → C → A  (circular!)

Or simply:

A → B → A  (two-asset circular)

Why They Matter¶

Impact	Description
Load Order	Engine can't determine correct load sequence
Slow Loading	May cause multiple load passes
Packaging Issues	Can cause cook failures or runtime errors
Memory	May prevent proper garbage collection

Finding Circular Dependencies¶

From Dashboard¶

View the Circular Dependencies card
If count > 0, click the card
The circular panel opens in Graph Explorer

From Graph Explorer¶

Click Find Circular in the header
The graph filters to show only circular assets
The circular panel opens on the right

Visual Identification¶

Assets in circular chains are displayed with a yellow tint in the dependency graph. The circular connection lines are also highlighted.

The Circular Panel¶

When viewing circular dependencies, a side panel displays each chain:

┌─────────────────────────────┐
│ CIRCULAR DEPENDENCIES  [×]  │
├─────────────────────────────┤
│ ▼ Cycle 1 (3 assets)        │
│   /Game/BP/Player           │
│   → /Game/BP/Weapon         │
│   → /Game/BP/Inventory      │
│   → /Game/BP/Player         │
│                             │
│ ▼ Cycle 2 (2 assets)        │
│   /Game/UI/MainMenu         │
│   → /Game/UI/Settings       │
│   → /Game/UI/MainMenu       │
├─────────────────────────────┤
│ [Ignore Selected]           │
└─────────────────────────────┘

Panel Features¶

Click a cycle to highlight it in the graph
Expand/collapse each cycle for details
Ignore cycles you've acknowledged

Understanding Circular Chains¶

Chain Length¶

The minimum chain length for detection is configurable:

Length	Example	Severity
2	A → B → A	Direct mutual reference
3	A → B → C → A	Indirect cycle
4+	A → B → C → D → A	Complex chain

Default Setting

By default, Asset Atlas uses a minimum chain length of 3. Two-asset mutual references are common and often intentional.

Common Patterns¶

Pattern	Description	Usually OK?
Manager ↔ Component	Manager references component, component references manager	Often
Parent ↔ Child	Bidirectional parent-child references	Sometimes
Subsystem cycles	Multiple systems referencing each other	Rarely

Resolving Circular Dependencies¶

Strategy 1: Break the Cycle¶

Identify which reference can be removed:

Look at the chain
Determine which direction is "optional"
Remove or refactor that reference

Strategy 2: Use Interfaces¶

Replace direct references with interface-based communication:

Before: A → B → A

After:  A → IB (interface)
        B implements IB
        B → IA (interface)
        A implements IA

Strategy 3: Use Soft References¶

Convert hard references to soft references for less critical dependencies:

// Before
UPROPERTY()
UMyAsset* DirectReference;

// After
UPROPERTY()
TSoftObjectPtr<UMyAsset> SoftReference;

Strategy 4: Restructure Assets¶

Sometimes the best solution is to restructure:

Merge tightly coupled assets
Split assets with too many responsibilities
Create a shared base class

Ignoring Circular Dependencies¶

For acceptable circular dependencies:

Select the cycle in the panel
Click Ignore
The cycle is added to the project's ignore list

When to Ignore¶

Known and intentional - You understand why it exists
Third-party assets - Can't modify external plugins
Working correctly - No actual issues in practice

Ignore List Behavior¶

Ignored cycles are excluded from counts
They won't affect your health score
The ignore list is stored per-project

Filtering Options¶

The circular detection system has configurable filters:

Built-in Filters¶

Filter	Description
Ignore Self References	Skip A → A patterns
Ignore Engine Assets	Skip /Engine/ and /Script/ paths
Ignore Soft References	Skip soft/lazy references

Configuring Filters¶

Filters are configured via:

Project Settings > Asset Atlas > Grading Preset
Or custom JSON grading rules

See Grading System for details.

Preventing Circular Dependencies¶

Best Practices¶

One-way dependencies - Establish clear dependency direction
Dependency injection - Pass references rather than hard-code
Event systems - Use delegates instead of direct references
Interface segregation - Depend on interfaces, not implementations

During Development¶

Scan regularly - Run Asset Atlas weekly
Fix early - Address circulars when they appear
Document intentional - If keeping a circular, document why

Grading System Orphan Detection