Best Practices

Gameplay Tags are most useful when they form a shared vocabulary. The goal is not to tag everything; it is to make gameplay logic easier to read, reuse, and maintain.

Design tags like facts

Good tags read naturally:

This character has Character.State.Stunned.
This attack deals Damage.Type.Fire.
This object belongs to Faction.Enemy.

Prefer a broad-to-specific structure:

Root.Category.Detail

Avoid vague or temporary paths such as Thing.Active, State1, or Temp.New.

Start with strong roots

Root	Possible scope
Character	Actor states, roles, traits, and abilities.
Damage	Damage types, resistances, and immunities.
Faction	Teams, relationships, and targeting.
Interaction	Usable, locked, highlighted, and interactable objects.
Item	Item categories, equipment groups, and pickups.
Quest	Quest categories and states.
World	Environment and level logic.

Add only the roots the project actually needs.

Use hierarchy deliberately

Damage.Type.Fire
Damage.Type.Ice
Damage.Type.Poison

This family supports a broad query for Damage.Type. Flat names such as FireDamage lose that relationship.

Avoid tag spam

Use tags for identity, category, state, and capability. Use variables or data fields for health, damage amount, currency, timers, cooldowns, counts, and object references.

Recommended: Damage.Type.Fire
Not recommended: Damage.Amount.25

Protect stable paths

• Add descriptions to widely shared tags.
• Review new root categories before introducing them.
• Export the repository before large reorganizations.
• Use version control before rename, reparent, import, or delete operations.
• Validate after imports and structural changes.
• Search project assets before deleting a shared tag.

Query efficiently

Prefer:

• querying a known GameplayTagComponent;
• using trigger or collision Events for local interactions;
• filtering with physics layers before tag checks; and
• caching repeated query results when appropriate.

Use scene-wide searches carefully, especially inside per-frame logic.

Review checklist

Before adding a tag, ask:

• Is this a state, identity, category, or capability?
• Will more than one system use it?
• Would a variable express it better?
• Does the path fit the existing hierarchy?
• Would parent matching be useful?
• Will another designer understand the name?