Getting started

gameplay-tags brings Unreal Engine's Gameplay Tags model to TypeScript and JavaScript: hierarchical dot-separated tags, tag containers with parent-aware matching, serializable queries, and portable tag dictionaries.

Install

npm install gameplay-tags

The package ships ESM and CJS builds with TypeScript types. Node 18+ and all modern bundlers are supported.

First tags

Tags live in a global registry managed by GameplayTagsManager. Register the tags your application knows about, then build containers for the objects that carry them:

import {
  GameplayTagsManager,
  makeGameplayTagContainer,
  requestGameplayTag
} from "gameplay-tags";

const manager = GameplayTagsManager.get();

manager.addNativeGameplayTag("Ability.Element.Fire");
manager.addNativeGameplayTag("Character.Class.Mage");

const owned = makeGameplayTagContainer([
  "Ability.Element.Fire",
  "Character.Class.Mage"
]);

owned.hasTag(requestGameplayTag("Ability.Element"));      // true — hierarchical
owned.hasTagExact(requestGameplayTag("Ability.Element")); // false — exact only

Registering Ability.Element.Fire implicitly creates the parent tags Ability.Element and Ability, exactly like Unreal's tag tree.

Where to go next

• Tags and containers — matching, filtering, and serialization.
• Dictionaries — importing and exporting tag catalogs (JSON, CSV, INI).
• Queries — building, persisting, and evaluating tag queries.
• Unreal API mapping — finding the equivalent of an Unreal API.

Runnable versions of every guide live in the repository under examples/.