mirror of
https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
synced 2026-07-16 01:40:46 +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>
184 lines
7.3 KiB
Markdown
184 lines
7.3 KiB
Markdown
---
|
|
order: 1
|
|
icon: iconoir:developer
|
|
---
|
|
|
|
# 개발 가이드
|
|
|
|
::: tip
|
|
본 페이지는 주로 PR 과정 및 MAA의 파일 포맷 요구사항을 설명합니다. MAA의 실행 로직 변경에 대한 구체적인 내용은 [프로토콜 문서](../protocol/)를 참고하세요.
|
|
:::
|
|
|
|
::: tip
|
|
[DeepWiki에 문의하여](https://deepwiki.com/MaaAssistantArknights/MaaAssistantArknights) MAA 프로젝트의 전체적인 아키텍처를 개략적으로 이해할 수 있습니다.
|
|
:::
|
|
|
|
## 프로그래밍을 잘 모르지만, json 파일과 docs 문서를 수정하고싶어요. 어떻게 해야하나요?
|
|
|
|
[웹 기반 PR 가이드](./pr-tutorial.md)를 참고하세요! (GitHub.com 웹사이트에서만 가능합니다)
|
|
|
|
## 몇 줄의 코드만 간단하게 수정하고 싶지만 환경 설정이 너무 복잡하고, 순수 웹 편집도 불편해요. 어떻게 해야 하나요?
|
|
|
|
[GitHub Codespaces](https://github.com/codespaces) 온라인 개발 환경을 사용해보세요!
|
|
|
|
다음과 같은 다양한 개발 환경을 사전에 설정했습니다：
|
|
|
|
- 빈 환경 (순수 Linux 컨테이너) (기본값)
|
|
|
|
[](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2Fdevcontainer.json)
|
|
|
|
- 경량 환경, 문서 사이트 프론트엔드 개발에 적합
|
|
|
|
[](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2F0%2Fdevcontainer.json)
|
|
|
|
- 전체 환경, MAA Core 관련 개발에 적합 (사용 권장하지 않음, 로컬 개발 권장, 관련 환경을 완전히 설정, 다음 섹션 참조)
|
|
|
|
[](https://codespaces.new/MaaAssistantArknights/MaaAssistantArknights?devcontainer_path=.devcontainer%2F1%2Fdevcontainer.json)
|
|
|
|
## 완전한 환경 설정 (Windows)
|
|
|
|
1. 이전에 fork 한 기록이 있다면 저장소 Settings 맨 아래에서 삭제
|
|
2. [MAA 메인 저장소](https://github.com/MaaAssistantArknights/MaaAssistantArknights)에서 Fork → Create fork 클릭
|
|
3. 본인 저장소의 dev 브랜치를 서브모듈 포함 클론:
|
|
|
|
```bash
|
|
git clone --recurse-submodules <저장소 git 링크> -b dev
|
|
```
|
|
|
|
::: warning
|
|
Visual Studio 등 --recurse-submodules 미지원 Git GUI 사용 시, 클론 후 다음 실행:
|
|
|
|
```bash
|
|
git submodule update --init
|
|
```
|
|
|
|
:::
|
|
|
|
4. 사전 빌드된 외부 라이브러리 다운로드
|
|
|
|
**Python 환경 필요 (별도 설치 필요)**
|
|
|
|
```cmd
|
|
python tools/maadeps-download.py
|
|
```
|
|
|
|
5. 개발 환경 구성
|
|
- `CMake` 다운로드 및 설치
|
|
- Visual Studio 2026 Community 설치 시 `C++ 데스크톱 개발` 및 `.NET 데스크톱 개발` 필수 선택
|
|
|
|
6. cmake 프로젝트 구성 실행
|
|
|
|
```cmd
|
|
mkdir -p build
|
|
cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON
|
|
```
|
|
|
|
7. `build/MAA.slnx` 파일을 더블 클릭하여 엽니다. Visual Studio가 자동으로 전체 프로젝트를 로드합니다.
|
|
8. VS 설정
|
|
- 상단 구성에서 `Debug` `x64` 선택
|
|
- `MaaWpfGui` 우클릭 → 시작 프로젝트로 설정
|
|
- F5 키를 눌러 실행
|
|
|
|
::: tip
|
|
Win32Controller(Windows 창 제어) 관련 기능을 디버깅하려면 [MaaFramework Releases](https://github.com/MaaXYZ/MaaFramework/releases)에서 해당 플랫폼 압축 파일을 다운로드하고, `bin` 디렉토리의 `MaaWin32ControlUnit.dll`을 MAA DLL과 같은 디렉토리(예: `build/bin/Debug`)에 배치해야 합니다. 자동 다운로드 스크립트 PR 환영!
|
|
:::
|
|
|
|
9. 이제 자유롭게 ~~개조~~ 개발 시작!
|
|
10. 주기적 커밋 (메시지 필수 작성)
|
|
Git 초보자는 dev 브랜치 대신 새 브랜치 생성 권장:
|
|
|
|
```bash
|
|
git branch your_own_branch
|
|
git checkout your_own_branch
|
|
```
|
|
|
|
dev 브랜치 업데이트 영향에서 자유로움
|
|
|
|
11. 개발 완료 후 변경사항 원격 저장소로 푸시:
|
|
|
|
```bash
|
|
git push origin dev
|
|
```
|
|
|
|
12. [MAA 메인 저장소](https://github.com/MaaAssistantArknights/MaaAssistantArknights)에서 Pull Request 제출 (master 대신 dev 브랜치 지정 필수)
|
|
13. 업스트림 저장소 변경사항 동기화 방법:
|
|
1. 업스트림 저장소 추가:
|
|
|
|
```bash
|
|
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
|
|
```
|
|
|
|
2. 변경사항 가져오기:
|
|
|
|
```bash
|
|
git fetch upstream
|
|
```
|
|
|
|
3. 리베이스(권장) 또는 병합:
|
|
|
|
```bash
|
|
git rebase upstream/dev
|
|
```
|
|
|
|
또는
|
|
|
|
```bash
|
|
git merge
|
|
```
|
|
|
|
4. 단계 8, 9, 10, 11 반복 수행
|
|
|
|
::: tip
|
|
Visual Studio 실행 시 Git 작업은 "Git 변경" 탭에서 명령어 없이 처리 가능
|
|
:::
|
|
|
|
## MAA 파일의 포매팅 요구 사항
|
|
|
|
MAA는 리포지토리의 코드 및 리소스 파일들을 아름답고 일관적으로 유지하기 위해 일련의 포매팅 도구를 사용합니다.
|
|
|
|
제출하기 전에 포맷을 지정했거나 [Pre-commit Hooks를 사용하여 자동 포매팅을 활성화](#pre-commit-hooks를-사용하여-자동-포매팅을-활성화)를 했는지 확인하세요.
|
|
|
|
현재 활성화된 포매팅 도구는 다음과 같습니다:
|
|
|
|
| 파일 유형 | 포매팅 도구 |
|
|
| --------- | --------------------------------------------------------------- |
|
|
| C++ | [clang-format](https://clang.llvm.org/docs/ClangFormat.html) |
|
|
| Json/Yaml | [Prettier](https://prettier.io/) |
|
|
| Markdown | [markdownlint](https://github.com/DavidAnson/markdownlint-cli2) |
|
|
|
|
### Pre-commit Hooks를 사용하여 자동 포매팅을 활성화
|
|
|
|
1. Python 및 Node 환경이 컴퓨터에 설치되어 있는지 확인하세요.
|
|
|
|
2. 프로젝트 루트 디렉터리에서 다음 명령을 실행하세요.
|
|
|
|
```bash
|
|
pip install pre-commit
|
|
pre-commit install
|
|
```
|
|
|
|
pip 설치 후에도 Pre-commit을 실행할 수 없다면, PIP 설치 경로가 PATH에 추가되었는지 확인하세요.
|
|
|
|
이제, 매번 커밋할 때마다 포매팅 도구가 자동으로 실행되어 코드 형식이 규칙에 맞는지 확인합니다.
|
|
|
|
### Visual Studio에서 clang-format 사용 설정
|
|
|
|
1. clang-format 20.1.0 또는 그 이상 버전을 설치합니다.
|
|
|
|
```bash
|
|
python -m pip install clang-format
|
|
```
|
|
|
|
2. Everything 등의 도구를 사용하여 clang-format.exe의 설치 위치를 찾습니다. 참고로 Anaconda를 사용하는 경우 clang-format.exe는 YourAnacondaPath/Scripts/clang-format.exe에 설치됩니다.
|
|
|
|
3. Visual Studio에서 `도구`-`옵션`을 검색하여 `clang-format`을 클릭합니다.
|
|
4. `ClangFormat 지원 활성화`를 클릭하고 아래의 `사용자 정의 clang-format.exe 파일 사용`을 선택한 다음 2단계에서 찾은 `clang-format.exe`를 선택합니다.
|
|
|
|
|
|
|
|
이제 Visual Studio에서 C++20 구문을 지원하는 clang-format을 사용할 수 있습니다!
|
|
|
|
또한 프로젝트 루트에서 `tools\ClangFormatter\clang-formatter.py`를 실행하여 직접 clang-format을 호출하여 포맷팅할 수도 있습니다.
|
|
|
|
- `python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MaaCore`
|