Skip to content

Gameplay Tags, Actor Tags, and Component Tags

Unreal has several things called "tags." They are all labels, but they do not mean the same thing, search the same place, or scale to the same problems.

The one-minute version

  • Actor Tags are plain Name labels stored on an actor. They are simple and good for small placed-level labels such as Checkpoint_A or Door.
  • Component Tags are plain Name labels stored on components. They label parts of an actor, such as WeakPoint, FootstepSource, or InteractZone.
  • Gameplay Tags are structured hierarchical tags such as Damage.Fire or State.Stunned. They live in a defined tag dictionary and are usually stored in GameplayTag or GameplayTagContainer variables.
  • Get All Actors with Tag searches the world for actor tags. It can return an empty array, and it is still a world search.
  • Get Components by Tag searches one actor's components for component tags and a component class.
  • Has Tag in the Gameplay Tags library checks a Gameplay Tag Container, not the actor's plain tag list.
  • Tags do not grant behavior. A tag can help you find or classify something, but the object still needs an interface, component, function, or data path that implements the behavior.

The three tag systems

Actor Tag:
    BP_Door actor has Tags = ["CheckpointDoor"]

Component Tag:
    DoorMesh component has Component Tags = ["DoorPanel"]
    BoxComponent has Component Tags = ["InteractZone"]

Gameplay Tag:
    StatusTags contains State.Stunned
    DamageTags contains Damage.Fire

The names can look similar, but the storage and query nodes are different.

Label system Stored on Type shape Common query
Actor Tags AActor.Tags Array of Name Actor Has Tag, Get All Actors with Tag
Component Tags UActorComponent.ComponentTags Array of Name Component Has Tag, Get Components by Tag
Gameplay Tags Gameplay tag variables/containers Defined hierarchical tags Has Tag, Has Any, Has All, tag queries

Actor/component tags are lightweight labels. Gameplay Tags are a gameplay classification system with a project dictionary, hierarchy, exact/non-exact matching rules, containers, and query helpers.

Actor Tags

Use actor tags for simple placed-world labels:

  • spawn point group: TeamRed;
  • checkpoint marker: Checkpoint_03;
  • tutorial actor: HighlightTarget;
  • one-off level scripting: BossDoor.

They are easy to add in Details and easy to misuse. A tag named Enemy does not make an actor damageable, replicated, hostile, or part of an AI team. It is just a name in an array.

World searches are the main trap:

BeginPlay
-> Get All Actors with Tag "Checkpoint_03"
-> use first result if array not empty

That can be fine once at setup time. It is a bad Tick pattern because the node searches over actors in the world. If you already have the reference, store or pass it instead of searching again.

Component Tags

Use component tags when the label belongs to a part of an actor:

  • the weak-point mesh on a boss;
  • a footstep source component;
  • a specific collision box named InteractZone;
  • several mesh components that should be hidden together.

Get Components by Tag is called on one actor. It filters that actor's components by component class and tag.

Hit Actor
-> Get Components by Tag
   Component Class = PrimitiveComponent
   Tag = "WeakPoint"
-> For Each returned component

That is not the same as finding actors in the world. If the tag is on a mesh, Get All Actors with Tag will not see it. If the tag is on an actor, Get Components by Tag will not see it unless a component has its own matching component tag.

Gameplay Tags

Gameplay Tags are better when the label is part of game logic instead of a one-off placed-level marker.

Good uses:

  • Damage.Fire, Damage.Ice, Damage.Explosion;
  • State.Stunned, State.Invulnerable, State.Interacting;
  • Item.Weapon.Sword, Item.Consumable.HealthPotion;
  • Ability.Dash, Ability.Block, Ability.Heal.

The hierarchy matters. With non-exact matching, a query for Damage can match Damage.Fire because Damage.Fire is inside the Damage branch. With exact matching, the container must contain the exact tag.

Gameplay Tags need to be defined so the editor and runtime know the legal tag names. For Blueprint-heavy projects, the normal beginner path is Project Settings -> Gameplay Tags, then Gameplay Tag or Gameplay Tag Container variables on the objects that need them.

BP_DamageTypeData
DamageTags = [Damage.Fire]

HealthComponent receives damage
-> Has Tag Damage.Fire?
-> apply fire resistance rules

For many first projects, do not jump straight to complex tag queries. Start with clear tag containers and Has Tag / Has Any.

When tags fail

Failure What it looks like What to check
Wrong tag system Search returns empty even though "the tag is there." Actor tag vs component tag vs Gameplay Tag container.
Typo in plain Name tag Query returns false/empty. Actor/component tags are names; spelling and spaces matter.
Gameplay Tag not defined Editor will not offer it, or data does not match expected tag. Project Settings -> Gameplay Tags or imported tag source.
Empty query input Get All Actors with Tag returns an empty array when no tag is specified. Print the tag value before searching.
World search overused Works in a test map, gets slow/noisy later. Store references, use events, or search once at setup.
Tag expected to grant behavior Object is found but cannot respond. Add interface/component/function behavior separately.

Failure is usually silent: false boolean, empty array, or "found the wrong thing." The fix is to prove where the tag is stored and which query is reading that storage.

The pattern everyone actually uses

Simple placed checkpoint:

Player overlaps checkpoint trigger
-> CheckpointId = "Checkpoint_03"
-> Save plain CheckpointId

Respawn
-> Find Player Start / checkpoint actor for CheckpointId
-> restart player there

Component weak point:

Line Trace hit actor
-> Hit Component
-> Component Has Tag "WeakPoint"
-> if true, multiply damage

Gameplay damage type:

Projectile has GameplayTagContainer DamageTags
    Damage.Fire

HealthComponent ApplyTaggedDamage
-> Has Tag Damage.Fire?
-> use fire resistance
-> broadcast OnHealthChanged

Lookalikes - which one do I want?

Need Use Watch out
Label a placed actor for simple level scripting Actor Tags They are plain names and world search can be slow.
Label a mesh/collider/part inside one actor Component Tags Actor tag queries will not find component tags.
Build scalable gameplay categories Gameplay Tags They need defined tag data and container/query nodes.
Call behavior on unknown object types Blueprint Interface A tag only identifies; it does not create callable functions.
Reuse state/logic across actors Actor Component Tags classify; components implement behavior.
Find all actors of one class Get All Actors Of Class Class search and tag search answer different questions.
Store durable progress IDs in SaveGame Live actor references and tags still need world resolution after load.

Rule of thumb: plain tags are labels on one object or component. Gameplay Tags are a typed vocabulary for gameplay meaning. Neither one replaces references or behavior.

Going deeper