Add Reset Mouse Look keybind to recover the macOS stuck-cursor freeze

[deliro]

Rescoped to just the manual recovery keybind:

• The perf changes (custom-condition loadstring cache, GetUIPanel short-circuit, ipairs) already landed in master via refactor: hot-path perf improvements / 3.3.1 — dropped here.
• The auto ResyncMouselookOnFocusRegain is dropped per review (broad heuristic, bypassed the free-look state machine, not platform-gated).

What this adds — Combat Mode - Reset Mouse Look

A MouselookStop() issued while the window is backgrounded (a watched panel auto-unlocks Mouse Look during an alt-tab — e.g. bags, LFG ready check) leaves the OS mouse capture stuck on macOS: on return the camera is frozen and the cursor is gone, while IsMouselooking() no longer reflects reality.

The keybind calls MouselookStart() → next-frame MouselookStop() to re-grab and cleanly release the capture, restoring the cursor. OnUpdate re-locks afterward if free look should still be active. It's also exposed in Settings → Mouse Look next to the other keybinds, with a tooltip explaining the recovery.

Why not automatic: there is no window-focus event, and the background keeps rendering (background FPS), so the frozen state can't be detected from OnUpdate. Keybinds still fire during the freeze, so a manual keypress is the only reliable recovery.

🤖 Generated with Claude Code

[sampconrad]

Thanks for the work on this, @deliro! I had no idea about the macOS issue.

I'm not currently subscribed to the game, so I can't really test the proposed changes. The next time Blizzard breaks something that requires me to update the addon, I'll merge this and include it in the next release.

[sampconrad]

Thanks again for this, @deliro. I finally dug into the diff properly.

Happy to take:

• the custom-condition loadstring cache (and treating empty string as off)
• the GetUIPanel short-circuit / ipairs cleanup in the unlock-frame path
• the manual Reset Mouse Look keybind as an emergency recovery path

Those look low-risk and useful on their own.

Holding off on auto ResyncMouselookOnFocusRegain as written. The macOS stuck-capture problem sounds real, and I agree there’s no clean focus event to hook. But the current heuristic feels a bit broad for something that pulses raw MouselookStart/MouselookStop:

1. False positives: gap ≥ 0.5s or GetFramerate() < 6 can also fire on hitch/loading/cinematic/FPS dips, not just focus regain.
2. Bypasses the free-look state machine: raw Start/Stop skips the UI/CVar side effects that LockFreeLook / UnlockFreeLook normally keep in sync (crosshair, tooltip, Action Cam, sticky crosshair, healing radial).
3. Platform scope: if this is macOS-specific, I’d rather gate it (IsMacClient() / opt-in setting) so Windows users don’t inherit accidental resync pulses.

If you’re up for a follow-up, my preferred shape would be:

• keep the manual reset keybind
• tighten auto-detect (prefer wall-clock gap; don’t use low FPS alone)
• settle through LockFreeLook/UnlockFreeLook after the re-grab
• skip while mouse buttons are held (and ideally loading/cinematic)
• macOS-only or behind a toggle

I’m fine merging the perf + manual-reset pieces first, then revisiting auto-recovery once tightened. Either way, thanks for chasing this. I didn’t know about the macOS capture desync before.

[deliro]

I'll split this into two PRs: one for the performance improvements and one for the manual unstuck binding. I've been using this fix for a while now, since the automatic unstuck doesn't work at all.

[deliro]

I see you've already merged the performance part. Then I'll keep only the manual binding.

[sampconrad]

Can I get a screenshot showing how this new option sits on the config panel in-game, please? You might need to adjust the size/positioning of the other elements to make sure nothing is visually breaking/odd.

Might even be the case of adding a check to show this for the macOS client only, if possible, so we don’t run resync pulses on all clients by default.

[deliro]

Settings:

Tooltip:

Native Blizzard keybindings:

[sampconrad]

I wonder what's causing it to break line like this...

UI scale, perhaps? 🤔
Ace3 and its peculiarities 😭

Here's what it's supposed to look like

Ideally, we'd fit that new keybind in a way that doesn't cause a vertical scroll on the page.

[deliro]

macro for bug & fix reproduction:

/run print("CMD bags in 5s - switch to another window NOW") C_Timer.After(5,function() OpenAllBags() print("CMD opened look="..tostring(IsMouselooking())) end)

Requirements & steps:

1. macOS
2. Fullscreen windowed mode
3. Active Mouse Look
4. Run macro
5. Switch to any other window (browser)
6. Wait > 5 secs
7. Get back
8. You're stuck
9. Mouse Look toggle binding doesn't work
10. Press Reset Mouse Look keybinding
11. Unstuck (and Mouse Look is deactivated)