godot-cache-refresh

name	godot-cache-refresh
description	Regenerate Godot caches (class_name registry and .uid files). Use after creating or renaming GDScript files with class_name.
allowed-tools	["Bash"]

Godot Cache Refresh

Regenerate Godot Engine's project caches by running the editor in headless mode.

What It Refreshes

• Class name cache: .godot/global_script_class_cache.cfg — registry of all class_name declarations
• UID files: .uid files for resources that are missing them

When to Use

• After creating new GDScript files with class_name
• After moving or renaming GDScript files
• When class references are not resolving correctly ("class not found" errors)

Command

<godot> --headless --editor --path <project_root> --quit

• <godot> — path to the Godot binary (use whatever is available: godot, godot4, /usr/bin/godot, etc.)
• <project_root> — directory containing project.godot

Finding the Project Root

find . -maxdepth 4 -name "project.godot" -type f 2>/dev/null

Success Criteria

Exit code 0 means the cache was regenerated successfully.

Important: Ignore Godot Log Noise

Godot prints WARNING and ERROR messages to stderr during headless runs. These are normal and expected — do not treat them as failures:

• WARNING: ObjectDB instances leaked at exit
• ERROR: Condition "..." is true

Only the exit code matters.

Role Separation vs godot-resource-resave

This skill is a passive scan: it never rewrites project files, only regenerates caches and missing .gd.uid sidecars. To inject uid= into .tscn / .tres files themselves (and validate that they load), use godot-resource-resave, which actively rewrites those files. When new .gd files are referenced by new scenes, run this skill first so the UID cache is populated, then godot-resource-resave.