開発ガイド

1175字程度約4分

ヒント

本ページは主に PR プロセスおよび MAA のファイルフォーマット要件について説明します。MAA の実行ロジックを変更する具体的な方法については、プロトコル文書を参照してください。

ヒント

DeepWiki に質問して、MAA プロジェクトの全体的なアーキテクチャを概要的に理解することができます。

プログラミングの仕方がわからないので、JSONファイルやドキュメントなどを少し変更したいのですが、どうすればいいですか？

「パラスちゃん」も理解できるGitHubのPull Requestの使用ガイドへようこそ（純WebサイトのPRチュートリアル）

数行のコードを少しだけ変更したいが、環境設定が面倒。純粋なWeb編集も使いにくい。どうすればよいですか？

GitHub Codespacesオンライン開発環境をご利用ください！

次のような、異なる開発環境を事前に準備しています：

空白環境（裸のLinuxコンテナ）（デフォルト）
軽量環境：ドキュメントサイトのフロントエンド開発に適している
完全環境：MAA Core関連の開発に適している（使用は推奨しません。ローカル開発を推奨します。関連環境を完全に設定。次のセクションを参照）

完全な環境セットアップ（Windows）

かなり前にフォークした場合は、まず自分のリポジトリの Settings の一番下で削除します
MAA メインリポジトリを開き、Fork → Create fork をクリック
自身のリポジトリの dev-v2 ブランチをクローン（サブモジュール含む）
```
git clone --recurse-submodules <リポジトリの git リンク> -b dev-v2 --single-branch
```
ヒント
--single-branch で取得されるのは dev-v2 の履歴だけです。あとで別のブランチに切り替えたい場合は、先に git remote set-branches origin '*' を実行してから再度 fetch するか、--single-branch なしでリポジトリを再度クローンして不足しているブランチ情報を取得してください。
注意
Visual Studio など --recurse-submodules パラメータに対応していない Git GUI を使用する場合、クローン後に以下を実行：
```
git submodule update --init
```
事前ビルド済みサードパーティライブラリのダウンロード
Python環境が必要（インストール方法は各自検索）
（tools/maadeps-download.py はプロジェクトルートに配置）
```
python tools/maadeps-download.py
```
開発環境の設定
- CMake をダウンロードしてインストール
- Visual Studio 2026 Community をインストール時、C++ によるデスクトップ開発 と .NET デスクトップ開発 を選択必須
cmake プロジェクト設定を実行
```
cmake --preset windows-x64
```
build/MAA.slnx をダブルクリックで開き、Visual Studio にプロジェクトを自動ロード
VS の設定
- 上部設定バーで Debug x64 を選択
- MaaWpfGui 右クリック → スタートアッププロジェクトに設定
- F5 キーを押して実行
ヒント
Win32Controller（Windows ウィンドウ制御）/ MaaFwAdbController（MaaFramework のタッチモード）関連機能を実行する場合は、python tools/maafw-control-unit-download.py を実行すると、対応プラットフォームの MaaWin32ControlUnit.dll / MaaAdbControlUnit.dll をビルド出力ディレクトリ（デフォルトでは build/bin 配下の最新ディレクトリ、--output-dir で指定可）に自動で配置します。
関連機能をデバッグする場合は、MaaFramework の Debug バージョンを自分でコンパイルし、対応する DLL ファイルを使用する必要があります。そうしないと、ブレークポイントデバッグ中に謎のクラッシュが発生します。
これで自由に改造開発を始められます
一定量の変更ごとにコミット（メッセージ記入必須）
Git 未経験者は dev ブランチ直接変更ではなく新規ブランチ作成推奨：
```
git branch your_own_branch
git checkout your_own_branch
```
これで dev の更新影響を受けずに開発可能
開発完了後、変更をリモートリポジトリへプッシュ：
```
git push origin dev-v2
```
MAA メインリポジトリで Pull Request を提出（master-v2 ではなく dev-v2 ブランチを指定）
上流リポジトリの更新を同期する場合：
1. 上流リポジトリを追加：
```
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
```
2. 更新を取得：
```
git fetch upstream
```
3. リベース（推奨）またはマージ：
```
git rebase upstream/dev-v2
```
  または
```
git merge
```
4. ステップ8、9、10、11 を繰り返し

ヒント

Visual Studio 起動後、Git 操作は「Git 変更」画面からコマンドライン不要で可能

Visual Studio での開発を推奨します。 MAA プロジェクトは主に Visual Studio をベースに構築されており、上記の完全な環境セットアップですべての開発ニーズをカバーし、すぐに使える最高の体験を提供します。VSCode ワークフローは、VSCode + CMake + clangd に精通した開発者向けの代替手段としてのみ提供されており、設定のハードルが比較的高くなります。

VSCodeを好む場合、CMake、clangdなどの拡張機能でコード補完、ナビゲーション、デバッグが可能です。前述の手順1～6（クローン、依存関係、CMake設定）を完了した後、以下の手順で設定できます。

推奨拡張機能

VS Code Marketplace からインストール：

拡張機能	用途
CMake Tools	CMake の設定、ビルド、デバッグ統合
clangd	C++ インテリセンス、コードナビゲーション、診断（LSPベース）
C/C++	C++ プログラムのデバッグ（CMake Tools または launch.json と連携）

ヒント

clangd を使用する場合、C/C++ 拡張機能の IntelliSense を無効化（C_Cpp.intelliSenseEngine を disabled に設定）することを推奨します。競合を避けるためです。

設定手順

VS Code でプロジェクトルートを開く
CMake Tools：ステータスバーで Configure Preset（例：windows-x64、linux-x64）を選択し、Build Preset でビルドを実行
clangd：Linux/macOS ではプリセットで CMAKE_EXPORT_COMPILE_COMMANDS が有効となり、clangd は build/compile_commands.json を自動使用。Windows で clangd の補完・ナビゲーションを使う場合は、まず compile_commands.json を生成する必要があります：
Windows での clangd 設定
- VS Installer で C++ Clang コンパイラ for Windows（clang-cl）をインストールに含める
- windows-x64-clang プリセットに切り替えて Configure を1回実行すると build/ に compile_commands.json が生成され、clangd が利用可能になります
- このプリセットは clang-cl を使用するため MSVC と異なり、ビルド成果物を直接生成できません。実際のビルド時は windows-x64 に切り替えてください
- clangd は clang-cl のコンパイル情報で解析するため、一部コード（MSVC 専用拡張など）でエラー表示が出る場合がありますが、無視して問題ありません。実際の MSVC ビルドには影響しません
コマンドラインでのプリセット切り替え例（プロジェクトルートで実行）：
```
rem compile_commands.json を生成（Configure のみ、ビルドなし）
cmake --preset windows-x64-clang

rem MSVC に戻して実際のビルドを行う
cmake --preset windows-x64
cmake --build --preset windows-x64-RelWithDebInfo
```
デバッグ：.vscode/launch.json は自分で作成する必要があります。設定すると MaaWpfGui や Debug Demo を起動してデバッグできます

ビルドとデバッグのショートカット

ビルド：Ctrl+Shift+B または CMake Tools ステータスバー
デバッグ：F5 または Run and Debug パネルで設定を選択

MAAのファイルフォーマット要件

MAAは、リポジトリ内のコードとリソースファイルが美しく統一されるよう、一連のフォーマットツールを使用してメンテナンスと読み取りを容易にしています。

提出する前にフォーマットするか、またはPre-commit Hooksを使用してコードを自動フォーマットしてください。

現在有効になっているフォーマットツールは次のとおりです：

ファイルタイプ	フォーマットツール
C++	clang-format
JSON/YAML	Prettier
Markdown	markdownlint
Python	ruff-format
PNG	oxipng

Pre-commit Hooksを使用してコードを自動フォーマット

コンピュータにPython環境とNode環境があることを確認してください。
プロジェクトのルートディレクトリで次のコマンドを実行します：
```
pip install pre-commit
pre-commit install
```

pipインストール後もPre-commitを実行できない場合は、PIPインストールパスがPATHに追加されていることを確認してください。

次に、提出するたびにフォーマットツールが自動的に実行され、コード形式がスタイルガイドに準拠していることを確認します。

Visual Studioでclang-formatを有効にする

clang-format バージョン20.1.0以上をインストールします。
```
python -m pip install clang-format
```
'Everything'などのツールを使用して、clang-format.exeのインストール場所を見つけます。参考までに、Anacondaを使用している場合、clang-format.exeはYourAnacondaPath/Scripts/clang-format.exeにインストールされます。
Visual Studioで、 Tools-Optionsで 'clang-format'を検索します。
clang-formatサポートを有効にする をクリックし、下の カスタムのclang-format.exeファイルを使用する を選択し、最初取得した 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

を実行するだけです。