`gameplay_tags`

AI & gameplay Experimental

Gameplay tag registry and tag-query authoring.

What it’s for

Gameplay tags are the hierarchical labels (Ability.Attack.Melee, State.Debuff.Stunned) that GAS and much of Lyra-style gameplay code branch on. This namespace lets your assistant read and edit that tag registry, and author the tag queries that filter on it, without you opening the Project Settings tag manager by hand.

Use it to list the tags currently defined (filtered by prefix or by the INI source they live in), to add or remove explicit tags on an INI-backed source, and to register a new INI source to hold them. When code or a designer needs a match rule rather than a single tag, it also builds an FGameplayTagQuery from a JSON expression tree and can write that query straight into a target asset property.

Reach for this when the change is about the tag vocabulary or a query expression. Reading or writing the tag values already set on a specific actor or component is a job for the asset and Blueprint namespaces instead.

This area is experimental and still improving. Method names and parameter shapes can change between releases, so confirm the current signature before you lean on it in a script.

Examples

See which tags exist under a prefix

Ask what is already registered before you add anything, so you match the existing naming.

You: List every gameplay tag under Ability.Attack.

  call("gameplay_tags.list", {prefix:"Ability.Attack"})
    → {tags:[{tag:"Ability.Attack.Melee", source:"DefaultGameplayTags.ini", explicit:true}, ...], totalMatches:6}

Done. Found 6 tags under Ability.Attack.

Register a new explicit tag

Add a tag to an INI source, with a developer comment recorded alongside it.

You: Add Ability.Attack.Charged to the game tags with a note.

  call("gameplay_tags.add", {tag:"Ability.Attack.Charged", source:"DefaultGameplayTags",
        comment:"Hold-to-charge heavy attack"})
    → {ok:true, tag:"Ability.Attack.Charged", source:"DefaultGameplayTags.ini"}

Done. Added Ability.Attack.Charged to DefaultGameplayTags.ini.

Build a tag query and write it into an asset

Compile a match rule from an expression tree and store it on a target property in one step.

You: On BP_Buff, require any of the Stunned or Rooted state tags.

  call("gameplay_tags.build_query", {expression:{op:"AnyTagsMatch",
        tags:["State.Debuff.Stunned", "State.Debuff.Rooted"]},
        target:{assetPath:"/Game/BP_Buff", propertyPath:"RequiredTags"},
        description:"Applies while stunned or rooted"})
    → {ok:true, queryDescription:"ANY(State.Debuff.Stunned, State.Debuff.Rooted)", wrote:true}

Done. Query written to BP_Buff.RequiredTags.

← Back to all namespaces