Skip to content

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 ​

sh
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:

ts
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 ​

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