C# API

Import the runtime namespace:

using SkywardGames.Runtime.GameplayTags;

This page documents the current public runtime signatures. Obsolete enum-based examples are omitted.

GameplayTag

GameplayTag represents one normalized path:

GameplayTag fire = GameplayTag.FromPath("Damage.Type.Fire");

Member	Purpose
`Path`	Full normalized tag path.
`Guid`	Stored tag GUID when available.
`IsNone`	Whether the path is empty.
`IsValid`	Whether the value is empty or defined in the registry.
`Parent`	Parent path as a `GameplayTag`.
`None`	Empty tag value.
`FromPath(string)`	Create a tag from a path.
`Matches(GameplayTag, bool)`	Match this owned tag against a query.
`IsChildOf(GameplayTag)`	Check whether this tag is below another tag.
`IsParentOf(GameplayTag)`	Check whether this tag is above another tag.

Parent matching:

GameplayTag owned = GameplayTag.FromPath("Damage.Type.Fire");
GameplayTag query = GameplayTag.FromPath("Damage.Type");

bool matches = owned.Matches(query, exact: false);

GameplayTagContainer

Create a container:

GameplayTagContainer tags = new GameplayTagContainer(
    GameplayTag.FromPath("Faction.Enemy"),
    GameplayTag.FromPath("Character.State.Burning")
);

Member	Purpose
`Count`	Number of stored tags.
`IsEmpty`	Whether no tags are stored.
`Tags`	Read-only tag list.
`Add(GameplayTag)`	Add and normalize a non-empty tag.
`Remove(GameplayTag)`	Remove a tag and its stored descendants.
`Clear()`	Remove all tags.
`HasTag(GameplayTag, bool)`	Query one tag.
`HasAny(GameplayTagContainer, bool)`	Require at least one query match.
`HasAll(GameplayTagContainer, bool)`	Require every query match.
`Union(GameplayTagContainer)`	Return a combined container.
`Intersect(GameplayTagContainer)`	Return exact tags shared by both containers.
`Copy()`	Return a defensive copy.
`EqualsExact(GameplayTagContainer)`	Compare normalized complete sets.
`NormalizeAndSort()`	Resolve, reduce, and sort the stored tags.

Require two exact tags:

GameplayTagContainer required = new GameplayTagContainer(
    GameplayTag.FromPath("Faction.Enemy"),
    GameplayTag.FromPath("Character.State.Burning")
);

bool canTarget = tags.HasAll(required, exact: true);

Containers avoid redundant ancestry. Adding a descendant removes a stored parent; adding a parent when one of its descendants is already stored does not change the container.

GameplayTagComponent

Get a component and mutate it through its public methods:

GameplayTagComponent component = GetComponent<GameplayTagComponent>();
GameplayTag usable = GameplayTag.FromPath("Interaction.Usable");

component.AddTag(usable);
bool isUsable = component.HasTag(usable, exact: true);
component.RemoveTag(usable);

Member	Purpose
`RuntimeTags`, `Tags`, `GetTagsCopy()`	Return a defensive copy of current tags.
`PrimaryTag`	First stored tag, or `None`.
`IsSingleTagMode`	Whether the component is in Single Tag mode.
`TagCount`	Number of stored tags.
`HasTag(GameplayTag, bool)`	Query component state.
`AddTag(GameplayTag)`	Add a tag.
`TryAddTag(GameplayTag, out bool)`	Add and report whether Single Tag mode replaced a value.
`RemoveTag(GameplayTag)`	Remove a tag.
`ClearTags()`	Remove every tag.
`SetTags(GameplayTagContainer, bool)`	Replace component state.
`SetPrimaryTag(GameplayTag)`	Replace state with one primary tag.
`RestoreFromPaths(string[])`	Restore tags from serialized paths.

The second SetTags argument exists for source compatibility and defaults to true; use the one-argument call unless maintaining older caller code requires the full signature.

Listen for changes

using SkywardGames.Runtime.GameplayTags;
using UnityEngine;

public class StunWatcher : MonoBehaviour
{
    private static readonly GameplayTag Stunned =
        GameplayTag.FromPath("Character.State.Stunned");

    private GameplayTagComponent tags;

    private void Awake()
    {
        tags = GetComponent<GameplayTagComponent>();
    }

    private void OnEnable()
    {
        tags.EventTagAdded += OnTagAdded;
    }

    private void OnDisable()
    {
        tags.EventTagAdded -= OnTagAdded;
    }

    private void OnTagAdded(GameplayTag tag)
    {
        if (tag == Stunned)
        {
            Debug.Log("Character is stunned");
        }
    }
}

Component events are:

component.EventTagsChanged += OnTagsChanged;
component.EventTagAdded += OnTagAdded;
component.EventTagRemoved += OnTagRemoved;

GameObject extensions

Extension methods inspect a GameplayTagComponent on the GameObject or its parent:

GameplayTag enemy = GameplayTag.FromPath("Faction.Enemy");
bool isEnemy = target.HasGameplayTag(enemy, exact: true);

Method	Purpose
`TryGetGameplayTags(out GameplayTagContainer)`	Return a defensive copy of the found component’s tags.
`HasGameplayTag(GameplayTag, bool)`	Query the found component.
`AddGameplayTag(GameplayTag)`	Add through the found component.
`RemoveGameplayTag(GameplayTag)`	Remove through the found component.
`FindGameplayTagComponent(GameObject)`	Find the component on the object or its parent.

GameplayTagObjectQuery

Object queries inspect active, enabled GameplayTagComponent instances:

using System.Collections.Generic;
using UnityEngine;

List<GameObject> enemies = new List<GameObject>();

GameplayTagObjectQuery.FindAll(
    GameplayTag.FromPath("Faction.Enemy"),
    exact: true,
    results: enemies
);

Method	Purpose
`Matches(GameplayTagContainer, GameplayTag, bool)`	Test a container.
`Matches(GameObject, GameplayTag, bool)`	Test a GameObject.
`FindFirst(GameplayTag, bool)`	Return the first active match.
`FindAny(GameplayTag, bool)`	Alias for `FindFirst`.
`FindAll(GameplayTag, bool, List<GameObject>)`	Replace a result list with active matches.

An empty query tag matches any non-empty container. Use global queries occasionally rather than every frame in large scenes.

GameplayTagRegistry

The registry owns lookup, redirect resolution, hierarchy caches, matching, and validation.

Method	Purpose
`RebuildCache()`	Rebuild runtime lookup and hierarchy data.
`IsDefined(string)`	Check whether a normalized path is defined.
`TryGetDefinition(string, out GameplayTagDefinition)`	Read metadata by path.
`TryGetDefinitionByGuid(string, out GameplayTagDefinition)`	Read metadata by GUID.
`FindByGuid(string)`	Return a tag for a known GUID.
`TryResolve(GameplayTag, out GameplayTag)`	Resolve a current definition, redirect, or GUID.
`Resolve(GameplayTag)`	Resolve when possible; otherwise return the input.
`Matches(GameplayTag, GameplayTag, bool)`	Match an owned tag against a query.
`GetParents(GameplayTag)`	Return ancestor tags.
`GetChildren(GameplayTag)`	Return direct children.
`GetDescendants(GameplayTag)`	Return all descendants.
`Validate()`	Return repository issue strings.

using System.Collections.Generic;

IReadOnlyList<string> issues = GameplayTagRegistry.Validate();

foreach (string issue in issues)
{
    Debug.LogWarning(issue);
}

GameplayTagService

The service resolves redirects and emits development warnings for undefined values:

Method	Purpose
`SetTag(GameplayTag)`	Resolve one tag and warn when undefined.
`AddTag(GameplayTagContainer, GameplayTag)`	Add a resolved tag.
`RemoveTag(GameplayTagContainer, GameplayTag)`	Remove a resolved tag.
`SetTags(GameplayTagContainer, GameplayTagContainer)`	Replace one container from another.

GameplayTagContainer state = new GameplayTagContainer();

GameplayTagService.AddTag(
    state,
    GameplayTag.FromPath("Character.State.Stunned")
);