ue-gameplay-tags-messaging
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.
quodsoler · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add quodsoler/unreal-engine-skills --skill 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 |
Declaring tags in .ini, data tables, renaming a tag | Ini and Data Table Tag Sources |
| Testing a tag, container membership, parent vs exact | Matching Semantics |
| Multi-tag conditions, AND/OR/NOT, designer-authored rules | Tag Queries |
| Actors exposing tags, gates and states built from tags | Tag-Driven Design |
| Sending tags over the network, tag cost, hot paths | Replication and Performance |
| Broadcasting events between systems without hard references | Decoupled Messaging |
Tag pickers, Categories filtering, per-team tag files | 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
阅读完整来源 ↗