babalae/better-genshin-impact · error · ArgumentException

游戏分辨率必须是16:9的分辨率

Error message

游戏分辨率必须是16:9的分辨率

What it means

Thrown by GlobalMethod.SetGameMetrics when the provided width and height do not form a 16:9 aspect ratio (checked via width * 9 != height * 16). All coordinate calculations, mouse movement scaling, and UI element matching in this project assume a 16:9 game resolution because Genshin Impact only renders at that aspect ratio.

Source

Thrown at BetterGenshinImpact/Core/Script/Dependence/GlobalMethod.cs:162

        {
            throw new ArgumentException($"键盘编码必须是VirtualKeyCodes枚举中的值，当前传入的 {key} 不合法");
        }
    }

    #endregion 键盘操作

    #region 鼠标操作

    private static int _gameWidth = 1920;
    private static int _gameHeight = 1080;
    private static double _dpi = 1;

    public static void SetGameMetrics(int width, int height, double dpi = 1)
    {
        // 必须16:9 的分辨率
        if (width * 9 != height * 16)
        {
            throw new ArgumentException("游戏分辨率必须是16:9的分辨率");
        }

        _gameWidth = width;
        _gameHeight = height;
        _dpi = dpi;
    }

    public static double[] GetGameMetrics()
    {
        return [_gameWidth, _gameHeight, _dpi];
    }

    public static void MoveMouseBy(int x, int y)
    {
        var realDpi = TaskContext.Instance().DpiScale;
        x = (int)(x * realDpi / _dpi);
        y = (int)(y * realDpi / _dpi);
        Simulation.SendInput.Mouse.MoveMouseBy(x, y);

View on GitHub (pinned to a7cb36712d)

Solutions

1. Ensure the game runs at a 16:9 resolution (1920x1080, 2560x1440, 3840x2160, 1600x900, 1280x720).
2. Derive width/height from the actual game capture region rather than the display resolution.
3. Validate the aspect ratio before calling: if (width * 9 != height * 16) adjust or warn.
4. If the game is running in borderless/windowed mode, set the window to a 16:9 size.

Example fix

// before
GlobalMethod.SetGameMetrics(displayWidth, displayHeight);

// after
// ensure 16:9 by deriving height from width
var gameHeight = gameWidth * 9 / 16;
GlobalMethod.SetGameMetrics(gameWidth, gameHeight, dpi);

// Validate 16:9 aspect ratio before calling SetGameMetrics
if (width * 9 != height * 16)
    throw new ArgumentException($"Resolution {width}x{height} is not 16:9. Use e.g. 1920x1080, 2560x1440.");
GlobalMethod.SetGameMetrics(width, height, dpi);

static bool Is16by9(int width, int height) => width * 9 == height * 16;

When it happens

Trigger: Calling GlobalMethod.SetGameMetrics(width, height) with a non-16:9 resolution such as 1920x1080 (valid) vs 2560x1080 (21:9, invalid) vs 1920x1200 (16:10, invalid).

Common situations: User has an ultrawide monitor and the game is windowed at a non-16:9 size. Script hardcodes resolution from the system display instead of the game capture region. Custom DPI or scaling settings produce non-standard dimensions.

Related errors

• 鼠标坐标超出游戏窗口范围
• 游戏窗口分辨率不是 16:9
• 游戏窗口分辨率不是 16:9 ！无法使用地图追踪功能！
• 游戏窗口分辨率小于 1920x1080 ！无法使用地图追踪功能！
• 游戏窗口分辨率不是 16:9

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/b089feee383a4c43. Report an issue: GitHub.