build: Adopt CMake presets for CI and add clangd/VSCode integration (#15595)

* feat: clangd support

* feat: 完善CMakePresets

* docs: 更新cmake命令

* fix: smoke test run

* docs: 更新vscode开发文档

* feat: 添加执行MaaWpf到cmake中

* feat: 支持全部的presets

* chore: 重新安排顺序

* chore: add some comment

* chore: add more comments

* feat: 简化res-update-game

* chore: 移除多余build

* chore: 统一x64和arm64

* chore: 修正重复忽略.vscode

* feat: vscode cmaketool乱码

* docs: 添加提示

.clangd

@@ -0,0 +1,2 @@
+CompileFlags:
+  CompilationDatabase: build

.github/workflows/ci.yml

@@ -11,6 +11,7 @@ on:
       - "3rdparty/include/**"
       - "cmake/**"
       - "CMakeLists.txt"
+      - "CMakePresets.json"
       - "include/**"
       - "src/**"
       - "tools/maadeps-download.py"
@@ -23,6 +24,7 @@ on:
       - "3rdparty/include/**"
       - "cmake/**"
       - "CMakeLists.txt"
+      - "CMakePresets.json"
       - "include/**"
       - "src/**"
       - "tools/maadeps-download.py"
@@ -130,20 +132,12 @@ jobs:
         run: |
           python3 tools/maadeps-download.py ${{ matrix.arch }}-windows
 
-      - name: Config cmake
+      - name: Configure, build and install
         run: |
-          mkdir -p build
+          cmake -B build --preset ${{ matrix.arch == 'arm64' && 'windows-publish-arm64' || 'windows-publish-x64' }} -DMAA_HASH_VERSION='${{ needs.meta.outputs.tag }}'
-          cmake -B build ${{ matrix.arch == 'arm64' && '-A ARM64' }} -DCMAKE_BUILD_TYPE=RelWithDebInfo -DMAADEPS_TRIPLET='maa-${{ matrix.arch }}-windows' -DINSTALL_RESOURCE=ON -DINSTALL_PYTHON=ON -DMAA_HASH_VERSION='${{ needs.meta.outputs.tag }}' -DBUILD_WPF_GUI=OFF
+          cmake --build --preset ${{ matrix.arch == 'arm64' && 'windows-publish-arm64' || 'windows-publish-x64' }} --parallel $env:NUMBER_OF_PROCESSORS
-
+          cmake --install build --config RelWithDebInfo
-      - name: Build
+      
-        run: |
-          cmake --build build --config RelWithDebInfo --parallel $env:NUMBER_OF_PROCESSORS
-
-      - name: Install
-        run: |
-          mkdir -p install
-          cmake --install build --prefix install --config RelWithDebInfo
-
       - name: Minify JSON in resource
         run: python3 tools/minify_json_folder.py install/resource
 
@@ -267,28 +261,14 @@ jobs:
         run: |
           python3 tools/maadeps-download.py ${{ matrix.arch == 'x86_64' && 'x64' || 'arm64' }}-linux
 
-      - name: Config cmake
+      - name: Configure, build and install
         run: |
-          mkdir -p build
+          cmake --preset ${{ matrix.arch == 'x86_64' && 'linux-publish-x64' || 'linux-publish-arm64' }} -DMAA_HASH_VERSION='${{ needs.meta.outputs.tag }}'
-          cmake -B build \
+          cmake --build --preset ${{ matrix.arch == 'x86_64' && 'linux-publish-x64' || 'linux-publish-arm64' }} --parallel $(nproc)
-            -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+          cmake --install build --config RelWithDebInfo
-            -DMAADEPS_TRIPLET='maa-${{ matrix.arch == 'x86_64' && 'x64' || 'arm64' }}-linux' \
-            -DINSTALL_RESOURCE=ON \
-            -DINSTALL_PYTHON=ON \
-            -DMAA_HASH_VERSION='${{ needs.meta.outputs.tag }}' \
-            -DCMAKE_TOOLCHAIN_FILE=src/MaaUtils/MaaDeps/cmake/maa-${{ matrix.arch == 'x86_64' && 'x64' || 'arm64' }}-linux-toolchain.cmake
-
-      - name: Build
-        run: |
-          cmake --build build --config RelWithDebInfo --parallel $(nproc)
         env:
           CLICOLOR_FORCE: 1
 
-      - name: Install
-        run: |
-          mkdir -p install
-          cmake --install build --prefix install --config RelWithDebInfo
-
       - name: Minify JSON in resource
         run: python3 tools/minify_json_folder.py install/resource
 
@@ -393,20 +373,11 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Config cmake
+      - name: Configure, build and install
         run: |
-          cmake -B build -GNinja \
+          cmake -B build --preset ${{ matrix.arch == 'x86_64' && 'macos-publish-x64' || 'macos-publish-arm64' }} -DMAA_HASH_VERSION='${{ needs.meta.outputs.tag }}'
-            -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+          cmake --build --preset ${{ matrix.arch == 'x86_64' && 'macos-publish-x64' || 'macos-publish-arm64' }} --parallel $(sysctl -n hw.logicalcpu)
-            -DCMAKE_OSX_ARCHITECTURES='${{ matrix.arch }}' \
+          cmake --install build --config RelWithDebInfo
-            -DMAA_HASH_VERSION='${{ needs.meta.outputs.tag }}'
-
-      - name: Build
-        run: |
-          cmake --build build --config RelWithDebInfo --parallel $(sysctl -n hw.logicalcpu)
-
-      - name: Install
-        run: |
-          cmake --install build --prefix install --config RelWithDebInfo
 
       - name: Upload MAA to GitHub
         uses: actions/upload-artifact@v6

.github/workflows/release-nightly-ota.yml

@@ -185,19 +185,11 @@ jobs:
         run: |
           python3 tools/maadeps-download.py ${{ matrix.arch }}-windows
 
-      - name: Config cmake
+      - name: Configure, build and install
         run: |
-          mkdir -p build
+          cmake -B build --preset ${{ matrix.arch == 'arm64' && 'windows-publish-arm64' || 'windows-publish-x64' }} -DMAA_HASH_VERSION='${{ steps.set_tag.outputs.tag }}'
-          cmake -B build ${{ matrix.arch == 'arm64' && '-A ARM64' }} -DCMAKE_BUILD_TYPE=RelWithDebInfo -DMAADEPS_TRIPLET='maa-${{ matrix.arch }}-windows' -DINSTALL_RESOURCE=ON -DINSTALL_PYTHON=ON -DMAA_HASH_VERSION='${{ steps.set_tag.outputs.tag }}' -DBUILD_WPF_GUI=OFF
+          cmake --build --preset ${{ matrix.arch == 'arm64' && 'windows-publish-arm64' || 'windows-publish-x64' }} --parallel $env:NUMBER_OF_PROCESSORS
-
+          cmake --install build --config RelWithDebInfo
-      - name: Build
-        run: |
-          cmake --build build --config RelWithDebInfo --parallel $env:NUMBER_OF_PROCESSORS
-
-      - name: Install
-        run: |
-          mkdir -p install
-          cmake --install build --prefix install --config RelWithDebInfo
 
       - name: Download MaaFramework
         if: matrix.arch == 'x64'

.github/workflows/res-update-game.yml

@@ -184,25 +184,13 @@ jobs:
         run: |
           python3 tools/maadeps-download.py arm64-osx
 
-      - name: Config cmake
+      - name: Config, Build & Install ResourceUpdater
         if: steps.resupd-cache.outputs.cache-hit != 'true'
         run: |
           cd tools/ResourceUpdater
-          mkdir -p build
+          cmake --preset res-updater-macos-arm64
-          cmake -B build -GNinja \
+          cmake --build --preset res-updater-macos-arm64 --parallel $(sysctl -n hw.logicalcpu)
-            -DCMAKE_BUILD_TYPE=Release \
+          cmake --install build --config Release
-            -DMAADEPS_TRIPLET='maa-arm64-osx' \
-            -DWITH_HASH_VERSION=ON
-
-      - name: Build
-        if: steps.resupd-cache.outputs.cache-hit != 'true'
-        run: |
-          cmake --build tools/ResourceUpdater/build --config Release --parallel $(sysctl -n hw.logicalcpu)
-
-      - name: Install
-        if: steps.resupd-cache.outputs.cache-hit != 'true'
-        run: |
-          cmake --install tools/ResourceUpdater/build --prefix tools/ResourceUpdater --config Release
 
       - name: Save ResourceUpdater to cache
         if: always() && steps.resupd-cache.outputs.cache-hit != 'true'

.github/workflows/smoke-testing.yml

@@ -87,27 +87,12 @@ jobs:
         run: |
           python3 tools/maadeps-download.py arm64-osx
 
-      - name: Config cmake
+      - name: Configure, build and install
         if: steps.smoke-cache.outputs.cache-hit != 'true'
         run: |
-          mkdir -p build
+          cmake -B build --preset smoke-test
-          cmake -B build -GNinja \
+          cmake --build build --preset smoke-test --parallel $(sysctl -n hw.logicalcpu)
-            -DCMAKE_BUILD_TYPE=Debug \
+          cmake --install build --config Debug
-            -DMAADEPS_TRIPLET='maa-arm64-osx' \
-            -DBUILD_SMOKE_TEST=ON \
-            -DINSTALL_RESOURCE=ON \
-            -DWITH_HASH_VERSION=ON
-
-      - name: Build
-        if: steps.smoke-cache.outputs.cache-hit != 'true'
-        run: |
-          cmake --build build --config Debug --parallel $(sysctl -n hw.logicalcpu)
-
-      - name: Install
-        if: steps.smoke-cache.outputs.cache-hit != 'true'
-        run: |
-          mkdir -p install
-          cmake --install build --prefix install --config Debug
 
       - name: Make link to Smoke Test cache
         if: steps.smoke-cache.outputs.cache-hit == 'true'

.gitignore

@@ -411,10 +411,10 @@ FodyWeavers.xsd
 # VS Code files for those working on multiple tools
 **/.vscode/*
 .vscode/*
-!.vscode/settings.json
+# !.vscode/settings.json
-!.vscode/tasks.json
+# !.vscode/tasks.json
-!.vscode/launch.json
+# !.vscode/launch.json
-!.vscode/extensions.json
+# !.vscode/extensions.json
 *.code-workspace
 
 # Local History for Visual Studio Code
@@ -434,7 +434,6 @@ FodyWeavers.xsd
 screen.png
 adb_screen.png
 tools/**/*.png
-.vscode
 enc_temp_folder/*
 
 # RoguelikeRecruitmentTool 导出的 Excel 文件
@@ -481,4 +480,4 @@ install
 .pnpm-store
 
 # CMake user presets
-CMakeUserPresets.json
+CMakeUserPresets.json

.vscode/settings.json

@@ -15,5 +15,6 @@
     "files.associations": {
         "**/resource/tasks/**/*.json": "jsonc"
     },
-    "C_Cpp.exclusionPolicy": "checkFilesAndFolders"
+    "C_Cpp.exclusionPolicy": "checkFilesAndFolders",
+    "cmake.outputLogEncoding": "UTF-8"
 }

CMakeLists.txt

@@ -35,6 +35,11 @@ if(BUILD_WPF_GUI)
     include_external_msproject(MaaWpfGui ${PROJECT_SOURCE_DIR}/src/MaaWpfGui/MaaWpfGui.csproj)
 
     add_dependencies(MaaWpfGui MaaCore)
+    add_custom_target(run-MaaWpfGui
+        COMMAND "${CMAKE_BINARY_DIR}/bin/$<CONFIG>/MAA.exe"
+        DEPENDS MaaWpfGui
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/bin/$<CONFIG>"
+    )
 endif()
 
 if(INSTALL_PYTHON)

CMakePresets.json

@@ -1,19 +1,25 @@
 {
-    "version": 3,
+    "version": 10,
     "cmakeMinimumRequired": {
-        "major": 4,
+        "major": 3,
-        "minor": 2,
+        "minor": 23,
         "patch": 0
     },
     "configurePresets": [
         {
-            "name": "windows",
+            "name": "windows-base",
-            "displayName": "Windows (Visual Studio 18 2026)",
+            "hidden": true,
             "generator": "Visual Studio 18 2026",
             "binaryDir": "${sourceDir}/build",
+            "$comment": [
+                "Base for Windows presets; Visual Studio is multi-config (Debug/Release/RelWithDebInfo in same build dir)",
+                "see https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2018%202026.html"
+            ],
             "cacheVariables": {
                 "BUILD_WPF_GUI": "ON",
-                "BUILD_DEBUG_DEMO": "ON"
+                "BUILD_DEBUG_DEMO": "ON",
+                "INSTALL_RESOURCE": "OFF",
+                "INSTALL_PYTHON": "OFF"
             },
             "condition": {
                 "type": "equals",
@@ -22,19 +28,321 @@
             }
         },
         {
-            "name": "linux",
+            "name": "linux-base",
-            "displayName": "Linux x64 (Unix Makefiles)",
+            "hidden": true,
-            "generator": "Unix Makefiles",
+            "generator": "Ninja Multi-Config",
             "binaryDir": "${sourceDir}/build",
+            "$comment": [
+                "Base for Linux presets; Ninja is multi-config (Debug/Release/RelWithDebInfo in same build dir)",
+                "see https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html",
+                "clangd uses compile_commands.json to provide code completion and navigation",
+                "so CMAKE_EXPORT_COMPILE_COMMANDS is set to ON",
+                "see https://clangd.llvm.org/installation.html"
+            ],
             "cacheVariables": {
-                "BUILD_DEBUG_DEMO": "ON",
+                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
-                "CMAKE_TOOLCHAIN_FILE": "src/MaaUtils/MaaDeps/cmake/maa-x64-linux-toolchain.cmake"
             },
             "condition": {
                 "type": "equals",
                 "lhs": "${hostSystemName}",
                 "rhs": "Linux"
             }
+        },
+        {
+            "name": "macos-base",
+            "hidden": true,
+            "generator": "Ninja Multi-Config",
+            "binaryDir": "${sourceDir}/build",
+            "$comment": [
+                "Base for macOS presets; Ninja is multi-config (Debug/Release/RelWithDebInfo in same build dir)",
+                "see https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html",
+                "clangd uses compile_commands.json to provide code completion and navigation",
+                "so CMAKE_EXPORT_COMPILE_COMMANDS is set to ON",
+                "see https://clangd.llvm.org/installation.html"
+            ],
+            "cacheVariables": {
+                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+            },
+            "condition": {
+                "type": "equals",
+                "lhs": "${hostSystemName}",
+                "rhs": "Darwin"
+            }
+        },
+        {
+            "name": "windows-x64",
+            "inherits": "windows-base",
+            "displayName": "Windows x64",
+            "architecture": "x64",
+            "cacheVariables": {
+                "MAADEPS_TRIPLET": "maa-x64-windows"
+            }
+        },
+        {
+            "name": "windows-arm64",
+            "inherits": "windows-base",
+            "displayName": "Windows arm64",
+            "architecture": "ARM64",
+            "cacheVariables": {
+                "MAADEPS_TRIPLET": "maa-arm64-windows"
+            }
+        },
+        {
+            "name": "linux-x64",
+            "inherits": "linux-base",
+            "displayName": "Linux x64",
+            "toolchainFile": "src/MaaUtils/MaaDeps/cmake/maa-x64-linux-toolchain.cmake",
+            "cacheVariables": {
+                "MAADEPS_TRIPLET": "maa-x64-linux"
+            }
+        },
+        {
+            "name": "linux-arm64",
+            "inherits": "linux-base",
+            "displayName": "Linux arm64",
+            "toolchainFile": "src/MaaUtils/MaaDeps/cmake/maa-arm64-linux-toolchain.cmake",
+            "cacheVariables": {
+                "MAADEPS_TRIPLET": "maa-arm64-linux"
+            }
+        },
+        {
+            "name": "macos-arm64",
+            "inherits": "macos-base",
+            "displayName": "macOS arm64",
+            "cacheVariables": {
+                "CMAKE_OSX_ARCHITECTURES": "arm64"
+            }
+        },
+        {
+            "name": "macos-x64",
+            "inherits": "macos-base",
+            "displayName": "macOS x64",
+            "cacheVariables": {
+                "CMAKE_OSX_ARCHITECTURES": "x86_64"
+            }
+        },
+        {
+            "name": "publish-base",
+            "$comment":[
+                "All the name contains 'publish' are used for github actions",
+                "see .github/workflows/ci.yml"
+            ],
+            "hidden": true,
+            "installDir": "install",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+                "INSTALL_RESOURCE": "ON",
+                "INSTALL_PYTHON": "ON",
+                "BUILD_WPF_GUI": "OFF",
+                "BUILD_DEBUG_DEMO": "OFF"
+            }
+        },
+        {
+            "name": "windows-publish-x64",
+            "inherits": ["publish-base", "windows-x64"],
+            "$comment": [
+                "github actions only support Visual Studio 17 2022",
+                "see https://github.com/actions/runner-images/issues/13291"
+            ],
+            "generator": "Visual Studio 17 2022",
+            "displayName": "Windows x64 Publish"
+        },
+        {
+            "name": "windows-publish-arm64",
+            "inherits": ["publish-base", "windows-arm64"],
+            "$comment": [
+                "github actions only support Visual Studio 17 2022",
+                "see https://github.com/actions/runner-images/issues/13291"
+            ],
+            "generator": "Visual Studio 17 2022",
+            "displayName": "Windows arm64 Publish"
+        },
+        {
+            "name": "linux-publish-x64",
+            "inherits": ["publish-base", "linux-x64"],
+            "displayName": "Linux x64 Publish"
+        },
+        {
+            "name": "linux-publish-arm64",
+            "inherits": ["publish-base", "linux-arm64"],
+            "displayName": "Linux arm64 Publish"
+        },
+        {
+            "name": "macos-publish-x64",
+            "inherits": ["publish-base", "macos-x64"],
+            "displayName": "macOS x64 Publish"
+        },
+        {
+            "name": "macos-publish-arm64",
+            "inherits": ["publish-base", "macos-arm64"],
+            "displayName": "macOS arm64 Publish"
+        },
+        {
+            "name": "smoke-test",
+            "$comment":[
+                "this preset is used for smoke testing",
+                "see .github/workflows/smoke-testing.yml"
+            ],
+            "inherits": "macos-arm64",
+            "displayName": "macOS arm64 Smoke Test",
+            "installDir": "install",
+            "cacheVariables": {
+                "BUILD_SMOKE_TEST": "ON",
+                "INSTALL_RESOURCE": "ON",
+                "WITH_HASH_VERSION": "ON"
+            }
+        }
+    ],
+    "buildPresets": [
+        {
+            "name": "windows-x64-Debug",
+            "displayName": "Build Windows x64 Debug",
+            "configurePreset": "windows-x64",
+            "configuration": "Debug"
+        },
+        {
+            "name": "windows-x64-Release",
+            "displayName": "Build Windows x64 Release",
+            "configurePreset": "windows-x64",
+            "configuration": "Release"
+        },
+        {
+            "name": "windows-x64-RelWithDebInfo",
+            "displayName": "Build Windows x64 RelWithDebInfo",
+            "configurePreset": "windows-x64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "windows-arm64-Debug",
+            "displayName": "Build Windows arm64 Debug",
+            "configurePreset": "windows-arm64",
+            "configuration": "Debug"
+        },
+        {
+            "name": "windows-arm64-Release",
+            "displayName": "Build Windows arm64 Release",
+            "configurePreset": "windows-arm64",
+            "configuration": "Release"
+        },
+        {
+            "name": "windows-arm64-RelWithDebInfo",
+            "displayName": "Build Windows arm64 RelWithDebInfo",
+            "configurePreset": "windows-arm64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "linux-x64-Debug",
+            "displayName": "Build Linux x64 Debug",
+            "configurePreset": "linux-x64",
+            "configuration": "Debug"
+        },
+        {
+            "name": "linux-x64-Release",
+            "displayName": "Build Linux x64 Release",
+            "configurePreset": "linux-x64",
+            "configuration": "Release"
+        },
+        {
+            "name": "linux-x64-RelWithDebInfo",
+            "displayName": "Build Linux x64 RelWithDebInfo",
+            "configurePreset": "linux-x64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "linux-arm64-Debug",
+            "displayName": "Build Linux arm64 Debug",
+            "configurePreset": "linux-arm64",
+            "configuration": "Debug"
+        },
+        {
+            "name": "linux-arm64-Release",
+            "displayName": "Build Linux arm64 Release",
+            "configurePreset": "linux-arm64",
+            "configuration": "Release"
+        },
+        {
+            "name": "linux-arm64-RelWithDebInfo",
+            "displayName": "Build Linux arm64 RelWithDebInfo",
+            "configurePreset": "linux-arm64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "macos-x64-Debug",
+            "displayName": "Build macOS x64 Debug",
+            "configurePreset": "macos-x64",
+            "configuration": "Debug"
+        },
+        {
+            "name": "macos-x64-Release",
+            "displayName": "Build macOS x64 Release",
+            "configurePreset": "macos-x64",
+            "configuration": "Release"
+        },
+        {
+            "name": "macos-x64-RelWithDebInfo",
+            "displayName": "Build macOS x64 RelWithDebInfo",
+            "configurePreset": "macos-x64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "macos-arm64-Debug",
+            "displayName": "Build macOS arm64 Debug",
+            "configurePreset": "macos-arm64",
+            "configuration": "Debug"
+        },
+        {
+            "name": "macos-arm64-Release",
+            "displayName": "Build macOS arm64 Release",
+            "configurePreset": "macos-arm64",
+            "configuration": "Release"
+        },
+        {
+            "name": "macos-arm64-RelWithDebInfo",
+            "displayName": "Build macOS arm64 RelWithDebInfo",
+            "configurePreset": "macos-arm64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "windows-publish-x64",
+            "displayName": "Build Windows x64 Publish",
+            "configurePreset": "windows-publish-x64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "windows-publish-arm64",
+            "displayName": "Build Windows arm64 Publish",
+            "configurePreset": "windows-publish-arm64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "linux-publish-x64",
+            "displayName": "Build Linux x64 Publish",
+            "configurePreset": "linux-publish-x64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "linux-publish-arm64",
+            "displayName": "Build Linux arm64 Publish",
+            "configurePreset": "linux-publish-arm64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "macos-publish-x64",
+            "displayName": "Build macOS x64 Publish",
+            "configurePreset": "macos-publish-x64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "macos-publish-arm64",
+            "displayName": "Build macOS arm64 Publish",
+            "configurePreset": "macos-publish-arm64",
+            "configuration": "RelWithDebInfo"
+        },
+        {
+            "name": "smoke-test",
+            "displayName": "Build macOS arm64 Smoke Test",
+            "configurePreset": "smoke-test",
+            "configuration": "Debug"
         }
     ]
 }

docs/en-us/develop/development.md

@@ -64,8 +64,7 @@ We've preset several different development environments for you to choose from:
 6. Execute cmake project configuration
 
    ```cmd
-   mkdir -p build
+   cmake --preset windows-x64
-   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.
@@ -127,6 +126,42 @@ We've preset several different development environments for you to choose from:
 After opening Visual Studio, Git operations can be performed using VS's built-in "Git Changes" instead of command-line tools.
 :::
 
+## Using VSCode 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 VSCode workflow is provided only as an alternative for developers already familiar with VSCode + CMake + clangd, and requires more configuration effort.
+:::
+
+If you prefer VSCode, 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:
+
+### Recommended Extensions
+
+Install from the VSCode marketplace:
+
+| Extension                                                                                           | Purpose                                                    |
+| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)            | CMake configure, build, and debug integration              |
+| [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) | C++ IntelliSense, code navigation, diagnostics (LSP-based) |
+| [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)                     | 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 VSCode
+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**: Works on Windows with MSVC without needing `compile_commands.json`. On Linux/macOS, presets enable `CMAKE_EXPORT_COMPILE_COMMANDS` and clangd uses `build/compile_commands.json` automatically
+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.

docs/ja-jp/develop/development.md

@@ -70,8 +70,7 @@ icon: iconoir:developer
 6. cmake プロジェクト設定を実行
 
    ```cmd
-   mkdir -p build
+   cmake --preset windows-x64
-   cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON
    ```
 
 7. `build/MAA.slnx` をダブルクリックで開き、Visual Studio にプロジェクトを自動ロード
@@ -133,6 +132,40 @@ icon: iconoir:developer
 Visual Studio 起動後、Git 操作は「Git 変更」画面からコマンドライン不要で可能
 :::
 
+## VSCodeでの開発（オプション）
+
+::: warning
+**Visual Studio での開発を推奨します。** MAA プロジェクトは主に Visual Studio をベースに構築されており、上記の完全な環境セットアップですべての開発ニーズをカバーし、すぐに使える最高の体験を提供します。VSCode ワークフローは、VSCode + CMake + clangd に精通した開発者向けの代替手段としてのみ提供されており、設定のハードルが比較的高くなります。
+:::
+
+VSCodeを好む場合、CMake、clangdなどの拡張機能でコード補完、ナビゲーション、デバッグが可能です。前述の手順1～6（クローン、依存関係、CMake設定）を完了した後、以下の手順で設定できます。
+
+### 推奨拡張機能
+
+VSCode Marketplace からインストール：
+
+| 拡張機能                                                                                            | 用途                                                              |
+| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)            | CMake の設定、ビルド、デバッグ統合                                |
+| [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) | C++ インテリセンス、コードナビゲーション、診断（LSPベース）       |
+| [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)                     | C++ プログラムのデバッグ（CMake Tools または launch.json と連携） |
+
+::: tip
+clangd を使用する場合、C/C++ 拡張機能の IntelliSense を無効化（`C_Cpp.intelliSenseEngine` を `disabled` に設定）することを推奨します。競合を避けるためです。
+:::
+
+### 設定手順
+
+1. VSCode でプロジェクトルートを開く
+2. **CMake Tools**：ステータスバーで Configure Preset（例：`windows-x64`、`linux-x64`）を選択し、Build Preset でビルドを実行
+3. **clangd**：Windows で MSVC を使用する場合、`compile_commands.json` がなくても clangd で開発可能。Linux/macOS ではプリセットで `CMAKE_EXPORT_COMPILE_COMMANDS` が有効となり、clangd は `build/compile_commands.json` を自動使用
+4. **デバッグ**：プロジェクトには `.vscode/launch.json` が含まれており、MaaWpfGui や Debug Demo の起動が可能
+
+### ビルドとデバッグのショートカット
+
+- **ビルド**：`Ctrl+Shift+B` または CMake Tools ステータスバー
+- **デバッグ**：F5 または Run and Debug パネルで設定を選択
+
 ## MAAのファイルフォーマット要件
 
 MAAは、リポジトリ内のコードとリソースファイルが美しく統一されるよう、一連のフォーマットツールを使用してメンテナンスと読み取りを容易にしています。

docs/ko-kr/develop/development.md

@@ -69,8 +69,7 @@ icon: iconoir:developer
 6. cmake 프로젝트 구성 실행
 
    ```cmd
-   mkdir -p build
+   cmake --preset windows-x64
-   cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON
    ```
 
 7. `build/MAA.slnx` 파일을 더블 클릭하여 엽니다. Visual Studio가 자동으로 전체 프로젝트를 로드합니다.
@@ -132,6 +131,40 @@ icon: iconoir:developer
 Visual Studio 실행 시 Git 작업은 "Git 변경" 탭에서 명령어 없이 처리 가능
 :::
 
+## VSCode로 개발하기 (선택 사항)
+
+::: warning
+**Visual Studio를 사용한 개발을 권장합니다.** MAA 프로젝트는 주로 Visual Studio를 기반으로 구축되며, 위의 완전한 환경 설정 과정이 모든 개발 요구를 충족하여 최상의 즉시 사용 가능한 경험을 제공합니다. VSCode 워크플로는 VSCode + CMake + clangd에 이미 익숙한 개발자를 위한 대안으로만 제공되며, 설정 난이도가 상대적으로 높습니다.
+:::
+
+VSCode를 선호한다면 CMake, clangd 등의 확장을 사용해 코드 완성, 탐색, 디버깅을 할 수 있습니다. 위 1–6단계(클론, 의존성, CMake 설정)를 완료한 후 다음 단계로 설정하세요.
+
+### 추천 확장
+
+VSCode Marketplace에서 설치:
+
+| 확장                                                                                                | 용도                                                      |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)            | CMake 설정, 빌드, 디버깅 통합                             |
+| [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) | C++ IntelliSense, 코드 탐색, 진단 (LSP 기반)              |
+| [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)                     | C++ 프로그램 디버깅 (CMake Tools 또는 launch.json과 연동) |
+
+::: tip
+clangd 사용 시 C/C++ 확장의 IntelliSense를 비활성화(`C_Cpp.intelliSenseEngine`을 `disabled`로 설정)하는 것을 권장합니다. 충돌을 피하기 위함입니다.
+:::
+
+### 설정 단계
+
+1. VSCode에서 프로젝트 루트 열기
+2. **CMake Tools**: 상태 표시줄에서 Configure Preset(예: `windows-x64`, `linux-x64`) 선택 후 Build Preset으로 빌드 실행
+3. **clangd**: Windows에서 MSVC 사용 시 `compile_commands.json` 없이도 clangd로 개발 가능. Linux/macOS에서는 프리셋에서 `CMAKE_EXPORT_COMPILE_COMMANDS`가 활성화되어 clangd가 `build/compile_commands.json`을 자동 사용
+4. **디버깅**: 프로젝트에 `.vscode/launch.json`이 포함되어 MaaWpfGui 또는 Debug Demo를 바로 실행 가능
+
+### 빌드 및 디버깅 단축키
+
+- **빌드**: `Ctrl+Shift+B` 또는 CMake Tools 상태 표시줄
+- **디버깅**: F5 또는 Run and Debug 패널에서 구성 선택
+
 ## MAA 파일의 포매팅 요구 사항
 
 MAA는 리포지토리의 코드 및 리소스 파일들을 아름답고 일관적으로 유지하기 위해 일련의 포매팅 도구를 사용합니다.

docs/zh-cn/develop/development.md

@@ -64,8 +64,7 @@ icon: iconoir:developer
 6. 执行 cmake 项目配置
 
    ```cmd
-   mkdir -p build
+   cmake --preset windows-x64
-   cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON
    ```
 
 7. 双击打开 `build/MAA.slnx` 文件，Visual Studio 会自动加载整个项目。
@@ -127,6 +126,42 @@ icon: iconoir:developer
 在打开 VS 之后，和 Git 有关的操作可以不用命令行工具，直接使用 VS 自带的“Git 更改”即可
 :::
 
+## 使用 VSCode 进行开发（可选）
+
+::: warning
+**推荐优先使用 Visual Studio 进行开发。** MAA 项目主要基于 Visual Studio 构建，上述完整环境配置流程已涵盖所有开发需求，开箱即用体验最佳。VSCode 方案仅作为备选，适合已经熟悉 VSCode + CMake + clangd 工作流的开发者，配置门槛相对较高。
+:::
+
+如果你偏好使用 VSCode，可以配合 CMake、clangd 等扩展获得代码补全、跳转和调试能力。在完成前述 1–6 步（克隆、依赖、CMake 配置）后，可按以下步骤配置：
+
+### 推荐扩展
+
+在 VSCode 扩展市场安装：
+
+| 扩展                                                                                                | 作用                                                |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)            | CMake 配置、构建、调试集成                          |
+| [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) | C++ 智能提示、代码跳转、诊断（基于 LSP）            |
+| [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)                     | 调试 C++ 程序（与 CMake Tools 或 launch.json 配合） |
+
+::: tip
+使用 clangd 时，建议禁用 C/C++ 扩展的 IntelliSense（`C_Cpp.intelliSenseEngine` 设为 `disabled`），避免与 clangd 冲突。
+:::
+
+### 配置步骤
+
+1. 用 VSCode 打开项目根目录
+2. 使用 **CMake Tools**：
+   - 状态栏选择 Configure Preset（如 `windows-x64`、`linux-x64` 等）
+   - 选择 Build Preset，执行配置与构建
+3. 使用 **clangd**：在 Windows 上配合 MSVC 使用时无需 `compile_commands.json` 即可正常开发。Linux/macOS 下预设已开启 `CMAKE_EXPORT_COMPILE_COMMANDS`，clangd 会自动使用 `build/compile_commands.json`
+4. **调试**：项目已包含 `.vscode/launch.json`，可直接启动 MaaWpfGui 或 Debug Demo 进行调试
+
+### 快速构建与调试
+
+- **构建**：`Ctrl+Shift+B` 或通过 CMake Tools 状态栏
+- **调试**：F5 或运行与调试面板选择对应配置
+
 ## MAA 的文件格式化要求
 
 MAA 使用一系列的格式化工具来保证仓库中的代码和资源文件美观统一，以便于维护和阅读

docs/zh-tw/develop/development.md

@@ -64,8 +64,7 @@ icon: iconoir:developer
 6. 執行 CMake 專案配置
 
    ```cmd
-   mkdir -p build
+   cmake --preset windows-x64
-   cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON
    ```
 
 7. 雙擊開啟 `build/MAA.slnx` 檔案，Visual Studio 會自動載入整個專案。
@@ -128,6 +127,42 @@ icon: iconoir:developer
 開啟 Visual Studio 之後，和 Git 有關的操作可以不用命令列工具，直接使用 Visual Studio 內建的「Git 變更」功能即可。
 :::
 
+## 使用 VSCode 進行開發（可選）
+
+::: warning
+**建議優先使用 Visual Studio 進行開發。** MAA 專案主要基於 Visual Studio 建置，上述完整環境配置流程已涵蓋所有開發需求，開箱即用體驗最佳。VSCode 方案僅作為備選，適合已經熟悉 VSCode + CMake + clangd 工作流的開發者，配置門檻相對較高。
+:::
+
+如果您偏好使用 VSCode，可以搭配 CMake、clangd 等擴充套件獲得程式碼補全、跳轉與除錯能力。完成前述 1–6 步（複製、相依、CMake 設定）後，可依下列步驟設定：
+
+### 推薦擴充套件
+
+於 VSCode 擴充套件市集安裝：
+
+| 擴充套件                                                                                            | 作用                                                |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)            | CMake 設定、建置、除錯整合                          |
+| [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) | C++ 智慧提示、程式碼跳轉、診斷（基於 LSP）          |
+| [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)                     | 除錯 C++ 程式（與 CMake Tools 或 launch.json 搭配） |
+
+::: tip
+使用 clangd 時，建議停用 C/C++ 擴充套件的 IntelliSense（將 `C_Cpp.intelliSenseEngine` 設為 `disabled`），以免與 clangd 衝突。
+:::
+
+### 設定步驟
+
+1. 使用 VSCode 開啟專案根目錄
+2. **CMake Tools**：
+   - 於狀態列選擇 Configure Preset（如 `windows-x64`、`linux-x64` 等）
+   - 選擇 Build Preset，執行設定與建置
+3. **clangd**：在 Windows 上搭配 MSVC 使用時無需 `compile_commands.json` 即可正常開發。Linux/macOS 下預設已開啟 `CMAKE_EXPORT_COMPILE_COMMANDS`，clangd 會自動使用 `build/compile_commands.json`
+4. **除錯**：專案已包含 `.vscode/launch.json`，可直接啟動 MaaWpfGui 或 Debug Demo 進行除錯
+
+### 快速建置與除錯
+
+- **建置**：`Ctrl+Shift+B` 或透過 CMake Tools 狀態列
+- **除錯**：F5 或於執行與除錯面板選擇對應設定
+
 ## MAA 的檔案格式化要求
 
 MAA 使用一系列的格式化工具來確保倉庫中的程式碼和資源檔案美觀統一，以便於維護和閱讀。

tools/ResourceUpdater/CMakePresets.json

@@ -0,0 +1,25 @@
+{
+    "version": 10,
+    "cmakeMinimumRequired": { "major": 3, "minor": 28, "patch": 0 },
+    "configurePresets": [
+        {
+            "name": "res-updater-macos-arm64",
+            "displayName": "ResourceUpdater macOS arm64 Release",
+            "$comment": ["see .github/workflows/res-update-game.yml"],
+            "generator": "Ninja",
+            "binaryDir": "${sourceDir}/build",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Release",
+                "MAADEPS_TRIPLET": "maa-arm64-osx",
+                "WITH_HASH_VERSION": "ON"
+            }
+        }
+    ],
+    "buildPresets": [
+        {
+            "name": "res-updater-macos-arm64",
+            "displayName": "Build ResourceUpdater macOS arm64",
+            "configurePreset": "res-updater-macos-arm64"
+        }
+    ]
+}