#Scripting API

Gameplay Tags are designed for Game Creator workflows first, but the runtime API is also available for custom C# systems.

Use this page as a practical reference for common scripting tasks. It intentionally focuses on public-facing runtime APIs instead of internal editor implementation details.

using SkywardGames.Runtime.GameplayTags;

#Common Tasks

Task	API
Create a tag from a path	`GameplayTag.FromPath("Damage.Type.Fire")`
Add a tag to an object	`GameplayTagComponent.AddTag(tag)`
Remove a tag from an object	`GameplayTagComponent.RemoveTag(tag)`
Check a known object	`HasTag` or `HasGameplayTag`
Check a parent category	`TagMatchMode.IncludeChildren`
Find active tagged objects	`GameplayTagObjectQuery.FindAll`
Validate the database	`GameplayTagRegistry.Validate()`

#GameplayTag

GameplayTag represents one tag path.

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

Useful members:

Member	Use
`Path`	Full tag path.
`Guid`	Stored tag GUID when available.
`IsNone`	True when the tag is empty.
`IsValid`	True when the tag is empty or defined in the registry.
`Parent`	Parent path as a `GameplayTag`.
`None`	Empty tag value.
`FromPath(string)`	Creates a tag from a path.
`Matches(GameplayTag, TagMatchMode)`	Checks this tag against another tag.
`IsChildOf(GameplayTag)`	Checks whether this tag is below another tag.
`IsParentOf(GameplayTag)`	Checks whether this tag is above another tag.

#Example: Parent Matching

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

bool matches = owned.Matches(query, TagMatchMode.IncludeChildren);

#GameplayTagContainer

GameplayTagContainer stores multiple tags.

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

Useful members:

Member	Use
`Count`	Number of tags.
`IsEmpty`	True when no tags are stored.
`Tags`	Read-only tag list.
`Add(GameplayTag)`	Adds a tag if it is not empty or duplicated.
`Remove(GameplayTag)`	Removes a tag.
`Clear()`	Removes all tags.
`HasTag(GameplayTag, TagMatchMode)`	Checks one tag.
`HasAny(GameplayTagContainer, TagMatchMode)`	Checks if any query tag matches.
`HasAll(GameplayTagContainer, TagMatchMode)`	Checks if every query tag matches.
`Union(GameplayTagContainer)`	Returns a combined container.
`Intersect(GameplayTagContainer)`	Returns shared exact tags.
`Copy()`	Returns a copy.
`EqualsExact(GameplayTagContainer)`	Checks exact container equality.

#Example: Required Tags

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

bool canTarget = tags.HasAll(required, TagMatchMode.Exact);

#GameplayTagComponent

GameplayTagComponent attaches runtime tags to a GameObject.

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

Useful members:

Member	Use
`RuntimeTags`	Component tag container.
`Tags`	Alias for the component tag container.
`PrimaryTag`	First tag in the container, or `None`.
`IsSingleTagMode`	True when the component is in Single Tag mode.
`HasTag(GameplayTag, TagMatchMode)`	Checks this component.
`AddTag(GameplayTag)`	Adds a tag.
`TryAddTag(GameplayTag, out bool replacedExisting)`	Adds a tag and reports replacement in Single Tag mode.
`RemoveTag(GameplayTag)`	Removes a tag.
`ClearTags()`	Clears all tags.
`SetTags(GameplayTagContainer, bool)`	Replaces the container.
`SetPrimaryTag(GameplayTag)`	Sets the primary tag.
`RestoreFromPaths(string[])`	Restores tags from path strings.

Events:

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

#Example: React to a Tag

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");
        }
    }
}

#GameObject Extensions

Use extension methods when you already have a GameObject.

bool isEnemy = target.HasGameplayTag(
    GameplayTag.FromPath("Faction.Enemy"),
    TagMatchMode.Exact
);

Method	Use
`TryGetGameplayTags(out GameplayTagContainer)`	Gets tags from a `GameplayTagComponent`.
`HasGameplayTag(GameplayTag, TagMatchMode)`	Checks for a matching tag.
`AddGameplayTag(GameplayTag)`	Adds a tag through the component.
`RemoveGameplayTag(GameplayTag)`	Removes a tag through the component.

#GameplayTagObjectQuery

Use GameplayTagObjectQuery for scene-level searches.

GameObject firstEnemy = GameplayTagObjectQuery.FindFirst(
    GameplayTag.FromPath("Faction.Enemy"),
    GameplayTagEventMatch.Exact
);

Method	Use
`Matches(GameplayTagContainer, GameplayTag, GameplayTagEventMatch)`	Checks a container using event match options.
`Matches(GameObject, GameplayTag, GameplayTagEventMatch)`	Checks a GameObject.
`FindFirst(GameplayTag, GameplayTagEventMatch)`	Finds the first active matching GameObject.
`FindAll(GameplayTag, GameplayTagEventMatch, List<GameObject>)`	Fills a list with active matching GameObjects.

Performance Note
FindFirst and FindAll search active GameplayTagComponent instances in the scene. Use them for occasional queries, not per-frame global scans in large scenes.

#GameplayTagRegistry

GameplayTagRegistry provides lookup, matching, hierarchy, redirect resolution, and validation.

Method	Use
`RebuildCache()`	Rebuilds runtime lookup data.
`IsDefined(string)`	Checks whether a path exists in the tag database.
`TryGetDefinition(string, out GameplayTagDefinition)`	Gets metadata for a path.
`Resolve(GameplayTag)`	Resolves redirects for a tag.
`Matches(GameplayTag, GameplayTag, TagMatchMode)`	Checks matching with redirects.
`GetParents(GameplayTag)`	Gets parent tags.
`GetChildren(GameplayTag)`	Gets direct child tags.
`GetDescendants(GameplayTag)`	Gets all descendant tags.
`Validate()`	Returns validation issue strings.

#Example: Validate the Database

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

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

#GameplayTagService

GameplayTagService is a helper for setting and mutating tags with redirect resolution and development warnings.

Method	Use
`SetTag(GameplayTag)`	Resolves a tag and warns for undefined tags in Editor/development builds.
`AddTag(GameplayTagContainer, GameplayTag)`	Adds a resolved tag to a container.
`RemoveTag(GameplayTagContainer, GameplayTag)`	Removes a resolved tag from a container.
`SetTags(GameplayTagContainer, GameplayTagContainer)`	Replaces one container with another.

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

#Enums

#TagMatchMode

TagMatchMode.Exact
TagMatchMode.IncludeChildren

Use this for tag and container matching.

#GameplayTagEventMatch

GameplayTagEventMatch.Any
GameplayTagEventMatch.Exact
GameplayTagEventMatch.IncludeChildren

Use this for object queries and Game Creator event-style matching.

#Recommended Patterns

#Check a Broad Category

bool isAnyDamageType = target.HasGameplayTag(
    GameplayTag.FromPath("Damage.Type"),
    TagMatchMode.IncludeChildren
);

#Add and Remove a Temporary State

GameplayTag stunned = GameplayTag.FromPath("Character.State.Stunned");

component.AddTag(stunned);
component.RemoveTag(stunned);

#Find Active Enemies

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

GameplayTagObjectQuery.FindAll(
    GameplayTag.FromPath("Faction.Enemy"),
    GameplayTagEventMatch.Exact,
    enemies
);