Release v4.4: raw mouse & docs

Author: d3nd3

.cursor/skills/new-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: new-release
-description: Bumps SoF Buddy version, updates VERSION and hdr/version.h, then git add/commit/push to trigger a GitHub Actions release. Use when creating a new release, cutting a build, or when the user asks to release, bump version, or push a new build. Agent must study commit history and changes to carefully create a changelog for the release.
+description: Bumps SoF Buddy version, updates VERSION and hdr/version.h, then git add/commit/push to trigger a GitHub Actions release. Use when creating a new release, cutting a build, or when the user asks to release, bump version, or push a new build. Agent must study commit history and changes to carefully create a changelog for the release. Do not skip over anything, if there is change in any feature, it must be documented in the changelog and change. This command is useful eg. `git diff v4.3-build143 --stat`
 ---
 
 # New Release

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v4.4
+
+- Raw mouse: reworked raw input pipeline to buffer and drain high-Hz `WM_INPUT` via `GetRawInputBuffer`, skip zero-delta packets, and keep the game's original mouse cvars/flow intact while sourcing movement from hardware deltas instead of OS cursor position.
+- Raw mouse: hardened window/foreground and clip handling (no cursor warping on clip refresh, proper unregister on failure/teardown, disabled-path hooks now pure passthrough with no side effects when `_sofbuddy_rawmouse` is 0).
+- Raw mouse docs: expanded feature README with callback/override details, disabled-path behavior, jitter/high-polling guidance, and configuration notes so users understand how and when to enable it.
+- Docs: README now surfaces a prominent “#1 thing you need to know” section and in-game command docs that emphasize `F12` / `sofbuddy_menu sof_buddy` as the primary entry point into SoF Buddy.
+
 ## v4.3
 
 - Docs: add http.png hero image to README.

VERSION

@@ -1 +1 @@
-4.3
+4.4

hdr/version.h

@@ -7,4 +7,4 @@
     Increment version using: ./increment_version.sh
 */
 
-#define SOFBUDDY_VERSION "4.3"
+#define SOFBUDDY_VERSION "4.4"

src/features/raw_mouse/README.md

@@ -1,59 +1,86 @@
 # Raw Mouse Input
 
 ## Purpose
-Implements raw mouse input support for Soldier of Fortune using Windows Raw Input API instead of the default GetCursorPos/SetCursorPos cursor management. Provides smoother, more direct mouse response without Windows acceleration/smoothing while preserving all original SoF mouse cvars.
+Implements raw mouse input support for Soldier of Fortune using the Windows Raw Input API instead of the default GetCursorPos/SetCursorPos cursor management. Provides smoother, more direct mouse response without Windows acceleration/smoothing while preserving all original SoF mouse cvars.
 
 ## Callbacks
 - **EarlyStartup** (Post, Priority: 70)
-  - `raw_mouse_EarlyStartup()` - Patches SetCursorPos calls in exe to install hooks
+  - `raw_mouse_EarlyStartup()` - Patches three `SetCursorPos` call sites in the exe (IN_Frame, IN_MouseMove, IN_MenuMouse) to redirect through `hkSetCursorPos`, and resolves the real `SetCursorPos` via `GetProcAddress` for passthrough use
 - **RefDllLoaded** (Post, Priority: 70)
-  - `raw_mouse_RefDllLoaded()` - Registers raw input device with Windows API
+  - `raw_mouse_RefDllLoaded()` - Creates the `_sofbuddy_rawmouse` cvar with a change callback; if the archived value is non-zero, immediately registers raw input
 
 ## Hooks
 - **IN_MouseMove** (Post, Priority: 100)
-  - `in_mousemove_callback()` - Resets delta accumulators after each frame
+  - `in_mousemove_callback()` - Polls buffered raw input to ensure minimum latency, then resets `raw_mouse_delta_x/y` to 0 after the game has consumed the frame's mouse input.
 - **IN_MenuMouse** (Post, Priority: 100)
-  - `in_menumouse_callback()` - Consumes accumulated deltas after menu mouse handling (same as IN_MouseMove)
+  - `in_menumouse_callback()` - Same as IN_MouseMove; polls and resets deltas.
 
 ## OverrideHooks
 - **GetCursorPos** (user32.dll)
-  - `getcursorpos_override_callback()` - Returns virtual cursor position `(window_center + raw_mouse_delta_x/y)` when raw input enabled; never calls real GetCursorPos for look/menu
+  - `getcursorpos_override_callback()` - When enabled, returns virtual cursor position `(window_center + delta_x/y)` instead of the real OS cursor position. On the first call (or after a reset), seeds `window_center` from the real cursor position via one call to the original `GetCursorPos`. When disabled, passes through to the original.
 - **DispatchMessageA** (user32.dll)
-  - `dispatchmessagea_override_callback()` - On WM_INPUT, extracts relative raw deltas (ignores absolute) and accumulates via `raw_mouse_accumulate_delta()`
+  - `dispatchmessagea_override_callback()` - When enabled: intercepts `WM_INPUT` messages, processes the current packet, and immediately polls `GetRawInputBuffer` to drain any queued input. This handles high-polling-rate mice efficiently. Also handles registration/clipping on window events.
 
 ## CustomDetours
-- **SetCursorPos** (user32.dll, via GetProcAddress)
-  - `hkSetCursorPos()` - When raw input enabled: updates internal `window_center`, returns TRUE without calling the real SetCursorPos (OS cursor is never warped). Cursor clip is refreshed by DispatchMessageA on focus/move/size events and during registration.
-  - Patched at exe addresses: `0x2004A0B2`, `0x2004A410`, `0x2004A579`
+- **SetCursorPos** (user32.dll, via binary patch + GetProcAddress)
+  - `hkSetCursorPos()` - When enabled: updates internal `window_center` to the coordinates the game wants to recenter to, and returns TRUE **without** calling the real `SetCursorPos` (the OS cursor is never warped by the game). When disabled: calls the real `SetCursorPos` normally.
+  - Patched at exe addresses: `0x2004A0B2` (IN_Frame), `0x2004A410` (IN_MouseMove), `0x2004A579` (IN_MenuMouse)
 
 ## Technical Details
 
 ### How It Works
-The implementation works by **faking cursor position changes** so the original mouse processing code continues to work with all its cvars intact:
-
-1. **Registration** (RefDllLoaded callback):
-   - Registers for raw mouse input using `RegisterRawInputDevices()`
-   - Sets `hwndTarget` to the active window handle
-
-2. **Message Processing** (DispatchMessageA hook):
-   - Intercepts WM_INPUT messages
-   - Calls `ProcessRawInput()` to extract mouse delta from RAWINPUT structure
-   - Ignores absolute mouse packets and accumulates only relative raw deltas
-
-3. **Virtual Cursor Position** (GetCursorPos hook):
-   - Returns `(window_center.x + raw_mouse_delta_x, window_center.y + raw_mouse_delta_y)` so the game sees movement (e.g. swipe left → negative delta_x → position left of center)
-   - Game logic unchanged: it reads “cursor” position and uses it for look/menu; we never call the real GetCursorPos for that path
-
-4. **No Cursor Warping** (SetCursorPos hook):
-   - Game’s recenter calls are intercepted: we update `window_center` and return TRUE without calling the real SetCursorPos, so the OS cursor is never moved by the game
-
-5. **Cursor Confinement** (ClipCursor):
-   - While raw input is enabled and the game window is foregrounded, cursor is clipped to the game client area inset by 64px on all edges to reduce edge-of-screen issues
-   - On each clip refresh (e.g. after alt-tab), if the OS cursor is outside the clip rect it is warped back inside via the real SetCursorPos so the cursor is always within bounds when regaining focus
-   - Clip is automatically released when raw input is disabled or focus is lost
-
-6. **Delta Consumption** (IN_MouseMove / IN_MenuMouse callbacks):
-   - After the game processes the frame, `raw_mouse_consume_deltas()` resets `raw_mouse_delta_x/y` to 0, so the virtual cursor is effectively back at window_center for the next frame
+The game's original mouse pipeline is: `SetCursorPos` (center cursor) → game logic → `GetCursorPos` (read cursor) → compute delta → apply to view. This feature intercepts that pipeline so the game's own mouse code continues to work unchanged, but the underlying input comes from raw hardware deltas instead of OS cursor position:
+
+1. **CVar Creation** (RefDllLoaded callback):
+   - `create_raw_mouse_cvars()` registers `_sofbuddy_rawmouse` with a change callback (`raw_mouse_on_change`)
+   - If the archived value is already non-zero (user previously enabled it), the change callback fires immediately
+
+2. **Registration** (cvar change callback):
+   - When the cvar is set to non-zero, `raw_mouse_on_change()` calls `raw_mouse_register_input()`
+   - This registers for raw mouse input using `RegisterRawInputDevices()` with `hwndTarget` set to the active window
+   - Deltas are reset and `window_center` is invalidated so the next `GetCursorPos` call seeds it fresh
+
+3. **Message Processing** (DispatchMessageA hook, only when enabled):
+   - Intercepts `WM_INPUT` messages
+   - Processes the current message's data immediately via `GetRawInputData`.
+   - Calls `GetRawInputBuffer` to drain any remaining input events in the queue in one batch. This prevents the message queue from being flooded by high-Hz mice (e.g. 1000Hz-8000Hz).
+   - Absolute mouse packets are ignored; only relative deltas are accumulated via `raw_mouse_accumulate_delta()`
+   - On window focus/move/size events, ensures registration is current and refreshes the cursor clip rect
+
+4. **Virtual Cursor Position** (GetCursorPos hook):
+   - Returns `(window_center.x + raw_mouse_delta_x, window_center.y + raw_mouse_delta_y)`
+   - The game sees this as a normal cursor position offset from center, so its existing delta calculation works unchanged
+   - On the very first call (or after a toggle), `window_center` is seeded from the real OS cursor position via one call to the original `GetCursorPos`
+
+5. **No Cursor Warping** (SetCursorPos hook):
+   - The game calls `SetCursorPos` every frame to recenter the cursor
+   - The hook intercepts this: it records the coordinates as `window_center` and returns TRUE, but **does not call the real SetCursorPos**
+   - This prevents the OS cursor from being physically moved, which would otherwise generate synthetic mouse events that conflict with raw input
+
+6. **Cursor Confinement** (ClipCursor):
+   - While raw input is enabled and the game window is foregrounded, the OS cursor is clipped to the game client area inset by 64px on all sides to prevent edge-of-screen issues
+   - Clip is automatically released when raw input is disabled, focus is lost, or the window cannot be resolved
+   - Clip refresh is only performed when raw mouse is enabled — when disabled, the DispatchMessageA hook has zero side effects
+
+7. **Delta Consumption** (IN_MouseMove / IN_MenuMouse post-callbacks):
+   - After the game processes the frame's mouse input, `raw_mouse_consume_deltas()` resets `raw_mouse_delta_x/y` to 0
+   - This means the next `GetCursorPos` call returns exactly `window_center`, making the game see zero delta until new raw input arrives
+
+### Disabled Path (Feature Compiled In, CVar Off)
+When `_sofbuddy_rawmouse` is 0 (the default), all hooks are pure passthroughs:
+- **GetCursorPos** → calls original
+- **SetCursorPos** → calls original `oSetCursorPos`
+- **DispatchMessageA** → calls original with no pre-processing
+- **IN_MouseMove / IN_MenuMouse** → returns immediately
+
+No cursor clipping, delta accumulation, or registration occurs. The game behaves identically to an unhooked state.
+
+### Jitter & high polling rate
+- **No cursor warp on clip refresh.** We do not call `SetCursorPos` to snap the OS cursor back inside the clip rect when refreshing. Warping generates synthetic mouse events that mix with raw deltas and cause spikey/jittery movement. Only `ClipCursor` is applied.
+- **Zero-delta packets skipped.** `ProcessRawInput` ignores `WM_INPUT` with `lLastX == 0 && lLastY == 0` so spurious (0,0) reports don’t add noise.
+- **Buffered Input.** Uses `GetRawInputBuffer` in both the message loop (draining the queue) and the frame loop (fetching latest data). This minimizes overhead for 1000Hz+ mice and ensures the lowest possible input latency.
+- **Legacy input left enabled.** We register with `dwFlags = 0` (no `RIDEV_NOLEGACY`) so window dragging and other system mouse behavior keep working.
+- **Windows 11.** KB5028185 and 24H2 improve behavior for high-polling-rate mice (throttling/coalescing for background listeners, USB polling optimizations). No code change required; up-to-date Win11 can help on high-Hz hardware.
 
 ### Preserved CVars
 All original SoF mouse cvars remain functional:
@@ -70,6 +97,7 @@ All original SoF mouse cvars remain functional:
 - **_sofbuddy_rawmouse** (default: 0, archived)
   - Set to 1 to enable raw mouse input
   - Set to 0 to use legacy cursor-based input
+  - Changes take effect immediately via the cvar change callback
 
 ## Benefits
 - Smoother, more direct mouse response (no Windows acceleration/smoothing)

src/features/raw_mouse/hooks/dispatchmessagea.cpp

@@ -2,131 +2,128 @@
 
 #if FEATURE_RAW_MOUSE
 
+#include "../shared.h"
+#include "generated_detours.h"
 #include "sof_compat.h"
 #include "util.h"
-#include "generated_detours.h"
-#include "../shared.h"
+#include <vector>
 
 using detour_DispatchMessageA::tDispatchMessageA;
 
 #if SOFBUDDY_RAWINPUT_API_AVAILABLE
-static bool ReadRawInputBuffer(HRAWINPUT input_handle, BYTE* buffer, UINT buffer_size)
-{
-    UINT size = buffer_size;
-    UINT copied = GetRawInputData(input_handle, RID_INPUT, buffer, &size, sizeof(RAWINPUTHEADER));
-    if (copied == static_cast<UINT>(-1)) {
-        return false;
-    }
-    return copied == size && size >= sizeof(RAWINPUTHEADER);
-}
+static std::vector<BYTE> g_dispatchBuffer;
 
-static void ProcessRawInput(LPARAM lParam)
-{
+static bool ReadRawInputBufferInternal(HRAWINPUT input_handle, std::vector<BYTE>& buffer) {
     UINT dwSize = 0;
-    if (GetRawInputData(reinterpret_cast<HRAWINPUT>(lParam), RID_INPUT, NULL, &dwSize, sizeof(RAWINPUTHEADER)) == static_cast<UINT>(-1)) {
-        return;
+    if (GetRawInputData(input_handle, RID_INPUT, NULL, &dwSize, sizeof(RAWINPUTHEADER)) == (UINT)-1) {
+        return false;
     }
+    
     if (dwSize < sizeof(RAWINPUTHEADER)) {
-        return;
+        return false;
     }
 
-    BYTE stackBuffer[256];
-    RAWINPUT* raw = nullptr;
-
-    if (dwSize <= sizeof(stackBuffer)) {
-        if (!ReadRawInputBuffer(reinterpret_cast<HRAWINPUT>(lParam), stackBuffer, dwSize)) {
-            return;
-        }
-        raw = reinterpret_cast<RAWINPUT*>(stackBuffer);
-    } else {
-        g_heapBuffer.resize(dwSize);
-        if (!ReadRawInputBuffer(reinterpret_cast<HRAWINPUT>(lParam), g_heapBuffer.data(), dwSize)) {
-            return;
-        }
-        raw = reinterpret_cast<RAWINPUT*>(g_heapBuffer.data());
+    if (buffer.size() < dwSize) {
+        buffer.resize(dwSize);
     }
 
-    if (!raw || raw->header.dwType != RIM_TYPEMOUSE) {
-        return;
+    if (GetRawInputData(input_handle, RID_INPUT, buffer.data(), &dwSize, sizeof(RAWINPUTHEADER)) != dwSize) {
+        return false;
     }
+    
+    return true;
+}
 
-    const RAWMOUSE& mouse = raw->data.mouse;
-    if ((mouse.usFlags & MOUSE_MOVE_ABSOLUTE) != 0) {
+static void ProcessRawInputMessage(LPARAM lParam) {
+    // Process the specific message that triggered WM_INPUT
+    if (!ReadRawInputBufferInternal(reinterpret_cast<HRAWINPUT>(lParam), g_dispatchBuffer)) {
         return;
     }
 
-    if (mouse.lLastX == 0 && mouse.lLastY == 0) {
+    RAWINPUT* raw = reinterpret_cast<RAWINPUT*>(g_dispatchBuffer.data());
+    if (raw->header.dwType != RIM_TYPEMOUSE) {
         return;
     }
 
-    raw_mouse_accumulate_delta(mouse.lLastX, mouse.lLastY);
-}
-#else
-static void ProcessRawInput(LPARAM lParam)
-{
-    (void)lParam;
-}
-#endif
-
-static void EnsureRawMouseRegistered(HWND hwnd_hint)
-{
-    if (!raw_mouse_is_enabled() || !raw_mouse_api_supported()) {
+    const RAWMOUSE &mouse = raw->data.mouse;
+    if ((mouse.usFlags & MOUSE_MOVE_ABSOLUTE) != 0) {
         return;
     }
-
-    HWND hwnd = raw_mouse_hwnd_target;
-    if (hwnd && !IsWindow(hwnd)) {
-        raw_mouse_registered = false;
-        raw_mouse_hwnd_target = nullptr;
-        hwnd = nullptr;
+    
+    if (mouse.lLastX != 0 || mouse.lLastY != 0) {
+        raw_mouse_accumulate_delta(mouse.lLastX, mouse.lLastY);
     }
 
-    if (!hwnd) hwnd = hwnd_hint;
-    if (!hwnd) hwnd = GetActiveWindow();
-    if (!hwnd) hwnd = GetForegroundWindow();
-    if (!hwnd) {
-        return;
-    }
+    // Now drain any other pending input to prevent queue buildup and latency
+    raw_mouse_poll();
+}
+#else
+static void ProcessRawInputMessage(LPARAM lParam) { (void)lParam; }
+#endif
 
-    if (!raw_mouse_registered || raw_mouse_hwnd_target != hwnd) {
-        raw_mouse_register_input(hwnd, false);
-    }
+static void EnsureRawMouseRegistered(HWND hwnd_hint) {
+  if (!raw_mouse_is_enabled() || !raw_mouse_api_supported()) {
+    return;
+  }
+
+  HWND hwnd = raw_mouse_hwnd_target;
+  if (hwnd && !IsWindow(hwnd)) {
+    raw_mouse_registered = false;
+    raw_mouse_hwnd_target = nullptr;
+    hwnd = nullptr;
+  }
+
+  if (!hwnd)
+    hwnd = hwnd_hint;
+  if (!hwnd)
+    hwnd = GetActiveWindow();
+  if (!hwnd)
+    hwnd = GetForegroundWindow();
+  if (!hwnd) {
+    return;
+  }
+
+  if (!raw_mouse_registered || raw_mouse_hwnd_target != hwnd) {
+    raw_mouse_register_input(hwnd, false);
+  }
 }
 
 static bool msg_affects_cursor_clip(UINT msg) {
-    switch (msg) {
-    case WM_SIZE:
-    case WM_MOVE:
-    case WM_ACTIVATE:
+  switch (msg) {
+  case WM_SIZE:
+  case WM_MOVE:
+  case WM_ACTIVATE:
 #ifndef WM_ENTERSIZEMOVE
 #define WM_ENTERSIZEMOVE 0x0231
 #endif
 #ifndef WM_EXITSIZEMOVE
-#define WM_EXITSIZEMOVE  0x0232
+#define WM_EXITSIZEMOVE 0x0232
 #endif
-    case WM_ENTERSIZEMOVE:
-    case WM_EXITSIZEMOVE:
+  case WM_ENTERSIZEMOVE:
+  case WM_EXITSIZEMOVE:
 #ifndef WM_DISPLAYCHANGE
 #define WM_DISPLAYCHANGE 0x007E
 #endif
-    case WM_DISPLAYCHANGE:
-        return true;
-    default:
-        return false;
-    }
+  case WM_DISPLAYCHANGE:
+    return true;
+  default:
+    return false;
+  }
 }
 
-LRESULT dispatchmessagea_override_callback(const MSG* msg, detour_DispatchMessageA::tDispatchMessageA original) {
-    if (msg && raw_mouse_is_enabled() && raw_mouse_api_supported()) {
-        if (msg_affects_cursor_clip(msg->message))
-            EnsureRawMouseRegistered(msg->hwnd);
-        if (msg->message == WM_INPUT)
-            ProcessRawInput(msg->lParam);
+LRESULT dispatchmessagea_override_callback(
+    const MSG *msg, detour_DispatchMessageA::tDispatchMessageA original) {
+  if (msg && raw_mouse_is_enabled() && raw_mouse_api_supported()) {
+    if (msg_affects_cursor_clip(msg->message)) {
+      EnsureRawMouseRegistered(msg->hwnd);
+      raw_mouse_refresh_cursor_clip(msg->hwnd);
+    }
+    if (msg->message == WM_INPUT) {
+      ProcessRawInputMessage(msg->lParam);
     }
-    if (msg && msg_affects_cursor_clip(msg->message))
-        raw_mouse_refresh_cursor_clip(msg->hwnd);
-    SOFBUDDY_ASSERT(original != nullptr);
-    return original(msg);
+  }
+  SOFBUDDY_ASSERT(original != nullptr);
+  return original(msg);
 }
 
-#endif // FEATURE_RAW_MOUSE
+#endif // FEATURE_RAW_MOUSE