/ue-gameplay-tags-messaging

name: ue-gameplay-tags-messaging
description: "Use when defining, querying or replicating Gameplay Tags, or wiring decoupled event messaging between gameplay systems in C++. Also use when the user mentions 'FGameplayTag', 'FGameplayTagContainer', 'FGameplayTagQuery', 'UE_DEFINE_GAMEPLAY_TAG', 'native gameplay tag', 'DefaultGameplayTags.ini', 'GameplayTagList', 'tag redirect', 'MatchesTag', 'HasTagExact', 'RequestGameplayTag', 'UGameplayTagsManager', 'Categories meta', 'tag picker', 'gameplay message', 'message bus', 'event bus' or 'AsyncMessageSystem'. For abilities, effects and cues that consume tags, see ue-gameplay-abilities; for wire cost and RPCs, see ue-networking-replication."
metadata:
  version: "2.0.0"
  engine: "5.8"

UE Gameplay Tags and Messaging

Target engine: **UE 5.8**. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

Gameplay Tags are a built-in runtime module, not a plugin: add `"GameplayTags"` to `PublicDependencyModuleNames` in your `Build.cs` and include `GameplayTagContainer.h` / `NativeGameplayTags.h` / `GameplayTagsManager.h`. This skill owns tag definition (native and ini), `FGameplayTag`, `FGameplayTagContainer`, `FGameplayTagQuery`, `UGameplayTagsManager`, editor filtering, and decoupled gameplay messaging — including the `AsyncMessageSystem` plugin (Experimental in 5.8).

Context

Read `.agents/ue-project-context.md` if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

| Request is about… | Go to | |---|---| | Declaring tags in C++, native tag macros, module setup | [Native Tag Definitions](#native-tag-definitions) | | Declaring tags in `.ini`, data tables, renaming a tag | [Ini and Data Table Tag Sources](#ini-and-data-table-tag-sources) | | Testing a tag, container membership, parent vs exact | [Matching Semantics](#matching-semantics) | | Multi-tag conditions, AND/OR/NOT, designer-authored rules | [Tag Queries](#tag-queries) | | Actors exposing tags, gates and states built from tags | [Tag-Driven Design](#tag-driven-design) | | Sending tags over the network, tag cost, hot paths | [Replication and Performance](#replication-and-performance) | | Broadcasting events between systems without hard references | [Decoupled Messaging](#decoupled-messaging) | | Tag pickers, `Categories` filtering, per-team tag files | [Editor UX and Filtering](#editor-ux-and-filtering) |

Tag Sources

A tag must be registered before it can be requested. Four sources feed the one global dictionary held by `UGameplayTagsManager`:

| Source | Where | Use for | |---|---|---| | Native | `UE_DEFINE_GAMEPLAY_TAG*` in a module `.cpp` | Tags C++ compares against by name | | Default ini | `Config/DefaultGameplayTags.ini`, `+GameplayTagList=` | Tags authored by designers | | Extra ini | `Config/Tags/*.ini` and plugin config dirs | Per-team or per-plugin tag lists | | Data table | `UDataTable` of `FGameplayTagTableRow` listed in `GameplayTagTableList` | Bulk import from a spreadsheet |

`EGameplayTagSourceType` (`Native`, `DefaultTagList`, `TagList`, `RestrictedTagList`, `DataTable`, `Invalid`) names these in the editor. Tags are hierarchical: registering `MyGame.State.Stunned` implicitly registers `MyGame.State` and `MyGame`.

Native Tag Definitions

Declare in a public header, define in exactly one `.cpp` of the same module. The macros `static_assert` that they are used from a `.cpp`.

// MyGameplayTags.h
#pragma once

#include "NativeGameplayTags.h"

MYGAME_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_MyGame_State_Stunned);
MYGAME_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_MyGame_Damage_Fire);
MYGAME_API UE_DECLARE_GAMEPLAY_TAG_EXTERN(TAG_MyGame_Message_ScoreChanged);

// MyGameplayTags.cpp
#include "MyGameplayTags.h"

UE_DEFINE_GAMEPLAY_TAG_COMMENT(TAG_MyGame_State_Stunned, "MyGame.State.Stunned", "Character cannot act");
UE_DEFINE_GAMEPLAY_TAG_COMMENT(TAG_MyGame_Damage_Fire, "MyGame.Damage.Fire", "Fire damage channel");
UE_DEFINE_GAMEPLAY_TAG_COMMENT(TAG_MyGame_Message_ScoreChanged, "MyGame.Message.ScoreChanged", "Score changed broadcast");

| Macro | Parameters | Effect | |---|---|---| | `UE_DECLARE_GAMEPLAY_TAG_EXTERN` | `(TagName)` | `extern FNativeGameplayTag TagName;` — goes in the header, prefixed with your `_API` macro | | `UE_DEFINE_GAMEPLAY_TAG` | `(TagName, Tag)` | Defines the variable with an empty dev comment | | `UE_DEFINE_GAMEPLAY_TAG_COMMENT` | `(TagName, Tag, Comment)` | Same plus a developer comment shown in the editor | | `UE_DEFINE_GAMEPLAY_TAG_STATIC` | `(TagName, Tag)` | `static` — visible only inside that one `.cpp`, with no matching declaration in a header |

`Tag` and `Comment` are bare string literals: the macro wraps `Comment` in `TEXT()` itself. Writing `TEXT("…")` there does not compile.

`FNativeGameplayTag` registers on static construction and unregisters when the module unloads, so tags from a plugin disappear cleanly with the plugin. It converts implicitly to `FGameplayTag` and also exposes `GetTag()`:

const FGameplayTag Stunned = TAG_MyGame_State_Stunned.GetTag();
if (OwnedTags.HasTag(TAG_MyGame_State_Stunned))
{
    return;
}

**One definition rule:** exactly one `UE_DEFINE_GAMEPLAY_TAG` (or `_COMMENT` / `_STATIC`) per tag variable per binary. Two modules defining the same tag string is fine (the manager reference-counts registrations), but two definitions of the same *variable* is a link error, and a definition in a header breaks every translation unit that includes it.

To register a tag whose name is only known at runtime, call the manager directly:

const FGameplayTag Runtime = UGameplayTagsManager::Get().AddNativeGameplayTag(
    FName(TEXT("MyGame.Generated.Slot01")), TEXT("Gene