> 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/gameplay-tags.md).

# Gameplay Tags

## Overview

The plugin ships with **native Gameplay Tags** defined in:

```txt
ModularAttachmentSystem/Config/Tags/ModularAttachmentTags.ini
```

Tags are registered automatically via `UGameplayTagsManager::AddTagIniSearchPath()` during `StartupModule`. No manual project configuration is needed.

## Tag Hierarchy

All tags live under the `ModularAttachment` root:

```txt
ModularAttachment
├── Slot              Component slot identifiers
├── Fragment          Fragment type / instance identifiers
├── Event             Event routing tags
├── Value             Payload numeric value keys
└── State             Runtime state descriptors
```

## Slot Tags — `ModularAttachment.Slot.*`

Used by `UModularAttachmentComponent::ComponentTag` to identify attachment slots on an actor. Each slot represents a logical mount point.

| Tag                 | Purpose                                                |
| ------------------- | ------------------------------------------------------ |
| `.Slot.Primary`     | Primary attachment slot (e.g., weapon body, main item) |
| `.Slot.Secondary`   | Secondary attachment slot                              |
| `.Slot.Optic`       | Optic / scope mount                                    |
| `.Slot.Muzzle`      | Muzzle device (suppressor, flash hider, compensator)   |
| `.Slot.Underbarrel` | Underbarrel rail (grip, laser, bipod)                  |
| `.Slot.Magazine`    | Magazine / ammo feed                                   |
| `.Slot.Stock`       | Stock / buttstock                                      |
| `.Slot.Barrel`      | Barrel                                                 |
| `.Slot.Handguard`   | Handguard / rail system                                |
| `.Slot.Accessory`   | General accessory (charm, sticker, sling)              |

**Example usage:**

```cpp
// In your weapon Blueprint, add a UModularAttachmentComponent:
// ComponentTag = "ModularAttachment.Slot.Optic"
// → registers the component under that tag in the subsystem
```

### Extending Slots

Add custom slot tags in your project's `DefaultGameplayTags.ini`:

```ini
GameplayTagList=(Tag="ModularAttachment.Slot.SideRail",DevComment="Side-mounted accessory rail.")
GameplayTagList=(Tag="ModularAttachment.Slot.Bayonet",DevComment="Bayonet lug mount point.")
```

## Fragment Tags — `ModularAttachment.Fragment.*`

Used by `UModularAttachmentFragment::FragmentTag` to identify individual fragment instances. Enables tag-based lookup via `GetFragmentByTag()` and selective event routing.

| Tag                       | Purpose                                           |
| ------------------------- | ------------------------------------------------- |
| `.Fragment.Mesh.Static`   | StaticMesh-producing fragment                     |
| `.Fragment.Mesh.Skeletal` | SkeletalMesh-producing fragment                   |
| `.Fragment.VFX`           | Visual effects (particles, Niagara, decals)       |
| `.Fragment.SFX`           | Sound effects (audio components)                  |
| `.Fragment.Stat`          | Stat modifier (damage, recoil, fire rate)         |
| `.Fragment.Animation`     | Animation override / additive layer               |
| `.Fragment.Cosmetic`      | Cosmetic-only (material param, decal, charm)      |
| `.Fragment.Gameplay`      | Gameplay-affecting (ability grant, attribute set) |
| `.Fragment.Widget`        | UI widget (reticle, crosshair, info display)      |

> **Best practice:** Use specific child tags for individual instances rather than reusing the category root. This enables precise `GetFragmentByTag()` queries:
>
> ```ini
> ; Good — specific and queryable
> GameplayTagList=(Tag="ModularAttachment.Fragment.Mesh.Static.ScopeBody",DevComment="Scope body mesh.")
> GameplayTagList=(Tag="ModularAttachment.Fragment.Mesh.Static.ScopeLens",DevComment="Scope lens mesh.")
> ```

## Event Tags — `ModularAttachment.Event.*`

Used in `FAttachmentEventPayload::EventTag` to describe what happened. Broadcast via `UModularAttachmentSubsystem::BroadcastToTag()`.

| Tag                   | Purpose                         | Typical Receivers          |
| --------------------- | ------------------------------- | -------------------------- |
| `.Event.Equipped`     | Attachment loaded and applied   | All fragments on the slot  |
| `.Event.Unequipped`   | Attachment removed / unloaded   | All fragments on the slot  |
| `.Event.Swapped`      | One attachment replaced another | New and old slot fragments |
| `.Event.Aim`          | Aim-down-sights                 | Optic fragments            |
| `.Event.Fire`         | Weapon fired                    | Muzzle, recoil fragments   |
| `.Event.Reload`       | Reload initiated                | Magazine fragments         |
| `.Event.Inspect`      | Inspect / preview triggered     | Cosmetic fragments         |
| `.Event.StateChanged` | Generic state change            | Any — check payload values |

**Example — fire an aim event to all optic components:**

```cpp
FAttachmentEventPayload Payload;
Payload.EventTag  = FGameplayTag::RequestGameplayTag("ModularAttachment.Event.Aim");
Payload.TargetTag = FGameplayTag::RequestGameplayTag("ModularAttachment.Slot.Optic");
Payload.Instigator = this;
Payload.Values.Add(
    FGameplayTag::RequestGameplayTag("ModularAttachment.Value.Zoom"), 4.0f
);

GetWorld()->GetSubsystem<UModularAttachmentSubsystem>()->BroadcastToTag(
    Payload.TargetTag, Payload
);
```

## Value Tags — `ModularAttachment.Value.*`

Keys for the `FAttachmentEventPayload::Values` map (`TMap<FGameplayTag, float>`). Carry named numeric data alongside events.

| Tag                       | Description                         | Example |
| ------------------------- | ----------------------------------- | ------- |
| `.Value.Damage`           | Damage modifier                     | `+15.0` |
| `.Value.RecoilMultiplier` | Recoil multiplier (1.0 = no change) | `0.8`   |
| `.Value.RangeMultiplier`  | Effective range multiplier          | `1.2`   |
| `.Value.AimSpeed`         | ADS speed modifier                  | `0.9`   |
| `.Value.Weight`           | Weight modifier                     | `+0.3`  |
| `.Value.Zoom`             | Optic magnification level           | `4.0`   |

## State Tags — `ModularAttachment.State.*`

Runtime state descriptors. Useful for GAS integration, UI queries, or conditional logic via tag containers.

| Tag              | Meaning                                  |
| ---------------- | ---------------------------------------- |
| `.State.Loading` | Attachment is currently streaming assets |
| `.State.Loaded`  | Attachment fully loaded and applied      |
| `.State.Failed`  | Attachment load failed                   |
| `.State.Empty`   | Slot has no attachment assigned          |

## Adding Custom Tags

You can extend any tag category without modifying the plugin:

### Option A — Project INI

Add to `Config/DefaultGameplayTags.ini`:

```ini
[/Script/GameplayTags.GameplayTagsList]
GameplayTagList=(Tag="ModularAttachment.Slot.CustomSlot",DevComment="My custom slot.")
GameplayTagList=(Tag="ModularAttachment.Event.CustomEvent",DevComment="My custom event.")
```

### Option B — Tag Data Table

Create a `DataTable` with row type `GameplayTagTableRow` and register it in **Project Settings → Gameplay Tags → Gameplay Tag Table List**.

### Option C — C++ Native Tags

```cpp
UE_DEFINE_GAMEPLAY_TAG(TAG_MAS_Slot_Custom, "ModularAttachment.Slot.CustomSlot");
```

## Next Steps

* [Creating Fragments](/dante-docs/modular-attachment-system/creating-fragments.md) — use fragment tags in custom implementations
* [API Reference](/dante-docs/modular-attachment-system/api-reference.md) — `BroadcastToTag()`, `GetComponentsByTag()`, `GetFragmentByTag()`