#Scripting API

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

Use this page as a practical reference for common scripting tasks across tags, containers, components, reactions, and queries.

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`
Mutate a reaction at runtime	`reaction.SetGameplayTag(...)` / `reaction.Cancel()`
Non-allocating query (including inactive)	`GameplayTagComponent.GetAllComponentsNonAlloc(...)`
Validate the database	`GameplayTagRegistry.Validate()`

#GameplayTag

GameplayTag represents a single tag path.

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

Member	Use
`Path`	Full tag path string.
`Guid`	Stored tag GUID when available.
`IsNone`	True when the tag is empty.
`IsValid`	True when defined in the tag registry.
`Parent`	Parent path as a `GameplayTag`.
`None`	Empty tag value.
`FromPath(string)`	Creates a tag from a path string.
`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.

#GameplayTagContainer

GameplayTagContainer stores multiple tags with automatic sorting and duplicate handling.

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

Member	Use
`Count`	Number of tags.
`IsEmpty`	True when no tags are stored.
`Tags`	Read-only tag list.
`Add(GameplayTag)`	Adds a tag if 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.

#GameplayTagComponent

GameplayTagComponent attaches runtime tags to a GameObject and integrates with the active lifecycle registry.

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

#Global Lifecycle Events

// Static component registry events:
GameplayTagComponent.EventCreated += comp => { ... };
GameplayTagComponent.EventRegistered += comp => { ... };
GameplayTagComponent.EventUnregistered += comp => { ... };
GameplayTagComponent.EventDestroying += comp => { ... };
GameplayTagComponent.EventComponentTagsChanged += (comp, tag) => { ... };

#Dual-Registry Non-Allocating Discovery

List<GameplayTagComponent> results = new List<GameplayTagComponent>();

// Retrieve active components without allocations:
GameplayTagComponent.GetAllComponentsNonAlloc(results, includeInactive: false);

// Retrieve all components including disabled/pooled:
GameplayTagComponent.GetAllComponentsNonAlloc(results, includeInactive: true);

#GameplayTagReaction

You can configure, trigger, or cancel GameplayTagReaction instances from code:

using SkywardGames.Runtime.GameplayTags;

// Dynamically mutate reaction filter and timing:
reaction.SetGameplayTag(GameplayTag.FromPath("Unit.Enemy.Elite"));
reaction.SetMatch(GameplayTagMatchMode.Exact);
reaction.SetWhen(GameplayTagReactionType.TaggedGameObjectStartsMatching);
reaction.SetExecution(GameplayTagReactionExecutionMode.Simultaneous);
reaction.SetDelay(GameplayTagReactionStartupDelayMode.NextFrame, 0f);
reaction.SetPersistAcrossScenes(true);

// Manual execution and queue controls:
reaction.ExecuteManual(targetGameObject);
reaction.Cancel(); // Cancels running execution and clears pending queue

// Reset back to inspector authored defaults:
reaction.ResetRuntimeStateToDefaults();

#GameObject Extensions

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

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

Method	Use
`FindFirst(GameplayTag, GameplayTagEventMatch)`	Finds the first active matching GameObject.
`FindAll(GameplayTag, GameplayTagEventMatch, List<GameObject>)`	Fills a list with active matching GameObjects.
`FindClosest(GameplayTag, GameplayTagEventMatch, Vector3, float)`	Finds the closest matching GameObject within distance.