GameplayTags Foundation for Godot

A hierarchical, dot-path GameplayTags implementation for Godot 4 — hashed identifiers with zero runtime string cost once registered, plus a full conditional rules engine (GameplayTagCondition/GameplayTagOperation) for driving gameplay and narrative logic.

• License: Apache 2.0
• Origin: Heathen Group
• Platforms: Windows, Linux, macOS

Extension Resolver This asset uses Extension Resolver to identify missing dependencies and help you install them.

Requirements

• Godot 4.6 or compatible
• godot-cpp, checked out locally, for building from source
• Godot-xxHash (compiled in directly — see Build)
• Godot-Game-Framework, enabled in the consuming project — a runtime dependency, not a build-time one. If it's missing, enabling this plugin walks you through fetching it automatically via Extension Resolver for Godot; see that project's README for how the manifest-driven resolution works.

Become a GitHub Sponsor

Support Heathen by becoming a GitHub Sponsor. Sponsorship directly funds the development and maintenance of free tools like this, as well as our game development Knowledge Base and community on Discord.

Sponsors also get access to our private SourceRepo, which includes developer tools for O3DE, Unreal, Unity, and Godot. Learn more or explore other ways to support @ heathen.group/kb

What it does

GameplayTags Foundation gives you a structured, hierarchy-aware tag system built on these core types:

Tags follow a dot-separated hierarchy. Registering "Effects.Buff.Strength" automatically makes it a descendant of both "Effects.Buff" and "Effects". Hierarchy is stored as parent links compiled to interval (nested-set) encoding — so is_descendant_of is an O(1) range comparison, not a hash-set lookup. This is the algorithm Unity-GameplayTags-Foundation uses, ported here in place of the descendant-hash-set approach the earlier O3DE port shipped with.

GameplayTagCondition and GameplayTagOperation are Resource-derived (not just script-side value types) specifically so they can be authored inline on Ogham Storyteller graph nodes and edited in the Inspector — this is a core dependency for Godot-Ogham-Storyteller-Foundation.

Install

Copy addons/FoundationGameplayTags/ into your project's addons/ folder. Enable the plugin from Project Settings → Plugins.

Author your project's default tags in a GameplayTagsList resource (tags: PackedStringArray), then add FoundationAutoload.tscn as an AutoLoad and assign your list(s) to its tag_lists export — they're registered on _ready(), before any other autoload can query the registry.

Build

Requires godot-cpp and Godot-xxHash checked out locally.

cmake -S addons/FoundationGameplayTags -B addons/FoundationGameplayTags/build \
  -DGODOT_CPP_PATH=/path/to/Godot-cpp \
  -DGODOT_XXHASH_PATH=/path/to/Godot-xxHash
cmake --build addons/FoundationGameplayTags/build

Output lands in addons/FoundationGameplayTags/bin/.

Usage overview

.gptags file format

{
  "registered": true,
  "tags": [ "Shop.Inventory.Money", "Shop.Basket.Total" ]
}

Same JSON schema as Unity-GameplayTags-Foundation's .gptags runtime tag source — a tag list authored for one engine is a plain copy-paste for the other. tags lists only the authored dot-paths; parent segments are implied, not required. registered defaults to false if omitted (Unity's convention for inert/draft tag sets, e.g. unvetted UGC/mod content) — set it true for tags you actually want registered.

Registering tags at runtime

var registry := Engine.get_singleton("GameplayTagRegistry")
registry.register_from_string(
    "Effects.Buff.Strength\n" +
    "Effects.Buff.Speed\n" +
    "Effects.Debuff.Slow\n" +
    "Status.Burning"
)

Use GameplayTagRegistry.validate_tag(name) to check a name before registering it. Intermediate nodes (Effects, Effects.Buff, ...) are inferred automatically.

Hierarchy queries

var strength := registry.hash("Effects.Buff.Strength")
var buff     := registry.hash("Effects.Buff")
var effects  := registry.hash("Effects")

registry.is_descendant_of(strength, buff)    # true
registry.is_descendant_of(strength, effects) # true
registry.is_descendant_of(buff, strength)    # false

Working with collections

var active := GameplayTagCollection.new()

# add_tag stacks — repeated calls increment the count
active.add_tag(registry.hash("Status.Burning"))
active.add_tag(registry.hash("Effects.Buff.Speed"))
active.add_tag(registry.hash("Effects.Buff.Speed")) # now 2

# Presence check — exact_match=false matches the tag or any descendant
var on_fire  := active.contains(registry.hash("Status.Burning"), true)
var any_buff := active.contains(registry.hash("Effects.Buff"), false)

# Numeric values, arithmetic
active.apply(registry.hash("Effects.Buff.Speed"), GameplayTagCollection.ARITHMETIC_ADD, 3)
var speed_stacks := active.get_value(registry.hash("Effects.Buff.Speed")) # 5

# Tags reaching 0 are removed automatically
active.apply(registry.hash("Status.Burning"), GameplayTagCollection.ARITHMETIC_SET, 0)

# Set operations
var required := GameplayTagCollection.new()
required.add_tag(registry.hash("Effects.Buff.Speed"))
required.add_tag(registry.hash("Status.Frozen"))

var has_all := active.contains_all(required, true) # false — Frozen absent
var has_any := active.contains_any(required, true) # true  — Speed present

Conditions and operations

# Condition: "World.PlayerReputation" must be >= 10
var rep_check := GameplayTagCondition.new()
rep_check.tag_name = "World.PlayerReputation"
rep_check.comparison = GameplayTagCondition.COMPARISON_GREATER_EQUAL
rep_check.compare_value = 10

var passed := rep_check.evaluate(active)

# Operation: add 5 to "World.PlayerReputation" if the condition passes
var give_rep := GameplayTagOperation.new()
give_rep.tag_name = "World.PlayerReputation"
give_rep.arithmetic = GameplayTagCollection.ARITHMETIC_ADD
give_rep.value = 5
give_rep.add_condition(rep_check) # optional guard conditions

active.apply_operation(give_rep) # applies only if rep_check passes

# Evaluate a list of conditions with AND/OR/XOR precedence
var conditions: Array[GameplayTagCondition] = [cond_a, cond_b, cond_c]
var result := GameplayTagCondition.evaluate_all(conditions, active)

Per-tag change subscriptions

active.subscribe(registry.hash("Effects.Buff"), func(tag, prev, next):
    print("Buff stack changed: ", prev, " -> ", next), false) # false = also fires for descendants

C# — every type above has a matching wrapper class in Heathen.GameplayTags (GameplayTagRegistry, GameplayTagCollection, GameplayTagCondition, GameplayTagOperation) so C# code never touches Engine.GetSingleton/Variant.Call directly. See the CSharp/ folder.

Public API reference

GameplayTagRegistry (engine singleton)

GameplayTagCollection (RefCounted)

Arithmetic values: ARITHMETIC_SET, ARITHMETIC_ADD, ARITHMETIC_SUBTRACT, ARITHMETIC_MULTIPLY, ARITHMETIC_DIVIDE, ARITHMETIC_MIN, ARITHMETIC_MAX. A result of 0 removes the tag.

GameplayTagCondition (Resource)

Comparison values: COMPARISON_EXISTS, COMPARISON_NOT_EXISTS, COMPARISON_EQUAL, COMPARISON_NOT_EQUAL, COMPARISON_LESS, COMPARISON_LESS_EQUAL, COMPARISON_GREATER, COMPARISON_GREATER_EQUAL, COMPARISON_IS_MEMBER_OF, COMPARISON_IS_PARENT_OF, COMPARISON_IS_EXACTLY.

GameplayTagOperation (Resource)

Editor tooling

Enable the plugin (Project Settings > Plugins) to get:

• Tag-picker Inspector field — any tag_name/*_tag_name String property (including GameplayTagCondition/GameplayTagOperation's own fields) gets a searchable Tree popup instead of a raw text field, built from every .gptags file in the project plus whatever GameplayTagRegistry already knows about. GameplayTagPickerProperty (editor/GameplayTagPickerProperty.gd) is reusable by other addons directly — no compile-time dependency needed, it's a plain global class_name.
• Compact GameplayTagCondition/GameplayTagOperation editors — one row (tag picker + comparison/arithmetic dropdown + value + exact-match toggle) instead of Godot's default multi-line block, since these are commonly embedded several-to-a-list (e.g. Ogham options).
• "GameplayTags" bottom-panel dock — tag tree CRUD over every .gptags file in the project (add/rename/delete, registered/unregistered toggle) — the closest Godot analog to Unity's Project Settings > Subsystems > Gameplay Tags page (Godot has no nested-tab Project Settings equivalent; bottom panels are the native idiom instead).