> For the complete documentation index, see [llms.txt](https://dante-3.gitbook.io/dante-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dante-3.gitbook.io/dante-docs/modular-attachment-system.md).

# Modular Attachment System

**Type:** Runtime + Editor\
**Status:** Stable\
**Engine:** UE 5.7+\
**Dependencies:** `GameplayTags` (Engine) 

{% embed url="<https://www.fab.com/listings/72d90bb1-0abc-442e-a154-720c3fc30efa>" %}

## Overview

`ModularAttachmentSystem` is a **data-driven, streaming-first attachment framework** for Unreal Engine 5. It enables modular composition of visual and gameplay elements on actors through a three-layer pipeline:

* **Fragments** — atomic building blocks (mesh, VFX, stat modifier, etc.)
* **Definitions** — data assets that compose multiple fragments into a complete attachment
* **Components** — runtime mount points on actors that load and apply definitions

Key capabilities:

* **Three-phase async load** — Definition → Soft Refs → Apply; guarantees all assets are ready before spawning
* **Ref-counted cache** — shared definitions loaded once, ref-counted across all consumers
* **Fragment hierarchy** — fragments can nest child fragments for complex compositions
* **Tag-based event routing** — broadcast events to specific slots/fragments via `FGameplayTag`
* **Editor preview** — full in-editor WYSIWYG preview with sync loading
* **Blueprint extensible** — fragments use `BlueprintNativeEvent`; override in C++ or Blueprint

## Architecture at a Glance

```
UModularAttachmentSubsystem  (UWorldSubsystem — one per world)
├── Asset Cache              ref-counted FStreamableHandle pool
├── Tag Registry             FGameplayTag → TArray<UModularAttachmentComponent*>
└── Event Broadcast          BroadcastToTag(TargetTag, Payload)
        │
        ▼
UModularAttachmentComponent  (USceneComponent — per-slot on any actor)
├── ComponentTag             "ModularAttachment.Slot.Optic"
├── LoadState                EAttachmentLoadState (NotLoaded → Loading → Loaded)
└── UModularAttachmentDefinition  (UPrimaryDataAsset)
    ├── Fragment A           UModularAttachmentFragment_StaticMesh
    ├── Fragment B           UModularAttachmentFragment_SkeletalMesh
    └── Fragment C           Custom fragment (stat modifier, VFX, etc.)
```

### Data Flow

```
LoadAttachment()
  │
  ▼  Phase 1 — Stream definition asset
Subsystem→RequestLoad()
  │
  ▼  Phase 2 — Definition→CollectAllSoftRefs() → batch stream all meshes/materials
OnFragmentAssetsLoaded()
  │
  ▼  Phase 3 — Apply fragments to component
Fragment→ApplyToComponent()  ×N
  │
  ▼
OnAttachmentLoadCompleted.Broadcast()
```