MaaXYZ · ZeroAd-06 · May 17, 2026 · May 25, 2026 · sourcery-ai · May 17, 2026
diff --git a/docs/en_us/2.2-IntegratedInterfaceOverview.md b/docs/en_us/2.2-IntegratedInterfaceOverview.md
@@ -353,6 +353,9 @@ Set controller options. Will be split into specific options in bindings.
 - ScreenshotTargetShortSide  
     Set screenshot scaling short side to specified length
 
+- ScreenshotTargetExpand  
+    Scale screenshots to a reference resolution `(width, height)` using Unity Canvas Scaler **Expand** semantics: `scale = max(width / raw_width, height / raw_height)`. The scale is applied uniformly to both axes so the source aspect ratio is preserved and both output dimensions are >= the reference. No cropping, no non-uniform stretching. Mutually exclusive with `ScreenshotTargetLongSide` / `ScreenshotTargetShortSide`; setting any of them resets the others. Value is an `int32_t` array of length 2: `{ width, height }`.
+
 - ScreenshotUseRawSize  
     No scaling for screenshots
 

diff --git a/docs/en_us/3.3-ProjectInterfaceV2.md b/docs/en_us/3.3-ProjectInterfaceV2.md
@@ -118,10 +118,13 @@ We have designated the version number for the independent release (January 30, 2
     and `WlRoots` (Linux only).
 
   - **display_short_side** `number`  
-    The short side length of the default scaled resolution, used for screen adaptation. _Optional_, defaults to 720. Mutually exclusive with `display_long_side` and `display_raw`.
+    The short side length of the default scaled resolution, used for screen adaptation. _Optional_, defaults to 720. Mutually exclusive with `display_long_side`, `display_expand`, and `display_raw`.
 
   - **display_long_side** `number`  
-    The long side length of the default scaled resolution, used for screen adaptation. _Optional._ Mutually exclusive with `display_short_side` and `display_raw`.
+    The long side length of the default scaled resolution, used for screen adaptation. _Optional._ Mutually exclusive with `display_short_side`, `display_expand`, and `display_raw`.
+
+  - **display_expand** `[number, number]`  
+    Reference resolution `[width, height]` with Unity Canvas Scaler "Expand" semantics: `scale = max(width / raw_width, height / raw_height)`, applied uniformly so the source aspect ratio is preserved and both output dimensions are >= the reference. _Optional._ Mutually exclusive with `display_short_side`, `display_long_side`, and `display_raw`.
 
   - **display_raw** `boolean`  
     Whether to use the original resolution for screenshots without scaling. _Optional_, defaults to false. Mutually exclusive with scaled resolution settings.

diff --git a/docs/zh_cn/2.2-集成接口一览.md b/docs/zh_cn/2.2-集成接口一览.md
@@ -353,6 +353,9 @@
 - ScreenshotTargetShortSide  
     设置截图缩放短边到指定长度
 
+- ScreenshotTargetExpand  
+    以 Unity Canvas Scaler 的 **Expand** 语义按参考分辨率 `(width, height)` 缩放截图：`scale = max(width / raw_width, height / raw_height)`，等比缩放后两边均不小于参考；保持源宽高比，无裁剪、无非等比拉伸。与 `ScreenshotTargetLongSide` / `ScreenshotTargetShortSide` 互斥，设置任一会重置其他。值为长度 2 的 `int32_t` 数组 `{ width, height }`。
+
 - ScreenshotUseRawSize  
     设置截图不缩放
 

diff --git a/docs/zh_cn/3.3-ProjectInterfaceV2协议.md b/docs/zh_cn/3.3-ProjectInterfaceV2协议.md
@@ -117,10 +117,13 @@
     控制器类型，取值为 `Adb`、`Win32`（仅 Windows）、`MacOS`（仅 macOS）、`PlayCover`（仅 macOS）、`Gamepad`（仅 Windows）和 `WlRoots`（仅 Linux）。
 
   - display_short_side `number`  
-    默认缩放分辨率的短边长度，用于屏幕适配。可选，默认720。与`display_long_side`和`display_raw`互斥。
+    默认缩放分辨率的短边长度，用于屏幕适配。可选，默认720。与`display_long_side`、`display_expand`和`display_raw`互斥。
 
   - display_long_side `number`  
-    默认缩放分辨率的长边长度，用于屏幕适配。可选。与`display_short_side`和`display_raw`互斥。
+    默认缩放分辨率的长边长度，用于屏幕适配。可选。与`display_short_side`、`display_expand`和`display_raw`互斥。
+
+  - display_expand `[number, number]`  
+    Unity Canvas Scaler 的 Expand 语义参考分辨率 `[width, height]`：`scale = max(width / raw_width, height / raw_height)`，保持源宽高比，输出两边均不小于参考。可选。与`display_short_side`、`display_long_side`和`display_raw`互斥。
 
   - display_raw `boolean`  
     是否使用原始分辨率进行截图，不进行缩放。可选，默认false。与缩放分辨率设置互斥。

diff --git a/include/MaaFramework/MaaDef.h b/include/MaaFramework/MaaDef.h
@@ -242,6 +242,16 @@ enum MaaCtrlOptionEnum
     ///
     /// value: int32_t array of virtual key codes; val_size: sizeof(int32_t) * count
     MaaCtrlOption_BackgroundManagedKeys = 7,
+
+    /// Scale screenshot to fit a reference (width, height) using Unity Canvas
+    /// Scaler "Expand" semantics: scale = max(W / raw_width, H / raw_height),
+    /// applied uniformly to both axes so the source aspect ratio is preserved
+    /// and both output dimensions are >= the reference (W, H).
+    /// Mutually exclusive with ScreenshotTargetLongSide / ScreenshotTargetShortSide;
+    /// setting any of these resets the others. Ignored when ScreenshotUseRawSize is true.
+    ///
+    /// value: int32_t[2] = { width, height }; val_size: sizeof(int32_t) * 2
+    MaaCtrlOption_ScreenshotTargetExpand = 8,
 };
 
 typedef MaaOption MaaTaskerOption;

diff --git a/source/MaaAgentClient/Client/AgentClient.cpp b/source/MaaAgentClient/Client/AgentClient.cpp
@@ -2481,6 +2481,28 @@ bool AgentClient::handle_controller_set_option(const json::value& j)
         ret = controller->set_option(key, keys.data(), sizeof(int32_t) * keys.size());
         break;
     }
+    case MaaCtrlOption_ScreenshotTargetExpand: {
+        if (!req.value.is_array() || req.value.as_array().size() != 2) {
+            LogError << "ScreenshotTargetExpand value must be a 2-element array" << VAR(req.value.type_name());
+            break;
+        }
+        int32_t dims[2] = { 0, 0 };
+        const auto& arr = req.value.as_array();
+        bool ok = true;
+        for (size_t i = 0; i < 2; ++i) {
+            if (!arr[i].is_number()) {
+                LogError << "ScreenshotTargetExpand array element must be a number" << VAR(arr[i].type_name());
+                ok = false;
+                break;
+            }
+            dims[i] = static_cast<int32_t>(arr[i].as_integer());
+        }
+        if (!ok || dims[0] <= 0 || dims[1] <= 0) {
+            break;
+        }
+        ret = controller->set_option(key, dims, sizeof(dims));
+        break;
+    }
     default:
         LogError << "unknown key" << VAR(req.key);
         break;

diff --git a/source/MaaAgentServer/RemoteInstance/RemoteController.cpp b/source/MaaAgentServer/RemoteInstance/RemoteController.cpp
@@ -57,6 +57,19 @@ bool RemoteController::set_option(MaaCtrlOption key, MaaOptionValue value, MaaOp
         break;
     }
 
+    case MaaCtrlOption_ScreenshotTargetExpand: {
+        if (val_size != sizeof(int32_t) * 2) {
+            LogError << "invalid val_size for expand option" << VAR(key) << VAR(val_size);
+            return false;
+        }
+        auto* dims = reinterpret_cast<const int32_t*>(value);
+        json::array arr;
+        arr.emplace_back(dims[0]);
+        arr.emplace_back(dims[1]);
+        jvalue = std::move(arr);
+        break;
+    }
+
     default:
         LogError << "unknown key" << VAR(key);
         return false;

diff --git a/source/MaaFramework/Controller/ControllerAgent.cpp b/source/MaaFramework/Controller/ControllerAgent.cpp
@@ -39,6 +39,8 @@ bool ControllerAgent::set_option(MaaCtrlOption key, MaaOptionValue value, MaaOpt
         return set_image_target_long_side(value, val_size);
     case MaaCtrlOption_ScreenshotTargetShortSide:
         return set_image_target_short_side(value, val_size);
+    case MaaCtrlOption_ScreenshotTargetExpand:
+        return set_image_target_expand(value, val_size);
     case MaaCtrlOption_ScreenshotUseRawSize:
         return set_image_use_raw_size(value, val_size);
     case MaaCtrlOption_MouseLockFollow:
@@ -1097,6 +1099,16 @@ bool ControllerAgent::calc_target_image_size()
         return true;
     }
 
+    if (image_target_expand_width_ > 0 && image_target_expand_height_ > 0) {
+        double sx = static_cast<double>(image_target_expand_width_) / image_raw_width_;
+        double sy = static_cast<double>(image_target_expand_height_) / image_raw_height_;
+        double scale = std::max(sx, sy);
+        image_target_width_ = static_cast<int>(std::round(image_raw_width_ * scale));
+        image_target_height_ = static_cast<int>(std::round(image_raw_height_ * scale));
+        LogInfo << "expand" << VAR(scale) << VAR(image_target_width_) << VAR(image_target_height_);
+        return true;
+    }
+
     if (image_target_long_side_ == 0 && image_target_short_side_ == 0) {
         LogError << "Invalid image target size";
         return false;
@@ -1168,6 +1180,8 @@ bool ControllerAgent::set_image_target_long_side(MaaOptionValue value, MaaOption
     }
     image_target_long_side_ = *reinterpret_cast<const int32_t*>(value);
     image_target_short_side_ = 0;
+    image_target_expand_width_ = 0;
+    image_target_expand_height_ = 0;
 
     clear_target_image_size();
 
@@ -1185,13 +1199,39 @@ bool ControllerAgent::set_image_target_short_side(MaaOptionValue value, MaaOptio
     }
     image_target_long_side_ = 0;
     image_target_short_side_ = *reinterpret_cast<const int32_t*>(value);
+    image_target_expand_width_ = 0;
+    image_target_expand_height_ = 0;
 
     clear_target_image_size();
 
     LogInfo << "image_target_height_ = " << image_target_short_side_;
     return true;
 }
 
+bool ControllerAgent::set_image_target_expand(MaaOptionValue value, MaaOptionValueSize val_size)
+{
+    LogDebug;
+
+    if (val_size != sizeof(int32_t) * 2) {
+        LogError << "invalid value size: " << val_size;
+        return false;
+    }
+    auto* arr = reinterpret_cast<const int32_t*>(value);
+    if (arr[0] <= 0 || arr[1] <= 0) {
+        LogError << "invalid expand size" << VAR(arr[0]) << VAR(arr[1]);
+        return false;
+    }
+    image_target_expand_width_ = arr[0];
+    image_target_expand_height_ = arr[1];
+    image_target_long_side_ = 0;
+    image_target_short_side_ = 0;
+
+    clear_target_image_size();
+
+    LogInfo << VAR(image_target_expand_width_) << VAR(image_target_expand_height_);
+    return true;
+}
+
 bool ControllerAgent::set_image_use_raw_size(MaaOptionValue value, MaaOptionValueSize val_size)
 {
     LogDebug;

diff --git a/source/MaaFramework/Controller/ControllerAgent.h b/source/MaaFramework/Controller/ControllerAgent.h
@@ -287,6 +287,7 @@ class ControllerAgent : public MaaController
 private: // options
     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_target_expand(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);
     bool set_screenshot_resize_method(MaaOptionValue value, MaaOptionValueSize val_size);
@@ -307,6 +308,8 @@ class ControllerAgent : public MaaController
     bool image_use_raw_size_ = false;
     int image_target_long_side_ = 0;
     int image_target_short_side_ = 720;
+    int image_target_expand_width_ = 0;
+    int image_target_expand_height_ = 0;
     int image_target_width_ = 0;
     int image_target_height_ = 0;
     int image_raw_width_ = 0;

diff --git a/source/MaaPiCli/Impl/Configurator.cpp b/source/MaaPiCli/Impl/Configurator.cpp
@@ -312,6 +312,7 @@ std::optional<RuntimeParam> Configurator::generate_runtime() const
     // 设置分辨率配置
     runtime.display_config.short_side = controller.display_short_side;
     runtime.display_config.long_side = controller.display_long_side;
+    runtime.display_config.expand = controller.display_expand;
     runtime.display_config.raw = controller.display_raw;
 
     std::vector<InterfaceData::Agent> agents = std::visit(

diff --git a/source/MaaPiCli/Impl/Runner.cpp b/source/MaaPiCli/Impl/Runner.cpp
@@ -143,6 +143,10 @@ bool Runner::run(const RuntimeParam& param)
         MaaBool raw = true;
         MaaControllerSetOption(controller_handle, MaaCtrlOption_ScreenshotUseRawSize, &raw, sizeof(raw));
     }
+    else if (param.display_config.expand.has_value()) {
+        int32_t expand[2] = { param.display_config.expand->at(0), param.display_config.expand->at(1) };
+        MaaControllerSetOption(controller_handle, MaaCtrlOption_ScreenshotTargetExpand, expand, sizeof(expand));
+    }
     else if (param.display_config.long_side.has_value()) {
         int long_side = param.display_config.long_side.value();
         MaaControllerSetOption(controller_handle, MaaCtrlOption_ScreenshotTargetLongSide, &long_side, sizeof(long_side));

diff --git a/source/binding/NodeJS/src/apis/controller.cpp b/source/binding/NodeJS/src/apis/controller.cpp
@@ -125,6 +125,14 @@ void ControllerImpl::set_screenshot_target_short_side(int32_t value)
     }
 }
 
+void ControllerImpl::set_screenshot_target_expand(std::tuple<int32_t, int32_t> value)
+{
+    int32_t arr[2] = { std::get<0>(value), std::get<1>(value) };
+    if (!MaaControllerSetOption(controller, MaaCtrlOption_ScreenshotTargetExpand, arr, sizeof(arr))) {
+        throw maajs::MaaError { "Controller set screenshot_target_expand failed" };
+    }
+}
+
 void ControllerImpl::set_screenshot_use_raw_size(bool value)
 {
     if (!MaaControllerSetOption(controller, MaaCtrlOption_ScreenshotUseRawSize, &value, sizeof(value))) {
@@ -372,6 +380,7 @@ void ControllerImpl::init_proto(maajs::ObjectType proto, maajs::FunctionType)
     MAA_BIND_FUNC(proto, "remove_sink", ControllerImpl::remove_sink);
     MAA_BIND_SETTER(proto, "screenshot_target_long_side", ControllerImpl::set_screenshot_target_long_side);
     MAA_BIND_SETTER(proto, "screenshot_target_short_side", ControllerImpl::set_screenshot_target_short_side);
+    MAA_BIND_SETTER(proto, "screenshot_target_expand", ControllerImpl::set_screenshot_target_expand);
     MAA_BIND_SETTER(proto, "screenshot_use_raw_size", ControllerImpl::set_screenshot_use_raw_size);
     MAA_BIND_SETTER(proto, "screenshot_resize_method", ControllerImpl::set_screenshot_resize_method);
     MAA_BIND_FUNC(proto, "clear_sinks", ControllerImpl::clear_sinks);

diff --git a/source/binding/NodeJS/src/apis/controller.d.ts b/source/binding/NodeJS/src/apis/controller.d.ts
@@ -150,6 +150,7 @@ declare global {
 
             set screenshot_target_long_side(value: number)
             set screenshot_target_short_side(value: number)
+            set screenshot_target_expand(value: [number, number])
             set screenshot_use_raw_size(value: boolean)
             set screenshot_resize_method(value: number)
 

diff --git a/source/binding/NodeJS/src/apis/controller.h b/source/binding/NodeJS/src/apis/controller.h
@@ -35,6 +35,7 @@ struct ControllerImpl : public maajs::NativeClassBase
     void clear_sinks();
     void set_screenshot_target_long_side(int32_t value);
     void set_screenshot_target_short_side(int32_t value);
+    void set_screenshot_target_expand(std::tuple<int32_t, int32_t> value);
     void set_screenshot_use_raw_size(bool value);
     void set_screenshot_resize_method(int32_t value);
     maajs::ValueType post_connection(maajs::ValueType self, maajs::EnvType env);

diff --git a/source/binding/Python/maa/controller.py b/source/binding/Python/maa/controller.py
@@ -495,6 +495,30 @@ def set_screenshot_target_short_side(self, short_side: int) -> bool:
             )
         )
 
+    def set_screenshot_target_expand(self, width: int, height: int) -> bool:
+        """以 Unity Canvas Scaler 的 Expand 语义按参考分辨率缩放截图 /
+        Scale screenshot to reference (width, height) using Unity Expand semantics
+
+        scale = max(width / raw_width, height / raw_height)，保持源宽高比，
+        输出两边均 >= 参考。与长/短边模式互斥。
+
+        Args:
+            width: 参考宽 / Reference width
+            height: 参考高 / Reference height
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
+        arr = (ctypes.c_int32 * 2)(width, height)
+        return bool(
+            Library.framework().MaaControllerSetOption(
+                self._handle,
+                MaaOption(MaaCtrlOptionEnum.ScreenshotTargetExpand),
+                arr,
+                ctypes.sizeof(arr),
+            )
+        )
+
     def set_screenshot_use_raw_size(self, enable: bool) -> bool:
         """设置截图不缩放 / Set screenshot use raw size without scaling
 

diff --git a/source/binding/Python/maa/define.py b/source/binding/Python/maa/define.py
@@ -152,6 +152,14 @@ class MaaCtrlOptionEnum(IntEnum):
     # value: int32_t array of virtual key codes; val_size: sizeof(int32_t) * count
     BackgroundManagedKeys = 7
 
+    # Scale screenshot to fit a reference (width, height) using Unity Canvas
+    # Scaler "Expand" semantics: scale = max(W / raw_width, H / raw_height),
+    # applied uniformly so the source aspect ratio is preserved and both
+    # output dimensions are >= the reference (W, H).
+    # Mutually exclusive with ScreenshotTargetLongSide / ScreenshotTargetShortSide.
+    # value: int32_t[2] = (width, height); val_size: sizeof(int32_t) * 2
+    ScreenshotTargetExpand = 8
+
 
 class MaaInferenceDeviceEnum(IntEnum):
     CPU = -2

diff --git a/source/include/ProjectInterface/Types.h b/source/include/ProjectInterface/Types.h
@@ -6,6 +6,7 @@
 #include <unordered_map>
 #include <variant>
 #include <vector>
+#include <array>
 
 #include <meojson/json.hpp>
 
@@ -82,9 +83,10 @@ struct InterfaceData
         // 是否需要管理员权限（例如某些 Win32 输入方式需要更高权限）
         bool permission_required = false;
 
-        // 分辨率设置，三者互斥
+        // 分辨率设置，四者互斥
         std::optional<int> display_short_side; // 默认720
         std::optional<int> display_long_side;
+        std::optional<std::array<int, 2>> display_expand; // [width, height], Unity Canvas Scaler "Expand" 语义
         bool display_raw = false;
 
         // 附加资源路径，在 resource.path 加载完成后额外加载
@@ -107,6 +109,7 @@ struct InterfaceData
             MEO_OPT permission_required,
             MEO_OPT display_short_side,
             MEO_OPT display_long_side,
+            MEO_OPT display_expand,
             MEO_OPT display_raw,
             MEO_OPT attach_resource_path,
             MEO_OPT option,
@@ -436,11 +439,12 @@ struct Configuration
 
 struct RuntimeParam
 {
-    // 分辨率设置，三者互斥
+    // 分辨率设置，四者互斥
     struct DisplayConfig
     {
         std::optional<int> short_side; // 默认720
         std::optional<int> long_side;
+        std::optional<std::array<int, 2>> expand; // [width, height], Unity Canvas Scaler "Expand" 语义
         bool raw = false;
     };
 

diff --git a/tools/interface.schema.json b/tools/interface.schema.json
@@ -418,7 +418,17 @@
                 "display_long_side": {
                     "type": "number",
                     "title": "长边分辨率",
-                    "description": "默认缩放分辨率的长边长度，用于屏幕适配。与 display_short_side 和 display_raw 互斥"
+                    "description": "默认缩放分辨率的长边长度，用于屏幕适配。与 display_short_side、display_expand 和 display_raw 互斥"
+                },
+                "display_expand": {
+                    "type": "array",
+                    "items": {
+                        "type": "number"
+                    },
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "title": "Unity Expand 参考分辨率",
+                    "description": "按 Unity Canvas Scaler 的 Expand 语义缩放：scale = max(width / raw_width, height / raw_height)，保持源宽高比，输出两边均不小于参考。格式 [width, height]。与 display_short_side、display_long_side 和 display_raw 互斥"
                 },
                 "display_raw": {
                     "type": "boolean",