Core Concepts

Gameplay Tags are structured labels that describe gameplay meaning:

Character.State.Stunned
Damage.Type.Fire
Faction.Enemy
Quest.Main.Completed
Interaction.Usable.Door

Dot-separated paths

Each segment narrows the meaning:

Damage
Damage.Type
Damage.Type.Fire

Damage is broad; Damage.Type.Fire is specific. A path must not be empty, begin or end with a dot, contain double dots, contain /, or contain an empty segment.

Hierarchy

The hierarchy supports both organization and matching:

Character
Character.State
Character.State.Stunned
Character.State.Burning
Character.State.Frozen

Use Exact when the complete paths must be equal. Use Include Children when a parent query should also accept an owned descendant.

Mode	Query behavior
Exact	Damage.Type.Fire matches only Damage.Type.Fire.
Include Children	A query for Damage.Type matches an owned Damage.Type.Fire.

Directional matching

Include Children broadens the query, not the owned tag. An owned Damage.Type.Fire matches a query for Damage.Type; an owned Damage.Type does not match a query for Damage.Type.Fire.

In the C# API, exact: true selects exact matching and exact: false selects the parent-query behavior described above.

Gameplay Tags and Unity Tags

Unity Tags	Gameplay Tags
One flat tag per GameObject	Multiple hierarchical tags per object or container
Useful for Unity-level categories	Useful for gameplay state and classification
No parent/child matching	Exact and parent-query matching

Use Unity Tags when Unity or another asset explicitly expects them. Use Gameplay Tags when systems need reusable, hierarchical gameplay meaning.

Gameplay Tags and variables

Tags classify; variables store values.

Use Gameplay Tags for:

• state such as Character.State.Stunned;
• faction such as Faction.Enemy;
• damage identity such as Damage.Type.Fire; and
• interaction categories such as Interaction.Usable.Door.

Use variables for:

• health, stamina, currency, and other quantities;
• timers and cooldowns;
• positions and object references; and
• progress values or user-facing text.

Rule of thumb

If the data needs math, ordering, or a range, use a variable. If it describes identity, category, state, or capability, consider a Gameplay Tag.

Examples of tag families

Character.State.Stunned
Character.State.Invulnerable
Faction.Player
Faction.Enemy
Damage.Type.Fire
Damage.Resistance.Fire
Quest.Main.Active
Quest.Main.Completed
Interaction.Usable
Interaction.Usable.Door