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

```bash
<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

```bash
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.