BP-REF-001

CriticalBlueprintHard Reference Cascade

Flags Blueprints that directly reference large assets as variables or defaults. Hard references load referenced assets into memory at class load time—before your code runs.

Why It Matters

Hard references resolve at load time. When Unreal loads your Blueprint, it follows every hard reference recursively—loading those assets before any of your code runs.

Reference Type	Load Behavior	Memory Impact
`UStaticMesh*`	Loaded when referencer loads	Immediate
`TSoftObjectPtr<>`	Loaded on demand	Deferred

Example: A character that hard-references 20 weapons at 15MB each loads 300MB just to spawn—even if the player only uses one weapon.

When It’s Acceptable

Always-needed assets: The character’s own skeletal mesh
Small assets: Tiny textures, simple meshes
Singletons: GameInstance referencing core systems

The Fix

Option 1: Soft References (Recommended)

// Before (hard reference)
UPROPERTY(EditDefaultsOnly)
UStaticMesh* WeaponMesh;

// After (soft reference)
UPROPERTY(EditDefaultsOnly)
TSoftObjectPtr<UStaticMesh> WeaponMesh;

// Load when needed
UStaticMesh* Mesh = WeaponMesh.LoadSynchronous();

In Blueprints, use Async Load Asset to load soft references on demand.

Option 2: Data Tables

Store asset paths in a Data Table (small reference), load meshes at runtime.

Option 3: Asset Manager

For complex loading patterns, use Primary Asset Types and load bundles on demand.

Configuration

Project Settings → Blueprint Health Analyzer → BP-REF-001 → 100.0

BP-CAST-001 — Casts create hard references
AST-UNUSED-001 — Unused assets loaded via references