godot-verification-check-only-autoloads

Answer

Root cause. godot --headless --check-only --script <file> compiles the script in isolation — no project boot, no SceneTree, no autoload registration. Autoloads like EventBus are injected into the SceneTree root at runtime boot from project.godot's [autoload] section. A standalone script compilation therefore cannot resolve the EventBus identifier, producing a false-positive Identifier not found on every script that touches an autoload. It is a resolution-scope problem, not a code defect — and --check-only never executes code, so it cannot validate wiring either.

The fix — verify via runtime paths only (for autoload-heavy projects):

1. Headless runtime boot (primary): boot a main-scene runner with godot --headless, let the SceneTree register autoloads, then load() + instantiate every control script and assert behavior.
2. GUT (godot --headless --script res://addons/gut/gut_cmdln.gd) — same mechanism: a SceneTree-subclass --script runner gets autoloads registered (verified below).
3. Restrict --check-only to autoload-free scripts, or use it only as a cheap syntax pre-filter — never as the pass/fail gate.

project.godot (minimal repro):

[application]
config/name="AutoloadVerificationTest"
run/main_scene="res://tests/test_runner.tscn"

[autoload]
EventBus="*res://autoload/event_bus.gd"

Control script under test (scripts/game_state.gd — the one that false-positives):

extends Node
class_name GameState
var score: int = 0
func _ready() -> void:
    EventBus.funds_changed.connect(_on_funds_changed)   # line 9: "Identifier not found" under check-only
func _on_funds_changed(amount: int) -> void:
    score = amount * 2
func current_funds() -> int:
    return EventBus.player_funds

The valid runner (tests/test_runner.gd, wired as main scene in test_runner.tscn):

extends Node

var failures: Array[String] = []
func _ready() -> void:
    _run()
    if failures.is_empty():
        print("ALL CHECKS PASSED (0 SCRIPT ERRORS)")
        get_tree().quit(0)
    else:
        for f in failures: printerr("FAIL: ", f)
        get_tree().quit(1)

func _run() -> void:
    _check(is_instance_valid(EventBus), "EventBus autoload registered in SceneTree")
    var gs: Node = load("res://scripts/game_state.gd").new()
    var ec: Node = load("res://scripts/economy_manager.gd").new()
    add_child(gs); add_child(ec)          # boot path: _ready() runs, signals wire
    _check(gs.current_funds() == 100, "GameState reads EventBus.player_funds")
    EventBus.emit_funds_changed(200)
    _check(gs.current_funds() == 200, "signal propagation through autoload")
    _check(gs.score == 400, "autoload signal reached GameState handler")
    _check(ec.apply_tax(100) == 15, "EconomyManager.apply_tax(100) == 15")
    _check(EventBus.player_funds == 85, "write-through autoload mutation")

func _check(ok: bool, what: String) -> void:
    if ok: print("PASS: ", what)
    else: failures.append(what); printerr("FAIL: ", what)

CI commands (with --path set to the project root):

# VALID: runtime verification — exit 0 = pass
godot --headless res://tests/test_runner.tscn

# VALID (GUT / SceneTree-subclass mode) — autoloads are registered
godot --headless --script res://tests/scene_tree_runner.gd

# INVALID as a pass/fail gate for autoload-heavy projects:
godot --headless --check-only --script res://scripts/game_state.gd   # false positive, exit 1