mirror of
https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
synced 2026-07-16 09:50:40 +08:00
a5b6f17e83
* feat(controller): 集成 MaaWin32ControlUnit 支持 Win32 窗口截图与控制 - 提取公共滑动插值逻辑到 SwipeHelper.hpp，重构 Minitouch/PlayTools 控制器 - 新增 Win32ControlUnitLoader 动态加载 MaaWin32ControlUnit.dll - 新增 Win32Controller 实现 ControllerAPI，适配 touch_down/move/up 接口 - 添加 AsstAsyncAttachWindow 公开 API 用于绑定 Win32 窗口 - 添加 Win32 截图/输入方式的类型定义和枚举常量 * feat(api): 增加同步版本的 AsstAttachWindow 接口 模仿 AsstConnect 实现同步绑定 Win32 窗口的接口，方便简单场景下直接调用。 该接口标记为 deprecated，建议使用异步版本 AsstAsyncAttachWindow。 * fix: can build MaaCore * feat: 完成整体适配 * feat(ci): 添加 MaaFramework Win32ControlUnit 下载步骤 使用 robinraju/release-downloader 从 MaaFramework 最新 release 下载 win-x64 版本并提取 MaaWin32ControlUnit 到构建产物中 * docs: 添加 Win32Controller 调试所需 MaaWin32ControlUnit 的说明 在开发文档的环境配置步骤中说明调试 Win32Controller 需要手动下载 MaaWin32ControlUnit.dll，并欢迎社区贡献自动下载脚本 * fix(i18n): 修改 UseAttachWindowWarning 措辞为"仅供尝鲜" * fix: 小细节修复 * ci: fix maafw filename * feat: PC 移至连接配置 * feat: 调整描述 * chore: 调整 PC 在连接配置中的顺序 * feat: 设置指引和开始唤醒界面 PC 选项绑定 --------- Co-authored-by: uye <99072975+ABA2396@users.noreply.github.com>
178 lines
7.3 KiB
Markdown
178 lines
7.3 KiB
Markdown
---
|
|
order: 1
|
|
icon: iconoir:developer
|
|
---
|
|
|
|
# Development Guide
|
|
|
|
::: tip
|
|
This page mainly describes the PR workflow and MAA's file formatting requirements. If you want to learn specifically how to make changes to MAA's operational logic, please refer to the [Protocol Documentation](../protocol/)
|
|
:::
|
|
|
|
::: tip
|
|
You can [Ask DeepWiki](https://deepwiki.com/MaaAssistantArknights/MaaAssistantArknights) to learn about the overall architecture of the MAA project.
|
|
:::
|
|
|
|
## I don't know programming but just want to modify some JSON files/documents, how can I do it?
|
|
|
|
Welcome to the [Web-based PR Tutorial](./pr-tutorial.md) that anyone can understand (purely web-based on Github.com)
|
|
|
|
## I want to make simple modifications to a few lines of code, but configuring the environment is too tedious and pure web editing is difficult to use. What should I do?
|
|
|
|
Use the [GitHub Codespaces](https://github.com/codespaces) online development environment and try it out!
|
|
|
|
We've preset several different development environments for you to choose from:
|
|
|
|
- Blank environment with a bare Linux container (default)
|
|
|
|
[](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2Fdevcontainer.json)
|
|
|
|
- Lightweight environment, suitable for documentation site frontend development
|
|
|
|
[](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2F0%2Fdevcontainer.json)
|
|
|
|
- Full environment, suitable for MAA Core related development (not recommended, suggest local development with full environment setup. See next section)
|
|
|
|
[](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2F1%2Fdevcontainer.json)
|
|
|
|
## Complete Environment Setup (Windows)
|
|
|
|
1. If you forked the repository long ago, first delete it via your repository's `Settings` at the bottom.
|
|
2. Visit the [MAA main repository](https://github.com/MaaAssistantArknights/MaaAssistantArknights), click `Fork`, then `Create fork`.
|
|
3. Clone the dev branch of your repository with submodules:
|
|
|
|
```bash
|
|
git clone --recurse-submodules <your repository link> -b dev
|
|
```
|
|
|
|
::: warning
|
|
If using Git GUI clients like Visual Studio without `--recurse-submodules` support, run `git submodule update --init` after cloning to initialize submodules.
|
|
:::
|
|
|
|
4. Download prebuilt third-party libraries
|
|
**Python environment required - search for Python installation tutorials if needed**
|
|
_(tools/maadeps-download.py is located in the project root)_
|
|
|
|
```cmd
|
|
python tools/maadeps-download.py
|
|
```
|
|
|
|
5. Configure development environment
|
|
- Download and install `CMake`
|
|
- Download and install `Visual Studio 2026 Community`, selecting `Desktop development with C++` and `.NET Desktop Development` during installation.
|
|
|
|
6. Execute cmake project configuration
|
|
|
|
```cmd
|
|
mkdir -p build
|
|
cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON
|
|
```
|
|
|
|
7. Double-click `build/MAA.slnx` to open the project in Visual Studio.
|
|
8. Configure Visual Studio settings
|
|
- Select `Debug` and `x64` in the top configuration bar
|
|
- Right-click `MaaWpfGui` - Set as Startup Project
|
|
- Press F5 to run
|
|
|
|
::: tip
|
|
To debug Win32Controller (Windows window control) features, you need to manually download the corresponding platform package from [MaaFramework Releases](https://github.com/MaaXYZ/MaaFramework/releases), and place `MaaWin32ControlUnit.dll` from the `bin` directory into MAA's DLL directory (e.g. `build/bin/Debug`). PRs for an auto-download script are welcome!
|
|
:::
|
|
|
|
9. Now you're ready to happily ~~mess around~~ start developing!
|
|
10. Commit regularly with meaningful messages during development
|
|
If you're not familiar with git usage, you might want to create a new branch for changes instead of committing directly to `dev`:
|
|
|
|
```bash
|
|
git branch your_own_branch
|
|
git checkout your_own_branch
|
|
```
|
|
|
|
This keeps your changes isolated from upstream `dev` updates.
|
|
|
|
11. After development, push your local branch (e.g. `dev`) to your remote repository:
|
|
|
|
```bash
|
|
git push origin dev
|
|
```
|
|
|
|
12. Submit a Pull Request at the [MAA main repository](https://github.com/MaaAssistantArknights/MaaAssistantArknights). Ensure your changes are based on the `dev` branch, not `master`.
|
|
13. To sync upstream changes:
|
|
1. Add upstream repository:
|
|
|
|
```bash
|
|
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
|
|
```
|
|
|
|
2. Fetch updates:
|
|
|
|
```bash
|
|
git fetch upstream
|
|
```
|
|
|
|
3. Rebase (recommended) or merge:
|
|
|
|
```bash
|
|
git rebase upstream/dev # rebase
|
|
```
|
|
|
|
or
|
|
|
|
```bash
|
|
git merge # merge
|
|
```
|
|
|
|
4. Repeat steps 8, 9, 10, 11.
|
|
|
|
::: tip
|
|
After opening Visual Studio, Git operations can be performed using VS's built-in "Git Changes" instead of command-line tools.
|
|
:::
|
|
|
|
## MAA File Formatting Requirements
|
|
|
|
MAA uses a series of formatting tools to ensure that the code and resource files in the repository are visually unified for easy maintenance and reading.
|
|
|
|
Please ensure that it has been formatted before submission, or [enable Pre-commit Hooks for automatic formatting](#use-pre-commit-hooks-to-automatically-format-code).
|
|
|
|
The currently enabled formatting tools are as follows:
|
|
|
|
| File Type | Format Tool |
|
|
| --------- | --------------------------------------------------------------- |
|
|
| C++ | [clang-format](https://clang.llvm.org/docs/ClangFormat.html) |
|
|
| Json/Yaml | [Prettier](https://prettier.io/) |
|
|
| Markdown | [markdownlint](https://github.com/DavidAnson/markdownlint-cli2) |
|
|
|
|
### Use Pre-commit Hooks to Automatically Format Code
|
|
|
|
1. Ensure that you have Python and Node environments on your computer.
|
|
|
|
2. Execute the following command in the root directory of the project:
|
|
|
|
```bash
|
|
pip install pre-commit
|
|
pre-commit install
|
|
```
|
|
|
|
If pre-commit still cannot be used after pip install, please check if the pip installation path has been added to the PATH.
|
|
|
|
The formatting tool will automatically run every time you submit to ensure that your code format conforms to the style guide.
|
|
|
|
### Enable clang-format in Visual Studio
|
|
|
|
1. Install clang-format version 20.1.0 or higher.
|
|
|
|
```bash
|
|
python -m pip install clang-format
|
|
```
|
|
|
|
2. Use tools like 'Everything' to locate the installation location of clang-format.exe. As a reference, if you are using Anaconda, clang-format.exe will be installed in YourAnacondaPath/Scripts/clang-format.exe.
|
|
3. In Visual Studio, search for 'clang-format' in Tools-Options.
|
|
4. Click `Enable ClangFormat support` and select `Use custom clang-format.exe file` and choose the `clang-format.exe` located in Step 2.
|
|
|
|
|
|
|
|
You are all set with the clang-format integrated in Visual Studio supporting c++20 features!
|
|
|
|
You can also format with `tools\ClangFormatter\clang-formatter.py` directly, by executing in the root folder of the project:
|
|
|
|
- `python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MaaCore`
|