bluesky013 · Copilot · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/.github/workflows/cmake.yml b/.github/workflows/cmake.yml
@@ -10,8 +10,12 @@ env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
   BUILD_TYPE: Release
 
+permissions:
+  contents: read
+
 jobs:
-  build:
+  build-legacy:
+    name: Build (legacy 3RD_PATH)
     runs-on: windows-latest
 
     steps:
@@ -42,4 +46,90 @@ jobs:
       # Execute tests defined by the CMake configuration.  
       # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
       run: ctest -C ${{env.BUILD_TYPE}}
-
+
+  build-vcpkg:
+    name: Build (vcpkg)
+    runs-on: windows-latest
+
+    env:
+      VCPKG_DEFAULT_TRIPLET: x64-windows-static
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup vcpkg
+      uses: lukka/run-vcpkg@v11
+      with:
+        vcpkgGitCommitId: 'c3867e714dd3a51c272826eea77267876517ed99'
+
+    - name: Configure CMake (vcpkg)
+      run: >
+        cmake -B ${{github.workspace}}/build
+        -DCMAKE_TOOLCHAIN_FILE=${{env.VCPKG_ROOT}}/scripts/buildsystems/vcpkg.cmake
+        -DVCPKG_TARGET_TRIPLET=x64-windows-static
+        -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+
+    - name: Build
+      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
+
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      run: ctest -C ${{env.BUILD_TYPE}}
+
+  build-vcpkg-linux:
+    name: Build (vcpkg, Linux)
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libx11-dev libxrandr-dev libxi-dev libgl1-mesa-dev
+
+    - name: Setup vcpkg
+      uses: lukka/run-vcpkg@v11
+      with:
+        vcpkgGitCommitId: 'c3867e714dd3a51c272826eea77267876517ed99'
+
+    - name: Configure CMake (vcpkg)
+      run: >
+        cmake -B ${{github.workspace}}/build
+        -DCMAKE_TOOLCHAIN_FILE=${{env.VCPKG_ROOT}}/scripts/buildsystems/vcpkg.cmake
+        -DVCPKG_TARGET_TRIPLET=x64-linux
+        -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+
+    - name: Build
+      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
+
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      run: ctest -C ${{env.BUILD_TYPE}}
+
+  build-vcpkg-macos:
+    name: Build (vcpkg, macOS)
+    runs-on: macos-14
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup vcpkg
+      uses: lukka/run-vcpkg@v11
+      with:
+        vcpkgGitCommitId: 'c3867e714dd3a51c272826eea77267876517ed99'
+
+    - name: Configure CMake (vcpkg)
+      run: >
+        cmake -B ${{github.workspace}}/build
+        -DCMAKE_TOOLCHAIN_FILE=${{env.VCPKG_ROOT}}/scripts/buildsystems/vcpkg.cmake
+        -DVCPKG_TARGET_TRIPLET=arm64-osx
+        -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+
+    - name: Build
+      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
+
+    - name: Test
+      working-directory: ${{github.workspace}}/build
+      run: ctest -C ${{env.BUILD_TYPE}}
+
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,6 @@
 # generated PDF documentation
 /docs/pdf/
 .DS_Store
+/vcpkg/
+/vcpkg_installed/
+/.thirdparty/
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,5 +1,128 @@
 cmake_minimum_required(VERSION 3.19)  # 3.19+ required for string(JSON ...)
 
+# ---------------------------------------------------------------------------
+# Third-party dependency strategy (must be configured before project()).
+#   LOCAL    : resolve deps via vcpkg (download/build to local workspace dirs)
+#   PREBUILT : resolve deps from prebuilt 3RD_PATH tree
+# ---------------------------------------------------------------------------
+set(SKY_THIRDPARTY_MODE "LOCAL" CACHE STRING "Third-party mode: LOCAL or PREBUILT")
+set_property(CACHE SKY_THIRDPARTY_MODE PROPERTY STRINGS LOCAL PREBUILT)
+option(SKY_THIRDPARTY_USE_PREBUILT "Prefer reusable prebuilt binaries from local/CI cache" ON)
+set(SKY_THIRDPARTY_ROOT "${CMAKE_SOURCE_DIR}/.thirdparty" CACHE PATH "Local third-party root for downloads/installed/cache")
+
+if (NOT SKY_THIRDPARTY_MODE STREQUAL "LOCAL" AND NOT SKY_THIRDPARTY_MODE STREQUAL "PREBUILT")
+    message(FATAL_ERROR "Invalid SKY_THIRDPARTY_MODE='${SKY_THIRDPARTY_MODE}'. Expected LOCAL or PREBUILT.")
+endif()
+
+if (SKY_THIRDPARTY_MODE STREQUAL "LOCAL")
+    # vcpkg bootstrap + manifest mode. Everything is resolved inside workspace-local dirs.
+    set(_sky_thirdparty_downloads "${SKY_THIRDPARTY_ROOT}/downloads")
+    set(_sky_thirdparty_installed "${SKY_THIRDPARTY_ROOT}/installed")
+    set(_sky_thirdparty_binary_cache "${SKY_THIRDPARTY_ROOT}/binary-cache")
+
+    file(MAKE_DIRECTORY "${SKY_THIRDPARTY_ROOT}")
+    file(MAKE_DIRECTORY "${_sky_thirdparty_downloads}")
+    file(MAKE_DIRECTORY "${_sky_thirdparty_installed}")
+    file(MAKE_DIRECTORY "${_sky_thirdparty_binary_cache}")
+
+    include(${CMAKE_SOURCE_DIR}/cmake/vcpkg_bootstrap.cmake)
+    x_vcpkg_bootstrap()
+    set(VCPKG_BOOTSTRAP_OPTIONS "-disableMetrics")
+    set(VCPKG_INSTALL_OPTIONS "--no-print-usage")
+    set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
+        CACHE STRING "Vcpkg toolchain file" FORCE)
+    list(APPEND VCPKG_FEATURE_FLAGS manifests)
+
+    set(VCPKG_DOWNLOADS "${_sky_thirdparty_downloads}" CACHE PATH "vcpkg downloads dir" FORCE)
+    set(VCPKG_INSTALLED_DIR "${_sky_thirdparty_installed}" CACHE PATH "vcpkg installed dir" FORCE)
+
+    if (SKY_THIRDPARTY_USE_PREBUILT)
+        set(VCPKG_BINARY_SOURCES "clear;files,${_sky_thirdparty_binary_cache},readwrite" CACHE STRING "vcpkg binary sources" FORCE)
+    else()
+        # Keep cache local even in source-build preference mode.
+        set(VCPKG_BINARY_SOURCES "clear;files,${_sky_thirdparty_binary_cache},readwrite" CACHE STRING "vcpkg binary sources" FORCE)
+    endif()
+
+    set(ENV{VCPKG_DEFAULT_BINARY_CACHE} "${_sky_thirdparty_binary_cache}")
+    set(SKY_USE_VCPKG ON CACHE BOOL "use vcpkg for third-party dependencies" FORCE)
+    unset(_sky_thirdparty_downloads)
+    unset(_sky_thirdparty_installed)
+    unset(_sky_thirdparty_binary_cache)
+else()
+    set(SKY_USE_VCPKG OFF CACHE BOOL "use vcpkg for third-party dependencies" FORCE)
+endif()
+
+# detect platform
+# TODO: try to adapt to more platforms
+if(WIN32)
+    set(VCPKG_TARGET_TRIPLET x64-windows)
+elseif(ANDROID)
+    set(VCPKG_TARGET_TRIPLET arm64-android)
+elseif(IOS)
+    set(VCPKG_TARGET_TRIPLET arm64-ios)
+elseif(APPLE)
+    set(VCPKG_TARGET_TRIPLET arm64-osx)
+elseif(UNIX)
+    set(VCPKG_TARGET_TRIPLET x64-linux)
+endif()
+
+# ---------------------------------------------------------------------------
+# vcpkg manifest-mode: map SKY_BUILD_* options to VCPKG_MANIFEST_FEATURES
+# so that vcpkg installs only the optional packages the user asked for.
+# These cache variables mirror the options defined later in cmake/options.cmake
+# but must be evaluated before project() because vcpkg runs at that point.
+# ---------------------------------------------------------------------------
+set(_sky_vcpkg_detected FALSE)
+if (SKY_THIRDPARTY_MODE STREQUAL "LOCAL")
+    set(_sky_vcpkg_detected TRUE)
+elseif (CMAKE_TOOLCHAIN_FILE)
+    string(FIND "${CMAKE_TOOLCHAIN_FILE}" "vcpkg" _vcpkg_idx)
+    if (NOT _vcpkg_idx EQUAL -1)
+        set(_sky_vcpkg_detected TRUE)
+    endif()
+    unset(_vcpkg_idx)
+endif()
+
+if (_sky_vcpkg_detected)
+    # Point vcpkg at our custom triplets (Android, iOS, etc.)
+    set(VCPKG_OVERLAY_TRIPLETS "${CMAKE_CURRENT_SOURCE_DIR}/triplets" CACHE STRING "" FORCE)
+
+    set(_sky_vcpkg_features "")
+
+    option(SKY_BUILD_EDITOR      "build editor"                OFF)
+    option(SKY_BUILD_BULLET      "build bullet physics plugin"  OFF)
+    option(SKY_BUILD_RECAST      "build recast navigation"      OFF)
+    option(SKY_USE_TRACY         "use tracy profiler"            OFF)
+    option(SKY_BUILD_FREETYPE    "build freetype text plugin"    OFF)
+    option(SKY_BUILD_COMPRESSION "build lz4 compression plugin"  OFF)
+
+    if (SKY_BUILD_EDITOR)
+        list(APPEND _sky_vcpkg_features "editor")
+    endif()
+    if (SKY_BUILD_BULLET)
+        list(APPEND _sky_vcpkg_features "bullet")
+    endif()
+    if (SKY_BUILD_RECAST)
+        list(APPEND _sky_vcpkg_features "recast")
+    endif()
+    if (SKY_USE_TRACY)
+        list(APPEND _sky_vcpkg_features "tracy")
+    endif()
+    if (SKY_BUILD_FREETYPE)
+        list(APPEND _sky_vcpkg_features "freetype")
+    endif()
+    if (SKY_BUILD_COMPRESSION)
+        list(APPEND _sky_vcpkg_features "compression")
+    endif()
+
+    if (_sky_vcpkg_features)
+        list(JOIN _sky_vcpkg_features ";" _sky_vcpkg_features_str)
+        set(VCPKG_MANIFEST_FEATURES "${_sky_vcpkg_features_str}" CACHE STRING "" FORCE)
+    endif()
+    unset(_sky_vcpkg_features)
+endif()
+unset(_sky_vcpkg_detected)
+
 PROJECT(SkyEngine)
 
 set(CMAKE_CXX_STANDARD 20)

diff --git a/CMakePresets.json b/CMakePresets.json
@@ -0,0 +1,49 @@
+{
+    "version": 3,
+    "cmakeMinimumRequired": {
+        "major": 3,
+        "minor": 19,
+        "patch": 0
+    },
+    "configurePresets": [
+        {
+            "name": "local-thirdparty",
+            "hidden": false,
+            "displayName": "Configure with local third-party (vcpkg)",
+            "description": "Build/download third-party packages locally under .thirdparty",
+            "generator": "Ninja",
+            "binaryDir": "${sourceDir}/build/vcpkg",
+            "cacheVariables": {
+                "SKY_THIRDPARTY_MODE": "LOCAL",
+                "SKY_THIRDPARTY_ROOT": "${sourceDir}/.thirdparty",
+                "SKY_THIRDPARTY_USE_PREBUILT": "ON"
+            }
+        },
+        {
+            "name": "prebuilt-thirdparty",
+            "hidden": false,
+            "displayName": "Configure with prebuilt third-party tree",
+            "description": "Use 3RD_PATH prebuilt packages produced by python/third_party.py",
+            "generator": "Ninja",
+            "binaryDir": "${sourceDir}/build/prebuilt",
+            "cacheVariables": {
+                "SKY_THIRDPARTY_MODE": "PREBUILT",
+                "3RD_PATH": "${sourceDir}/build_3rd/Win32"
+            }
+        }
+    ],
+    "buildPresets": [
+        {
+            "name": "local-thirdparty",
+            "configurePreset": "local-thirdparty",
+            "description": "Build using local third-party preset",
+            "configuration": "Release"
+        },
+        {
+            "name": "prebuilt-thirdparty",
+            "configurePreset": "prebuilt-thirdparty",
+            "description": "Build using prebuilt third-party preset",
+            "configuration": "Release"
+        }
+    ]
+}
diff --git a/README.md b/README.md
@@ -2,6 +2,32 @@
 
 ## Build
 
+### Third-party strategy
+
+SkyEngine supports two CMake-selectable third-party modes:
+
+1. `LOCAL` (default): build/download third-party dependencies through vcpkg in workspace-local directories.
+2. `PREBUILT`: use a prebuilt `3RD_PATH` tree produced by `python/third_party.py`.
+
+Key CMake cache options:
+
+| option                        | description                                                            |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| `SKY_THIRDPARTY_MODE`         | `LOCAL` or `PREBUILT`                                                  |
+| `SKY_THIRDPARTY_ROOT`         | local dependency root for downloads/installed/cache                    |
+| `SKY_THIRDPARTY_USE_PREBUILT` | in `LOCAL` mode, prefer reusable prebuilt binaries from local/CI cache |
+| `3RD_PATH`                    | required in `PREBUILT` mode                                            |
+
+Examples:
+
+```shell
+# LOCAL mode: build/download packages to local workspace (no system install dir)
+cmake -S . -B build -DSKY_THIRDPARTY_MODE=LOCAL -DSKY_THIRDPARTY_ROOT=.thirdparty
+
+# PREBUILT mode: use prebuilt packages
+cmake -S . -B build -DSKY_THIRDPARTY_MODE=PREBUILT -D3RD_PATH=build_3rd/Win32
+```
+
 ### Build Third-party deps
 ```cmd
 python3 python/third_party.py -p [platform]
@@ -10,14 +36,14 @@ python3 python/third_party.py -p [platform]
 * Third-party deps list:  cmake/thirdparty.json
 * Third-party build args.
 
-| args               | Description               |
-|--------------------|---------------------------|
-| -i, --intermediate | Third-party download/build path (default: `build_3rd/intermediate`) |
+| args               | Description                                                            |
+| ------------------ | ---------------------------------------------------------------------- |
+| -i, --intermediate | Third-party download/build path (default: `build_3rd/intermediate`)    |
 | -o, --output       | Third-party output root, effective `3RD_PATH` is `<output>/<platform>` |
-| -e, --engine       | Engine path (default: current repository root) |
-| -p, --platform     | Target Platform           |
-| -c, --clean        | Clear build               |
-| -t, --target       | Build Single Library      |
+| -e, --engine       | Engine path (default: current repository root)                         |
+| -p, --platform     | Target Platform                                                        |
+| -c, --clean        | Clear build                                                            |
+| -t, --target       | Build Single Library                                                   |
 
 * Default third-party layout
 
@@ -55,7 +81,7 @@ python3 python/third_party.py -i <intermediate_path> -o <output_path> -e <engine
 * Supported Platforms
 
 | platform  | arch              |
-|-----------|-------------------|
+| --------- | ----------------- |
 | Win32     | Window x86_64     |
 | MacOS-x86 | MacOS with x86_64 |
 | MacOS-arm | MacOS with arm    |
@@ -64,12 +90,22 @@ python3 python/third_party.py -i <intermediate_path> -o <output_path> -e <engine
 
 ### Build Engine Editor
 ```shell
-cmake -S . -B build -G "Visual Studio 17 2022" -D3RD_PATH=${path_to_3rd}
+cmake -S . -B build -G "Visual Studio 17 2022" -DSKY_THIRDPARTY_MODE=PREBUILT -D3RD_PATH=${path_to_3rd}
 cmake --build build
 ```
 
 If you use the default third-party layout, `${path_to_3rd}` should point to the platform subdirectory, for example `build_3rd/Win32`. You can also leave `3RD_PATH` unset and let CMake auto-load `build_3rd/thirdparty_cache.cmake`.
 
+### CI build/publish/reuse of third-party packages
+
+CI builds dependencies with `SKY_THIRDPARTY_MODE=LOCAL` and uses a workspace-local binary cache. The cache is:
+
+1. restored before build for reuse,
+2. populated by build jobs,
+3. uploaded as a CI artifact on `main` for downstream reuse.
+
+This keeps third-party package installation out of system directories and makes packages reusable across CI runs.
+
 ## Compile Shader
 ```shell
 python .\assets\shaders\compileshaders.py