Scoring

Focus and scoring

SteamShell decides which window should be in front by scoring candidates, not by guessing. The goal is to recover from Steam and launcher focus problems without stealing focus from you.

How a window is scored

Each tick, every visible top-level window is judged in three stages. Each stage gates the next, so the expensive checks only run on windows that already look plausible.

1. Shape

Is it the right size and in the right place?

• Near-fullscreen — fills the display and sits at its origin. Best score.
• Large borderless — at least 90% of the display. Lower score.
• Anything smaller is rejected as TOO_SMALL, and nothing further is measured.
• A short title costs a small bonus; a real title earns it.

Measured per monitor. A fullscreen game on your second display is compared against that display's size and origin. Before 2.0.0 the shell compared everything against the primary monitor, so a game at x=1920 failed the position test and scored as merely borderless — or was rejected outright if the second monitor was larger.

2. CPU

Only now is process CPU sampled.

• Above the threshold: a solid bonus. Games use CPU.
• Some but not much: a small bonus.
• Zero: rejected, if you have strict mode on.
• Unreadable: not evidence either way, and never rejects. A process being seen for the first time has no reading yet, and discarding it for being new would be wrong.

3. Audio

Only for windows that survived CPU. A process making sound is very likely the game — this is what separates a game from a fullscreen browser or a launcher sitting at the same size.

The winner is the highest score, largest window breaking a tie.

Hard rules that come first

• Always Focus executables win over Steam when present.
• Minimised legacy game surfaces bypass the shape test entirely — an exclusive fullscreen game that minimised itself when Steam took focus has meaningless geometry.
• Cooldowns stop it acting every tick.
• Pause focus stands the whole thing down.

Seeing the decision

Quick Menu → Game Detection shows the current candidates and scores live.

For more, Settings → Logging → diagnostic mode logs the full candidate table each time, including rejected windows and why they were rejected. That is usually the fastest way to answer "why did it pick that?".

Tuning

Symptom	Try
Grabs focus too eagerly	Raise the minimum score to activate, or lengthen the cooldown
Misses your game	Lower the minimum score, or add it to Always Focus
Picks a launcher	Add the launcher to the excluded list
Wrong window on a second monitor	Should be fixed in 2.0.0 — check Game Detection and report it

Change one setting, reload with Ctrl+Alt+Shift+R, and test again.

What it cannot do

Some exclusive-fullscreen applications cannot be brought forward by any third-party activation call. If Alt+Tab works and SteamShell does not, that is an OS-level focus restriction rather than a scoring problem.