📘 Tags System Documentation (Godot G.A.S. Plugin)

🔹 Overview

The Tag System in the Godot G.A.S. (Gameplay Ability System) plugin is designed to mimic Unreal Engine’s flexible gameplay tag architecture while conforming to Godot standards. Tags are used throughout the system for:

• Ability activation requirements
• Effect targeting/filtering
• Cooldown tagging
• Attribute regeneration filtering
• Gameplay Cues identification
• And more…

Tags are human-readable hierarchical labels like State.Movement.Slowed and are used both for developer tooling and runtime logic.

🔹 Tag Categories and Structure

Tags are organized into Categories, shown in the editor as a collapsible tree.

⚠ Reserved Categories

The following categories are built-in, required, and cannot be edited or deleted:

• Uncategorized
• Ability
• Effect
• State
• Event
• Attributes

These are rendered with a blue star icon instead of the standard folder icon.

Any attempt to edit/delete these categories in the Tag Manager is blocked both visually and functionally.

🔹 Tag Creation and Editing

When creating a tag:

• Display Name is entered by the user.
• Tag Name is automatically derived from the Display Name in PascalCase (e.g. stunned → Stunned).
• Tag Name is now an internal field only and not exposed in the inspector.

Tags are stored in the centralized GameplayTags singleton (addons/GAS/resources/gameplay_tags.gd) and serialized in the gameplay_tags.tres file (addons/GAS/settings/gameplay_tags.tres).

Each tag stores:

• display_name – shown in editor dropdowns
• category – which determines tag hierarchy (e.g., State)
• is_cue – a boolean used to mark the tag as a gameplay cue

🔹 Gameplay Cues

Tags can be marked as Cues using the Is Cue checkbox when creating/editing a tag. Cue tags are used to trigger VFX, SFX, and other gameplay feedback systems.

Cue tags are never allowed in the "Cue" category to prevent duplicate prefixing (Cue.Cue.TagName).

🔹 Integration with Other Systems

🔸 GameplayTagsComponent

This runtime component is used by actors (e.g., characters, enemies, abilities) to store and manage their current active tags.

Key features:

• Add/Remove tags at runtime
• Query tags (has, matches, includes)
• Emits signals when tags change

var active_tages: Array[String] = []

@export var active_tags_gas_taglist: Array[String] = []:
	set(value):
		active_tags = value
		active_tags_gas_taglist = active_tags
	get:
		return active_tags

This setup allows you to edit tags via a dropdown in the Inspector using the _gas_taglist suffix, while keeping the actual logic and runtime tag data in the active_tags array.

At runtime, all tag systems (Attributes, Cues, Abilities) access the internal list using:

get_node("GameplayTagsComponent").get_gameplay_tags()

This ensures separation between editor tooling and runtime logic while maintaining consistency.

You can also manually add, remove, or query tags (Although not advised):

tags_component.add_tag("State.Stunned")
tags_component.remove_tag("State.Stunned")
if tags_component.has_tag("State.Stunned"):
	print("Entity is stunned!")

⚠️ Note: Only use tags from your configured Tag System. All tags should match exactly as defined in the gameplay_tags.tres resource.

🔹 Inspector Dropdowns: _gas_taglist Suffix

To enable dropdown rendering in the Inspector for selecting tags:

• Append _gas_taglist to any exported Array[String] or String property name.

@export var required_tags_gas_taglist: Array[String] = []
@export var ability_cue_gas_taglist: String = ""

This suffix tells the plugin to render a custom dropdown linked to the current global GameplayTags list, supporting both single- and multi-select dropdowns.

These dropdowns:

• Auto-refresh when tags change
• Support per-element editing (for arrays)
• Filter disabled/invalid tags visually

🔹 Tag Validation and Caching

Tag names are validated:

• Must be PascalCase
• Must not conflict with existing tags
• Must not include illegal characters or whitespace
• Empty or duplicate names are blocked

Internally, the system maintains a cached flat tag list (e.g., State.Movement.Slowed) for quick lookup and dropdown population.

🔹 File Structure

Key files involved in the Tag System:

• addons/GAS/resources/gameplay_tags.gd – Core singleton logic
• addons/GAS/settings/gameplay_tags.tres – Saved tag data
• addons/GAS/editor_extension/tag_manager_panel.tscn – Tag Manager UI
• addons/GAS/editor_extension/tag_manager_panel.gd – Editor logic
• addons/GAS/editor_extension/multi_tag_editor_property.gd – Inspector dropdown UI
• addons/GAS/editor_extension/gas_taglist_suffix_handler.gd – Suffix-based dropdown routing

🔹 Best Practices

• Use meaningful categories and names — e.g., Effect.Slowed, Ability.Dash.
• Use the _gas_taglist suffix for all exported tag fields.
• Mark tags as Is Cue instead of using a "Cue" category.
• Never manually edit the .tres tag file outside of the editor.

✅ Summary

The Godot G.A.S. Tag System is a flexible, runtime-aware tag architecture with complete editor integration, category grouping, cue support, and dynamic runtime tag application. It supports all use cases needed for a fully-featured Gameplay Ability System in Godot.