Skip to content

Gameplay Tags

This guide explains how MIP organizes Gameplay Tag .ini files and how the pre-commit hook helps you avoid committing noisy editor-generated diffs.

MIP splits Gameplay Tags across multiple .ini files under Config/Tags/ so that each domain area can be changed independently without causing merge conflicts with unrelated tags.

File Layout

File Owns
GameplayTags.Abilities.ini Ability, combat, input, GAS tags
GameplayTags.Attributes.ini GAS attribute tags
GameplayTags.Inventory.ini Item types, equipment slots, quality, currency
GameplayTags.Misc.ini Miscellaneous cross-cutting tags
GameplayTags.NPC.ini NPC-specific tags
GameplayTags.Player.ini Player state, movement, camera tags
GameplayTags.UI.ini Widget, HUD, and UI event tags
GameplayTags.World.ini World objects, environment tags
LifeSkill.ini Life skill categories, attributes, recipes

All files are registered under DefaultGame.ini via +AllowedConfigFiles= so the engine picks them up automatically.

How to Add a New Tag

Always hand-edit the correct file. Do not use the Unreal editor UI to add tags to shared files — see Why Not the Editor UI below.

  1. Open the right .ini file in VS Code.
  2. Add one line under the section header:
[/Script/GameplayTags.GameplayTagsList]
GameplayTagList=(Tag="LifeSkill.Gathering.Herbalism",DevComment="")
  1. Save the file.

  2. In the UE Editor: Project Settings → Gameplay Tags → toggle "Import Tags From Config" off, then back on.
    Tags reload without an editor restart.

  3. Commit the single-line change.

Why Not the Editor UI

When you add a tag through the Gameplay Tags editor UI and save, the editor rewrites the entire target file using Unreal's config command syntax. This emits:

  • Hundreds of -GameplayTagList= removal lines — one for every tag from every other split file that is loaded in memory but does not belong in this file.
  • Then the real additions at the bottom.

Result: a clean one-tag addition becomes a 300+ line diff that is noisy, misleading in review, and risky to commit (the - lines are real removal directives in UE's config system).

; Example of what the editor produces — do NOT commit this
-GameplayTagList=(Tag="Chat",DevComment="")
-GameplayTagList=(Tag="Inventory.Currency.Gold",DevComment="")
... (300 more)
GameplayTagList=(Tag="YourActualNewTag",DevComment="")

Pre-commit Hook

A pre-commit hook automatically detects -GameplayTagList= lines in any staged Config/Tags/*.ini file and asks whether to strip them before the commit lands.

Install (once per clone)

bash scripts/install-hooks.sh

The script copies everything from scripts/hooks/ into .git/hooks/ and marks them executable. It will not overwrite a non-MIP hook that is already present.

What the hook does

On every git commit:

  1. Scans staged Config/Tags/*.ini files for lines starting with -GameplayTagList=.
  2. If none found → proceeds silently.
  3. If found, behaviour depends on context:
Context Behaviour
CLI commit (git commit in terminal) Asks y/n per file inline — y strips and re-stages, n commits as-is
GUI commit (VS Code / Cursor source control) Pops a PowerShell MessageBox per file — Yes strips and re-stages, No commits as-is

Hook source

The hook lives at scripts/hooks/pre-commit and is committed to the repo so every clone gets the same version after running the installer.

.git/hooks/ is not tracked by git

The .git/ directory is never committed. Every fresh clone needs to run bash scripts/install-hooks.sh once to activate the hook.

Quick Reference

Action How
Add a new tag Hand-edit the correct Config/Tags/*.ini file
Reload tags in editor Toggle Import Tags From Config off → on
Install pre-commit hook bash scripts/install-hooks.sh
Discard editor-generated bloat git restore Config/Tags/<file>.ini
Strip bloat without discarding real additions Run the commit; hook will prompt to clean