Skip to content

feat(connection): support native Win32 clients - #575

Draft
hwJinny wants to merge 1 commit into
MaaAssistantArknights:mainfrom
hwJinny:codex/win32-attach-window
Draft

feat(connection): support native Win32 clients#575
hwJinny wants to merge 1 commit into
MaaAssistantArknights:mainfrom
hwJinny:codex/win32-attach-window

Conversation

@hwJinny

@hwJinny hwJinny commented Aug 13, 2026

Copy link
Copy Markdown

Summary

  • add a safe AsstAsyncAttachWindow wrapper and Windows-only exact-window discovery
  • add the Win32 connection preset with PID/executable disambiguation and PC platform resources
  • route normal maa run tasks through native window attachment without ADB and disable StartUp game launching
  • add maa connection test --profile <name> --screencap --json for ADB, PlayCover, and Win32 onboarding probes
  • require MaaWin32ControlUnit.dll in the Windows MaaCore installation

Safety

  • only visible top-level windows with an exact title are eligible
  • optional PID and canonical executable path must match the owning process
  • Win32 is compile-time rejected outside Windows and never invokes ADB
  • ambiguous matches fail closed

Tests

  • Windows x64 all-features Clippy with -D warnings
  • Windows x64 release build
  • maa-core: 22 passed
  • maa-cli: 297 passed, 26 ignored
  • Linux x64 Zig build and test-binary compilation

Live verification still required

  • attach and screenshot smoke test against each official PC client region on Windows 10/11

Summary by Sourcery

为官方 Windows 客户端新增原生 Win32 连接支持,并加入 CLI 连接测试流程;将基于窗口的附着能力集成到 MaaCore 和 maa-cli 中,同时更新配置、安装程序和文档。

New Features:

  • 引入 Win32 连接预设,可在不使用 ADB 的情况下附着到选定的原生 Windows 游戏窗口,并自动加载 PC 平台资源。
  • 新增类型化的 Assistant::async_attach_window API 和窗口分辨率工具,以支持对可见的顶层 Win32 窗口进行安全附着,并可选通过 PID 和可执行文件进行区分。
  • 暴露 maa connection test CLI 命令,支持截图探测和可选的 JSON 输出,用于验证各预设下已配置连接的有效性。

Enhancements:

  • 确保为 Win32 连接准备的任务跳过基于包的游戏启动流程,并在附着到已运行的 PC 客户端时禁用 StartUp.start_game_enabled
  • 扩展配置模式、示例和资源自动选择逻辑,以覆盖 Win32 特定的连接字段和 PC 平台资源。
  • 在 Windows 上要求 MaaWin32ControlUnit.dll 与 MaaCore 一同存在,并在安装程序/测试中加入对其存在性的校验。

Tests:

  • 添加针对 Win32 连接参数解析、窗口选择与控制单元验证、非 Windows 环境拒绝行为以及连接探测工具的单元测试。
  • 更新现有测试以覆盖与 Win32 相关的默认值、模式变更,并确保连接路由在处理 Win32 预设时绝不构造 ADB 请求。
Original summary in English

Summary by Sourcery

Add native Win32 connection support for the official Windows client and a CLI connection test flow, integrating window-based attachment into MaaCore and maa-cli while updating configuration, installer, and docs.

New Features:

  • Introduce a Win32 connection preset that attaches to a selected native Windows game window without using ADB and automatically loads PC platform resources.
  • Add a typed Assistant::async_attach_window API and window resolution utilities to support safe attachment to visible top-level Win32 windows with optional PID and executable disambiguation.
  • Expose a maa connection test CLI command with screenshot probing and optional JSON output to validate configured connections across presets.

Enhancements:

  • Ensure tasks prepared for Win32 connections skip package-based game launching and disable StartUp.start_game_enabled when attaching to an already-running PC client.
  • Extend configuration schema, examples, and resource auto-selection to cover Win32-specific connection fields and PC platform resources.
  • Require MaaWin32ControlUnit.dll alongside MaaCore on Windows and teach the installer/tests to verify its presence.

Tests:

  • Add unit tests for Win32 connection argument parsing, window selection and control-unit validation, non-Windows rejection behavior, and connection probing utilities.
  • Update existing tests to cover Win32-related defaults, schema changes, and ensure connection routing never constructs ADB requests for Win32 presets.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants