ContextQMD
Back to Maaassistantarknights

Development Guide

docs/en-us/develop/development.md

6.9.211.0 KB
Original Source

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 :::

::: tip You can Ask DeepWiki 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 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 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)

  • Lightweight environment, suitable for documentation site frontend development

  • Full environment, suitable for MAA Core related development (not recommended, suggest local development with full environment setup. See next section)

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, 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-v2 --single-branch

    ::: tip --single-branch only fetches the history for dev-v2. If you later want to switch to another branch, run git remote set-branches origin '*' and fetch again so Git can download the missing branch data, or re-clone the repository without --single-branch. :::

    ::: 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
    cmake --preset windows-x64

  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 run Win32Controller (Windows window control) / MaaFwAdbController (MaaFramework touch mode) features, you need to manually download the package for your platform from MaaFramework Releases, and place MaaWin32ControlUnit.dll / MaaAdbControlUnit.dll from the bin directory into MAA's DLL directory (e.g. build/bin/Debug). PRs for an auto-download script are welcome!

    To debug these features, compile the Debug version of MaaFramework yourself and use the corresponding DLLs, or it will randomly crash at breakpoints. :::

  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-v2:

    bash
    git branch your_own_branch
git checkout your_own_branch

    This keeps your changes isolated from upstream dev-v2 updates.

  11. After development, push your local branch (e.g. dev-v2) to your remote repository:

    bash
    git push origin dev-v2

  12. Submit a Pull Request at the MAA main repository. Ensure your changes are based on the dev-v2 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-v2 # 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. :::

Using VS Code for Development (Optional)

::: warning Visual Studio is the recommended IDE for development. The MAA project is primarily built around Visual Studio, and the complete environment setup described above covers all development needs with the best out-of-the-box experience. The VS Code workflow is provided only as an alternative for developers already familiar with VS Code + CMake + clangd, and requires more configuration effort. :::

If you prefer VS Code, you can use CMake, clangd, and related extensions for code completion, navigation, and debugging. After completing steps 1–6 above (clone, dependencies, CMake configuration), follow these steps:

Install from the VS Code marketplace:

ExtensionPurpose
CMake ToolsCMake configure, build, and debug integration
clangdC++ IntelliSense, code navigation, diagnostics (LSP-based)
C/C++Debug C++ programs (works with CMake Tools or launch.json)

::: tip When using clangd, set C_Cpp.intelliSenseEngine to disabled to avoid conflicts with the C/C++ extension's IntelliSense. :::

Setup Steps

  1. Open the project root folder in VS Code

  2. CMake Tools:

    • Select a Configure Preset from the status bar (e.g. windows-x64, linux-x64)
    • Select a Build Preset and run configure/build

  3. clangd: On Linux/macOS, presets enable CMAKE_EXPORT_COMPILE_COMMANDS and clangd uses build/compile_commands.json automatically. On Windows, clangd's code completion and navigation requires generating compile_commands.json first:

    ::: warning clangd Setup on Windows

    • In VS Installer, check C++ Clang compiler for Windows (clang-cl)
    • Switch to the windows-x64-clang preset and run Configure once to generate compile_commands.json in build/, then clangd will work
    • This preset uses clang-cl instead of MSVC and cannot produce valid build artifacts; switch back to windows-x64 for actual builds
    • clangd analyzes based on clang-cl; some code (e.g. MSVC-specific extensions) may show errors. These can be ignored and do not affect MSVC compilation

    Command-line preset switching example (run from project root):

    cmd
    rem Generate compile_commands.json (Configure only, no build)
cmake --preset windows-x64-clang

rem Switch back to MSVC for actual build
cmake --preset windows-x64
cmake --build --preset windows-x64-RelWithDebInfo

    :::

  4. Debugging: The project includes .vscode/launch.json for launching MaaWpfGui or Debug Demo

Build and Debug Shortcuts

  • Build: Ctrl+Shift+B or via CMake Tools status bar
  • Debug: F5 or choose a configuration from the Run and Debug panel

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.

The currently enabled formatting tools are as follows:

File TypeFormat Tool
C++clang-format
JSON/YAMLPrettier
Markdownmarkdownlint

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