The Stale Godot Class Cache Bug That Passed CI but Broke Local Startup

The test code also used the new classes for casts and enum access:

var sentinel := await _test_spawn_enemy( "res://src/enemies/clockwork_sentinel.tscn", Vector2(320, 300) ) as ClockworkSentinel if sentinel._state == ClockworkSentinel.State.CHARGE: charged = true 

Those references were valid after Godot refreshed its global class registry. Before that refresh, the parser could not resolve them.

CI missed the problem because the test workflow imported the project before running the suite. The import regenerated the cache, so CI always tested the healthy state. Local startup followed a different order and exposed the bug.

Refreshing or deleting .godot could repair one checkout, but it left the startup dependency in the code. I wanted the game to parse even before the editor rebuilt the cache.

Code

I merged the complete fix as PR #95 in the project’s private repository. Since the repository is not publicly accessible, the relevant before-and-after code is included below.

The first change was to use a script path when a room inherited from one of the newly added classes:

extends "res://src/rooms/tower_room.gd" 

For runtime checks, I loaded the script resource explicitly instead of asking the parser to resolve TowerRoom as a global name:

const TOWER_ROOM_SCRIPT := preload("res://src/rooms/tower_room.gd") func _is_tower_room(node: Node) -> bool: if node == null: return false var script: Script = node.get_script() as Script while script != null: if script == TOWER_ROOM_SCRIPT: return true script = script.get_base_script() return false 

The enemy tests now use their stable base type. They read the state through the object and compare it with an enum from an explicitly loaded script:

const CLOCKWORK_SENTINEL_SCRIPT := preload( "res://src/enemies/clockwork_sentinel.gd" ) var sentinel: EnemyBase = await _test_spawn_enemy( "res://src/enemies/clockwork_sentinel.tscn", Vector2(320, 300) ) if int(sentinel.get("_state")) == CLOCKWORK_SENTINEL_SCRIPT.State.CHARGE: charged = true 

Temporary objects such as wax pools and bell shockwaves did not need a global type check at all. I added them to groups and tested the behavior that mattered:

if child.is_in_group(&"wax_pool"): pool_found = true 

Effects and map marker helpers received the same explicit preload treatment. The fix covered 19 files with 81 additions and 33 deletions.

My improvements

I added a static check to stop cache-sensitive global names from returning outside their own class_name declarations:

CACHE_SENSITIVE='\b(TowerRoom|BelfrySpider|BellRingerWretch|CandleBearerSkeleton|CarrionCrow|ClockworkSentinel|GeneratedFx|MapMarkers|TowerImp|WaxSlime)\b' CACHE_REFS=$(rg -n "$CACHE_SENSITIVE" src --glob '*.gd' \ | grep -vE 'class_name (TowerRoom|BelfrySpider|BellRingerWretch|CandleBearerSkeleton|CarrionCrow|ClockworkSentinel|GeneratedFx|MapMarkers|TowerImp|WaxSlime)' \ || true) if [ -n "$CACHE_REFS" ]; then echo "FAIL(stale-cache): direct reference to a newly added global class" exit 1 fi 

This check is intentionally narrow. class_name is still useful in the project, and I did not want to ban it. The guard covers the recently added classes that caused this startup regression.

I ran the full test command again on the current main branch while preparing this submission:

PASS(stale-cache) PASS(rooms) PASS(transition) PASS(save) PASS(progression) PASS(gameover) PASS(pause) PASS(dash) PASS(boss) PASS(enemies) PASS(walljump) PASS(combo) PASS(skins) PASS(area3) PASS(area3-enemies) PASS(enemy-ai) PASS(physics) PASS(connections) == ALL PASS == 

The asset check also passed for 911 media files, including 893 decoded PNGs and 110 frame sequences.

Clearing a bad cache would have repaired one checkout. The durable fix removes the undocumented requirement that the cache must be fresh before the project can be parsed. CI now checks the dependency directly, and the game no longer relies on editor state to reach its startup path.