Focus Audit — Godot 4 keyboard & gamepad navigation audit

Your menu works. You have clicked every button. You have tabbed through it. And on a gamepad, one of those buttons cannot be selected at all.

Why tabbing through it proves nothing

Godot has two navigation graphs, and Tab is the forgiving one.

Tab (find_next_valid_focus) walks the whole scene tree in order. Unless you have wired focus_next / focus_previous by hand, you eventually reach everything from anywhere — which is why tabbing through a menu almost never finds a bug.

Arrows and the D-pad (find_valid_focus_neighbor) are geometric. Godot compares the laid-out rectangles and picks the nearest control in that direction, and a control can very easily have nothing pointing at it.

A gamepad has no Tab key.

Focus Audit walks the arrow graph. It does not reimplement Godot's rules — it builds each scene with your game's own theme, lets the layout settle, and asks the engine itself where each direction leads. The answer is the engine's own, for the scene as you saved it.

What it reports

• Mouse-only control — a button a player must press whose focus_mode is NONE or CLICK
• Screen-reader-only control — focus_mode is ACCESSIBILITY (Godot 4.5+): a screen reader reaches it, a keyboard and gamepad cannot
• Cannot be reached with a D-pad — no arrow direction leads to it from where focus starts
• Focus gets stuck here — focus can arrive and nothing leads out
• focus_neighbor points nowhere — a path that no longer reaches a focusable control. Godot ignores these in silence
• Screen opens with nothing focused — a controller player sees a dead menu
• No route back — reachable, but nothing navigates back toward the start

The finding worth staring at

The demo menu has a Credits button. Nothing is wrong with it. Its focus_mode is the default, it is visible, it is on screen, and Tab reaches it immediately.

It is unreachable because the other buttons were wired into a tidy loop and none of them points at it. The bug is not in the broken button — which is exactly why looking at it never finds anything.

Open the demo and press play. It looks completely finished, and with a mouse it is. Unplug the mouse and no key does anything at all, because nothing has focus.

Output

The dock, a Markdown report, and JSON with a versioned schema so a build server can fail on it. Each check has its own tick box, so a project can switch off the ones it has decided not to care about.

What it will not tell you

Your scripts do not run. Checks happen in the editor, and the editor only runs @tool scripts. So "Screen opens with nothing focused" is a statement about the saved scene: a menu that calls grab_focus() in an ordinary _ready() is still reported, because that line has not run. Ignore that one finding where a script grabs focus at runtime, or switch the check off with its tick box. The reverse holds too — a scene's own @tool code does run inside your editor when that scene is checked.

Focus your code moves later during gameplay is not simulated at all. Hidden branches are not laid out and are skipped. Only .tscn files outside addons/ are scanned — binary .scn scenes are not. Scenes that cannot be loaded are reported as skipped — in the dock and in the saved reports — never as clean. A clean report means the saved scenes had none of the faults it looks for — play the game with a controller and nothing else plugged in.

In the download

The addon, a demo menu with one of every fault planted in it, the full README, and the licence.

How it was built

The code and this page were written with AI, directed and reviewed by a person. Every claim above is checked by an automated suite that runs on Godot 4.4 and 4.7, and by pressing the dock's own button inside a real editor on both — the findings quoted here come out of that suite rather than being typed by hand.

Requirements

Godot 4.4 through 4.7. FOCUS_ACCESSIBILITY exists from 4.5 and is only reported where the engine has it. No C#, no build step, no external tools. One purchase, unlimited projects, commercial use included.