feat(win32): 添加鼠标锁定跟随模式，支持后台 TPS/FPS 视角控制 (#1232)

Co-authored-by: Z_06 <z060606060606@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: 4 people

docs/en_us/2.4-ControlMethods.md

@@ -98,6 +98,7 @@ Different programs on Win32 handle input differently, so there is no universal m
 > - Admin privileges mainly depend on the target program's permission level. If the target program runs as administrator, running with admin privileges is required for compatibility.
 > - The `WithCursorPos` methods briefly move the cursor to the target position, then restore it after sending the message, hence "Brief" cursor seizure, but it does not block user operations.
 > - The `WithWindowPos` methods briefly move the window so the target position aligns with the current cursor position, then restore the window position after sending the message. The cursor is not moved, so there is no mouse seizure, but the window may briefly flicker.
+> - Win32 also provides a **Mouse Lock Follow** mode: enable with `MaaControllerSetOption(ctrl, MaaCtrlOption_MouseLockFollow, &enabled, sizeof(bool))` (set `enabled` to `true` to enable, `false` to disable). Designed for TPS/FPS games that lock the mouse to the window in the background. When enabled, the window continuously follows the mouse cursor, and RawInput counter-moves prevent the game from sensing hardware mouse movement. Use `MaaControllerPostRelativeMove` to inject intentional camera rotation while this mode is active. **Note:** On Win32, `MaaControllerPostRelativeMove` requires mouse-lock-follow mode to be active; calling it without this mode will fail. Only supported with MessageInput-based input methods (SendMessage / PostMessage variants).
 
 ### Win32 Screencap
 

docs/zh_cn/2.4-控制方式说明.md

@@ -98,6 +98,7 @@ Win32 下不同程序处理输入的方法不同，不存在一个通用方式
 > - 管理员权限主要取决于目标程序的权限级别，若目标程序为管理员权限，则需以管理员权限运行以保证兼容性。
 > - `WithCursorPos` 系列方式会短暂移动光标到目标位置，发送完消息后会将光标移回原位置，因此会“短暂”抢占鼠标，但不会阻止用户操作。
 > - `WithWindowPos` 系列方式会短暂移动窗口，使目标位置与当前光标位置重合，发送完消息后会将窗口移回原位置。不会移动光标，因此不抢占鼠标，但窗口会短暂闪烁。
+> - Win32 还提供了**鼠标锁定跟随模式**（Mouse Lock Follow）：通过 `MaaControllerSetOption(ctrl, MaaCtrlOption_MouseLockFollow, &enabled, sizeof(bool))` 开启（`enabled` 为 `true` 开启，`false` 关闭），适用于 TPS/FPS 等在后台将鼠标锁定到窗口内的游戏。开启后窗口会始终跟随鼠标移动，同时通过 RawInput 对冲阻止游戏感知硬件鼠标位移。配合 `MaaControllerPostRelativeMove` 可在此模式下注入视角旋转。**注意：** Win32 平台的 `MaaControllerPostRelativeMove` 需要先开启鼠标锁定跟随模式，否则调用将失败。仅支持 MessageInput 系列输入方式（SendMessage / PostMessage 及其变体）。
 
 ### Win32 Screencap
 

include/MaaControlUnit/ControlUnitAPI.h

@@ -99,6 +99,8 @@ class Win32ControlUnitAPI
 {
 public:
     virtual ~Win32ControlUnitAPI() = default;
+
+    virtual bool set_mouse_lock_follow(bool /*enabled*/) { return false; }
 };
 
 class MacOSControlUnitAPI

include/MaaFramework/MaaDef.h

@@ -210,6 +210,13 @@ enum MaaCtrlOptionEnum
     /// value: bool, eg: true; val_size: sizeof(bool)
     MaaCtrlOption_ScreenshotUseRawSize = 3,
 
+    /// Enable or disable mouse-lock-follow mode for Win32 controllers.
+    /// This is designed for TPS/FPS games that lock the mouse to their window in the background.
+    /// Only valid for Win32 controllers using message-based input methods.
+    ///
+    /// value: bool, eg: true; val_size: sizeof(bool)
+    MaaCtrlOption_MouseLockFollow = 4,
+
     // Deprecated
     // Dump all screenshots and actions
     //

source/MaaFramework/Controller/ControllerAgent.cpp

@@ -41,6 +41,8 @@ bool ControllerAgent::set_option(MaaCtrlOption key, MaaOptionValue value, MaaOpt
         return set_image_target_short_side(value, val_size);
     case MaaCtrlOption_ScreenshotUseRawSize:
         return set_image_use_raw_size(value, val_size);
+    case MaaCtrlOption_MouseLockFollow:
+        return set_mouse_lock_follow_option(value, val_size);
 
     default:
         LogError << "Unknown key" << VAR(key) << VAR(value);
@@ -1201,4 +1203,28 @@ bool ControllerAgent::set_image_use_raw_size(MaaOptionValue value, MaaOptionValu
     return true;
 }
 
+bool ControllerAgent::set_mouse_lock_follow_option(MaaOptionValue value, MaaOptionValueSize val_size)
+{
+    LogDebug;
+
+    if (val_size != sizeof(bool)) {
+        LogError << "invalid value size: " << val_size;
+        return false;
+    }
+
+    if (!control_unit_) {
+        LogError << "control_unit_ is nullptr";
+        return false;
+    }
+
+    auto win32_unit = std::dynamic_pointer_cast<MAA_CTRL_UNIT_NS::Win32ControlUnitAPI>(control_unit_);
+    if (!win32_unit) {
+        LogError << "Mouse lock follow is only supported for Win32 controllers.";
+        return false;
+    }
+
+    bool enabled = *reinterpret_cast<bool*>(value);
+    return win32_unit->set_mouse_lock_follow(enabled);
+}
+
 MAA_CTRL_NS_END

source/MaaFramework/Controller/ControllerAgent.h

@@ -288,6 +288,7 @@ class ControllerAgent : public MaaController
     bool set_image_target_long_side(MaaOptionValue value, MaaOptionValueSize val_size);
     bool set_image_target_short_side(MaaOptionValue value, MaaOptionValueSize val_size);
     bool set_image_use_raw_size(MaaOptionValue value, MaaOptionValueSize val_size);
+    bool set_mouse_lock_follow_option(MaaOptionValue value, MaaOptionValueSize val_size);
 
 private:
     bool need_to_stop_ = false;