gameplay-tags

Appearance

Dictionaries ​

A dictionary is the global tag catalog: which tags exist, their comments, restricted flags, and redirects. A GameplayTagContainer is the runtime tag set attached to one object. Dictionaries define what is valid; containers carry state.

Importing ​

ts
import {
  GameplayTagSourceType,
  importGameplayTagDictionary,
  validateGameplayTagDictionary
} from "gameplay-tags";

const dictionary = {
  gameplayTagList: [
    { Tag: "Ability.Element.Fire", DevComment: "Fire damage and spell effects" }
  ],
  restrictedGameplayTagList: [
    { Tag: "Character.Internal.DebugOnly", bAllowNonRestrictedChildren: true }
  ],
  gameplayTagRedirects: [
    { OldTagName: "Character.State.OnFire", NewTagName: "Character.State.Burning" }
  ]
};

const validation = validateGameplayTagDictionary(dictionary);
// validation.diagnostics: duplicate tags, invalid names, redirect cycles,
// redirects pointing at missing tags — each with a code and row index.

if (validation.isValid) {
  importGameplayTagDictionary(dictionary, {
    sourceName: "MyTags",
    sourceType: GameplayTagSourceType.TagList
  });
}

Row fields (Tag, DevComment, bAllowNonRestrictedChildren, OldTagName, NewTagName) intentionally keep Unreal's casing so data moves between this package and Unreal projects without renaming.

Redirects ​

Redirects retarget old tag names, including chains:

ts
import { redirectGameplayTagName, requestGameplayTag } from "gameplay-tags";

requestGameplayTag("Character.State.OnFire").getTagName();
// "Character.State.Burning"

redirectGameplayTagName("Character.State.OnFire");
// "Character.State.Burning"

Cycles and over-deep chains are reported as redirect-loop / redirect-chain-too-deep diagnostics during validation.

Exporting and formats ​

ts
const exported = GameplayTagsManager.get().exportGameplayTagDictionary();

stringifyGameplayTagDictionary(exported, "json");
stringifyGameplayTagDictionary(exported, "csv");
stringifyGameplayTagDictionary(exported, "ini"); // DefaultGameplayTags.ini style

const parsed = parseGameplayTagDictionary(iniText, "ini");

The INI format round-trips Unreal's DefaultGameplayTags.ini sections, including quoting, escapes, comments, and restricted tag rows — so a web tool can edit the same file an Unreal project checks in.

Editor metadata ​

Each registered tag tracks where it came from:

ts
GameplayTagsManager.get().getTagEditorData("Ability.Element.Fire");
// { comment, firstTagSource, tagSources, sourceTypes,
//   isTagExplicit, isRestrictedTag, allowNonRestrictedChildren }