Why is my button losing focus when clicking on random stuff?

I recently encountered an issue with my Godot game, Dice Tower, where clicking around on random parts of the game (like the background of a menu) resulted in focused buttons losing focus to…nothing at all. I didn’t find any search results which got to the root of the actual problem, so I’ll share what I figured out in case someone suffers the same problem in the future.

Root Cause: SubViewportContainer nodes default with focus_mode: CLICK.

My game uses a lot of SubViewport nodes for rendering tricks around mixing pixel art and hi-res assets. Accordingly, I also use SubViewportContainer nodes to wrap the viewports and scale them as needed. Because of focus_mode: CLICK (which means focus is grabbed when clicked), that meant any time I clicked on something that itself wasn’t grabbing focus, the SubViewportContainer grabbed that focus, instead.

Ultimately, it wasn’t a hard fix. However, at no point during my internet sleuthing did I come across any articles that suggested this was the problem. I only figured it out by creating a test scene and experimenting with different configurations of nodes and viewports to fix the perceived behavior. Thus, I wrote this article.

Hopefully, if you are also trying to figure out why clicking on random stuff loses button focus, this article saved you time in figuring out the problem. Comment if it did!