From 36286efc635bdb59eea04f84e75905bef52cd1d0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 01:55:34 +0000
Subject: [PATCH 01/11] Initial plan


From 312a5f62444ba98a7bc7656e27c48483a3bd9610 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 02:05:07 +0000
Subject: [PATCH 02/11] feat: add vcpkg custom registry support for third-party
 dependencies

Add vcpkg manifest mode support alongside the existing 3RD_PATH-based
build. When CMAKE_TOOLCHAIN_FILE points to vcpkg, the build auto-detects
and uses vcpkg packages; otherwise the legacy python/third_party.py
workflow continues to work unchanged.

New files:
- vcpkg.json: manifest listing all dependencies with optional features
- vcpkg-configuration.json: default + custom registry (bluesky013/sky-vcpkg-registry)
- cmake/vcpkg.cmake: bridge that creates 3rdParty:: targets from vcpkg

Modified files:
- CMakeLists.txt: map SKY_BUILD_* options to VCPKG_MANIFEST_FEATURES
- cmake/options.cmake: add SKY_USE_VCPKG option
- cmake/thirdparty.cmake: auto-detect vcpkg vs legacy mode
- .github/workflows/cmake.yml: add vcpkg CI job

Co-authored-by: bluesky013 <35895395+bluesky013@users.noreply.github.com>
Agent-Logs-Url: https://github.com/bluesky013/SkyEngine/sessions/eade4691-4288-4e3e-869b-d626ec188c91
---
 .github/workflows/cmake.yml |  34 ++++++-
 CMakeLists.txt              |  54 +++++++++++
 cmake/options.cmake         |   2 +
 cmake/thirdparty.cmake      |  45 +++++----
 cmake/vcpkg.cmake           | 179 ++++++++++++++++++++++++++++++++++++
 vcpkg-configuration.json    |  20 ++++
 vcpkg.json                  | 102 ++++++++++++++++++++
 7 files changed, 418 insertions(+), 18 deletions(-)
 create mode 100644 cmake/vcpkg.cmake
 create mode 100644 vcpkg-configuration.json
 create mode 100644 vcpkg.json

diff --git a/.github/workflows/cmake.yml b/.github/workflows/cmake.yml
index f5d21258..7f9ed0ba 100644
--- a/.github/workflows/cmake.yml
+++ b/.github/workflows/cmake.yml
@@ -11,7 +11,8 @@ env:
   BUILD_TYPE: Release
 
 jobs:
-  build:
+  build-legacy:
+    name: Build (legacy 3RD_PATH)
     runs-on: windows-latest
 
     steps:
@@ -42,4 +43,33 @@ 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}}
+
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 658e5965..5f76e7b4 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,5 +1,59 @@
 cmake_minimum_required(VERSION 3.19)  # 3.19+ required for string(JSON ...)
 
+# ---------------------------------------------------------------------------
+# 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_USE_VCPKG)
+    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)
+    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/cmake/options.cmake b/cmake/options.cmake
index 260bc21c..c8dfa656 100644
--- a/cmake/options.cmake
+++ b/cmake/options.cmake
@@ -8,6 +8,8 @@ if (NOT 3RD_PATH STREQUAL "")
     set(3RD_PATH "${3RD_PATH}" CACHE PATH "SkyEngine 3rd path" FORCE)
 endif ()
 
+option(SKY_USE_VCPKG "use vcpkg for third-party dependencies" OFF)
+
 option(SKY_BUILD_EDITOR "build editor" OFF)
 option(SKY_EDITOR "editor mode" OFF)
 
diff --git a/cmake/thirdparty.cmake b/cmake/thirdparty.cmake
index a47f6dcd..49dc95f5 100644
--- a/cmake/thirdparty.cmake
+++ b/cmake/thirdparty.cmake
@@ -1,22 +1,30 @@
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${ENGINE_ROOT}/cmake/thirdparty)
 include(${ENGINE_ROOT}/cmake/thirdparty_helpers.cmake)
 
-function(sky_find_3rd)
-    cmake_parse_arguments(TMP
-        ""
-        "TARGET"
-        "DIR"
-        ${ARGN}
-        )
-    message("find target ${TMP_TARGET}")
-    set(${TMP_TARGET}_PATH ${3RD_PATH}/${TMP_DIR})
-    find_package(${TMP_TARGET})
-    if (NOT ${${TMP_TARGET}_FOUND})
-        message(FATAL_ERROR "${TMP_TARGET} not found")
-    endif()
-endfunction()
+# ---------------------------------------------------------------------------
+# Detect which mode to use:
+#   1. vcpkg   – when CMAKE_TOOLCHAIN_FILE points at the vcpkg toolchain
+#   2. legacy  – when 3RD_PATH is set (pre-built tree from python/third_party.py)
+# ---------------------------------------------------------------------------
+if (DEFINED VCPKG_TOOLCHAIN OR SKY_USE_VCPKG)
+    message(STATUS "[SkyEngine] Using vcpkg for third-party dependencies")
+    include(${ENGINE_ROOT}/cmake/vcpkg.cmake)
+elseif(EXISTS ${3RD_PATH})
+    function(sky_find_3rd)
+        cmake_parse_arguments(TMP
+            ""
+            "TARGET"
+            "DIR"
+            ${ARGN}
+            )
+        message("find target ${TMP_TARGET}")
+        set(${TMP_TARGET}_PATH ${3RD_PATH}/${TMP_DIR})
+        find_package(${TMP_TARGET})
+        if (NOT ${${TMP_TARGET}_FOUND})
+            message(FATAL_ERROR "${TMP_TARGET} not found")
+        endif()
+    endfunction()
 
-if(EXISTS ${3RD_PATH})
     # core
     sky_find_3rd(TARGET sfmt          DIR sfmt)
     sky_find_3rd(TARGET boost         DIR boost)
@@ -79,5 +87,10 @@ if(EXISTS ${3RD_PATH})
         sky_find_3rd(TARGET ImGuizmo      DIR ImGuizmo)
     endif ()
 else()
-    message(FATAL_ERROR "3rdParty folder: ${3RD_PATH} does not exist, call cmake defining a valid 3RD_PATH")
+    message(FATAL_ERROR
+        "No third-party source configured.\n"
+        "Either:\n"
+        "  1. Use vcpkg: cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake\n"
+        "  2. Use pre-built: cmake -B build -D3RD_PATH=<path-to-prebuilt-3rdparty>\n"
+    )
 endif()
diff --git a/cmake/vcpkg.cmake b/cmake/vcpkg.cmake
new file mode 100644
index 00000000..93188957
--- /dev/null
+++ b/cmake/vcpkg.cmake
@@ -0,0 +1,179 @@
+# cmake/vcpkg.cmake
+# Bridge module: creates 3rdParty:: targets from vcpkg-installed packages.
+# Included automatically when vcpkg toolchain is detected.
+
+include(${ENGINE_ROOT}/cmake/thirdparty_helpers.cmake)
+
+# ---------------------------------------------------------------------------
+# Helper: create a 3rdParty::<name> INTERFACE target forwarding to vcpkg
+# targets, but only if the alias does not already exist.
+# ---------------------------------------------------------------------------
+function(sky_vcpkg_alias ALIAS_NAME)
+    if (TARGET ${ALIAS_NAME})
+        return()
+    endif()
+    add_library(${ALIAS_NAME} INTERFACE IMPORTED GLOBAL)
+    target_link_libraries(${ALIAS_NAME} INTERFACE ${ARGN})
+endfunction()
+
+# ===========================================================================
+# Core dependencies (always required)
+# ===========================================================================
+
+# --- boost ------------------------------------------------------------------
+find_package(Boost REQUIRED COMPONENTS container graph)
+sky_vcpkg_alias(3rdParty::boost Boost::container Boost::graph)
+
+# --- sfmt -------------------------------------------------------------------
+find_package(sfmt CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::sfmt sfmt::sfmt)
+
+# --- taskflow ---------------------------------------------------------------
+find_package(Taskflow CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::taskflow Taskflow::Taskflow)
+
+# --- rapidjson --------------------------------------------------------------
+find_package(RapidJSON CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::rapidjson rapidjson)
+
+# --- sdl --------------------------------------------------------------------
+if (NOT ANDROID AND NOT IOS)
+    find_package(SDL2 CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::sdl SDL2::SDL2 SDL2::SDL2main)
+endif()
+
+# --- vulkan-memory-allocator ------------------------------------------------
+find_package(VulkanMemoryAllocator CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::vma GPUOpen::VulkanMemoryAllocator)
+
+# --- imgui ------------------------------------------------------------------
+find_package(imgui CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::imgui imgui::imgui)
+
+# --- glslang ----------------------------------------------------------------
+find_package(glslang CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::glslang
+    glslang::glslang
+    glslang::glslang-default-resource-limits
+    glslang::SPIRV
+    glslang::SPVRemapper
+)
+
+# --- SPIRV-Cross ------------------------------------------------------------
+find_package(spirv_cross_core CONFIG REQUIRED)
+find_package(spirv_cross_glsl CONFIG REQUIRED)
+find_package(spirv_cross_msl  CONFIG REQUIRED)
+find_package(spirv_cross_cpp  CONFIG REQUIRED)
+find_package(spirv_cross_reflect CONFIG REQUIRED)
+find_package(spirv_cross_util CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::SPIRVCross
+    spirv-cross-glsl
+    spirv-cross-msl
+    spirv-cross-cpp
+    spirv-cross-core
+    spirv-cross-reflect
+    spirv-cross-util
+)
+
+# --- dxcompiler (Windows only) ----------------------------------------------
+if (WIN32)
+    find_package(directx-dxc CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::dxcompiler Microsoft::DirectXShaderCompiler)
+endif()
+
+# --- googletest -------------------------------------------------------------
+find_package(GTest CONFIG REQUIRED)
+sky_vcpkg_alias(3rdParty::googletest GTest::gtest)
+
+# ===========================================================================
+# Optional dependencies (controlled by CMake options)
+# ===========================================================================
+
+# --- cpython ----------------------------------------------------------------
+if (SKY_BUILD_CPYTHON)
+    find_package(Python3 COMPONENTS Development REQUIRED)
+    sky_vcpkg_alias(3rdParty::cpython Python3::Python)
+endif()
+
+# --- lz4 (compression plugin) ----------------------------------------------
+if (SKY_BUILD_COMPRESSION)
+    find_package(lz4 CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::lz4 lz4::lz4)
+endif()
+
+# --- freetype (text plugin) -------------------------------------------------
+if (SKY_BUILD_FREETYPE)
+    find_package(Freetype REQUIRED)
+    sky_vcpkg_alias(3rdParty::freetype Freetype::Freetype)
+endif()
+
+# --- tracy (profiler) -------------------------------------------------------
+if (SKY_USE_TRACY)
+    find_package(Tracy CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::tracy Tracy::TracyClient)
+    add_definitions(-DTRACY_ENABLE)
+endif()
+
+# --- bullet3 (physics plugin) ----------------------------------------------
+if (SKY_BUILD_BULLET)
+    find_package(Bullet CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::bullet3
+        Bullet3Common::Bullet3Common
+        Bullet3Collision::Bullet3Collision
+        Bullet3Dynamics::Bullet3Dynamics
+        Bullet3Geometry::Bullet3Geometry
+        BulletCollision::BulletCollision
+        BulletDynamics::BulletDynamics
+        LinearMath::LinearMath
+    )
+endif()
+
+# --- recast (navigation plugin) --------------------------------------------
+if (SKY_BUILD_RECAST)
+    find_package(recastnavigation CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::recast
+        RecastNavigation::DebugUtils
+        RecastNavigation::Detour
+        RecastNavigation::DetourCrowd
+        RecastNavigation::DetourTileCache
+        RecastNavigation::Recast
+    )
+endif()
+
+# ===========================================================================
+# Editor dependencies (SKY_BUILD_EDITOR)
+# ===========================================================================
+if (SKY_BUILD_EDITOR)
+    # --- assimp -------------------------------------------------------------
+    find_package(assimp CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::assimp assimp::assimp)
+
+    # --- meshoptimizer ------------------------------------------------------
+    find_package(meshoptimizer CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::meshoptimizer meshoptimizer::meshoptimizer)
+
+    # --- stb ----------------------------------------------------------------
+    find_package(Stb REQUIRED)
+    if (NOT TARGET 3rdParty::stb)
+        add_library(3rdParty::stb INTERFACE IMPORTED GLOBAL)
+        target_include_directories(3rdParty::stb INTERFACE ${Stb_INCLUDE_DIR})
+    endif()
+
+    # --- ImGuizmo -----------------------------------------------------------
+    find_package(imguizmo CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::ImGuizmo imguizmo::imguizmo)
+
+    # --- GKlib (custom registry) --------------------------------------------
+    find_package(gklib CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::GKlib gklib::gklib)
+
+    # --- metis --------------------------------------------------------------
+    find_package(metis CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::metis metis::metis)
+
+    # --- ispc_texcomp (custom registry) -------------------------------------
+    find_package(ispc_texcomp CONFIG REQUIRED)
+    sky_vcpkg_alias(3rdParty::ispc_texcomp ispc_texcomp::ispc_texcomp)
+endif()
+
+message(STATUS "[SkyEngine] Third-party libraries resolved via vcpkg")
diff --git a/vcpkg-configuration.json b/vcpkg-configuration.json
new file mode 100644
index 00000000..d6b0f6cf
--- /dev/null
+++ b/vcpkg-configuration.json
@@ -0,0 +1,20 @@
+{
+	"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg-configuration.schema.json",
+	"default-registry": {
+		"kind": "git",
+		"repository": "https://github.com/microsoft/vcpkg",
+		"baseline": "c3867e714dd3a51c272826eea77267876517ed99"
+	},
+	"registries": [
+		{
+			"kind": "git",
+			"repository": "https://github.com/bluesky013/sky-vcpkg-registry",
+			"baseline": "TODO",
+			"packages": [
+				"sfmt",
+				"gklib",
+				"ispc-texcomp"
+			]
+		}
+	]
+}
diff --git a/vcpkg.json b/vcpkg.json
new file mode 100644
index 00000000..948b8da0
--- /dev/null
+++ b/vcpkg.json
@@ -0,0 +1,102 @@
+{
+	"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
+	"name": "skyengine",
+	"version-string": "0.1.0",
+	"description": "SkyEngine - A cross-platform game engine",
+	"dependencies": [
+		{
+			"name": "boost-container",
+			"version>=": "1.85.0"
+		},
+		{
+			"name": "boost-graph",
+			"version>=": "1.85.0"
+		},
+		"sfmt",
+		"rapidjson",
+		"taskflow",
+		{
+			"name": "sdl2",
+			"platform": "windows | osx | linux"
+		},
+		"vulkan-memory-allocator",
+		{
+			"name": "imgui",
+			"features": [
+				"docking-experimental"
+			]
+		},
+		"gtest",
+		"glslang",
+		"spirv-cross",
+		{
+			"name": "directx-dxc",
+			"platform": "windows"
+		}
+	],
+	"features": {
+		"editor": {
+			"description": "Editor and asset building tools",
+			"dependencies": [
+				{
+					"name": "assimp",
+					"platform": "windows | osx"
+				},
+				{
+					"name": "meshoptimizer",
+					"platform": "windows | osx"
+				},
+				{
+					"name": "stb",
+					"platform": "windows | osx"
+				},
+				{
+					"name": "imguizmo",
+					"platform": "windows | osx"
+				},
+				{
+					"name": "gklib",
+					"platform": "windows | osx"
+				},
+				{
+					"name": "metis",
+					"platform": "windows | osx"
+				},
+				{
+					"name": "ispc-texcomp",
+					"platform": "windows | osx"
+				}
+			]
+		},
+		"bullet": {
+			"description": "Bullet physics engine",
+			"dependencies": [
+				"bullet3"
+			]
+		},
+		"recast": {
+			"description": "Recast navigation mesh generation",
+			"dependencies": [
+				"recastnavigation"
+			]
+		},
+		"tracy": {
+			"description": "Tracy frame profiler",
+			"dependencies": [
+				"tracy"
+			]
+		},
+		"freetype": {
+			"description": "FreeType font rendering",
+			"dependencies": [
+				"freetype"
+			]
+		},
+		"compression": {
+			"description": "LZ4 compression support",
+			"dependencies": [
+				"lz4"
+			]
+		}
+	}
+}

From 5f96477b849ba9000054ace12c99ed48c1f4e232 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 02:06:40 +0000
Subject: [PATCH 03/11] fix: add explicit permissions to CI workflow for
 security

Co-authored-by: bluesky013 <35895395+bluesky013@users.noreply.github.com>
Agent-Logs-Url: https://github.com/bluesky013/SkyEngine/sessions/eade4691-4288-4e3e-869b-d626ec188c91
---
 .github/workflows/cmake.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/cmake.yml b/.github/workflows/cmake.yml
index 7f9ed0ba..815a3f11 100644
--- a/.github/workflows/cmake.yml
+++ b/.github/workflows/cmake.yml
@@ -10,6 +10,9 @@ env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
   BUILD_TYPE: Release
 
+permissions:
+  contents: read
+
 jobs:
   build-legacy:
     name: Build (legacy 3RD_PATH)

From 009e2bbc394f02928bac9d7cb0fe4562326d3f66 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 02:31:54 +0000
Subject: [PATCH 04/11] Switch to Zhuyin-Graphics/vcpkg-registry with
 thirdparty.json version pins

- vcpkg-configuration.json: change custom registry from bluesky013/sky-vcpkg-registry
  to Zhuyin-Graphics/vcpkg-registry with baseline 303d3f22
- vcpkg.json: update boost version>= to 1.88.0 (from thirdparty.json tag boost-1.88.0)
- vcpkg.json: add overrides section pinning versions from thirdparty.json tags:
  boost 1.88.0, sdl2 2.32.6, taskflow 3.7.0, vma 3.2.1,
  glslang 15.3.0, spirv-cross 1.4.313.0, tracy 0.11.1

Co-authored-by: bluesky013 <35895395+bluesky013@users.noreply.github.com>
Agent-Logs-Url: https://github.com/bluesky013/SkyEngine/sessions/709f2c17-ffc8-4542-92b3-9fd48942ebdf
---
 vcpkg-configuration.json |  4 ++--
 vcpkg.json               | 40 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/vcpkg-configuration.json b/vcpkg-configuration.json
index d6b0f6cf..0fecf0ef 100644
--- a/vcpkg-configuration.json
+++ b/vcpkg-configuration.json
@@ -8,8 +8,8 @@
 	"registries": [
 		{
 			"kind": "git",
-			"repository": "https://github.com/bluesky013/sky-vcpkg-registry",
-			"baseline": "TODO",
+			"repository": "https://github.com/Zhuyin-Graphics/vcpkg-registry",
+			"baseline": "303d3f22e71e31ded282ff6dfe103ed27723682c",
 			"packages": [
 				"sfmt",
 				"gklib",
diff --git a/vcpkg.json b/vcpkg.json
index 948b8da0..d9fcc6fd 100644
--- a/vcpkg.json
+++ b/vcpkg.json
@@ -6,11 +6,11 @@
 	"dependencies": [
 		{
 			"name": "boost-container",
-			"version>=": "1.85.0"
+			"version>=": "1.88.0"
 		},
 		{
 			"name": "boost-graph",
-			"version>=": "1.85.0"
+			"version>=": "1.88.0"
 		},
 		"sfmt",
 		"rapidjson",
@@ -98,5 +98,39 @@
 				"lz4"
 			]
 		}
-	}
+	},
+	"overrides": [
+		{
+			"name": "boost-container",
+			"version": "1.88.0"
+		},
+		{
+			"name": "boost-graph",
+			"version": "1.88.0"
+		},
+		{
+			"name": "sdl2",
+			"version": "2.32.6"
+		},
+		{
+			"name": "taskflow",
+			"version": "3.7.0"
+		},
+		{
+			"name": "vulkan-memory-allocator",
+			"version": "3.2.1"
+		},
+		{
+			"name": "glslang",
+			"version": "15.3.0"
+		},
+		{
+			"name": "spirv-cross",
+			"version": "1.4.313.0"
+		},
+		{
+			"name": "tracy",
+			"version": "0.11.1"
+		}
+	]
 }

From 4ed0331baa06166fa29a1713787b88b80ad15689 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 03:03:26 +0000
Subject: [PATCH 05/11] Add cross-platform vcpkg triplets and CI for
 Linux/macOS

- Add custom triplet files for arm64-android, arm64-ios, arm64-osx,
  x64-osx, x64-linux, x64-windows-static in triplets/
- Set VCPKG_OVERLAY_TRIPLETS in CMakeLists.txt before project() so
  vcpkg can find custom triplets for Android and iOS builds
- Add Linux (ubuntu-latest) and macOS (macos-14 ARM) CI build jobs
  using vcpkg to verify cross-platform support

Co-authored-by: bluesky013 <35895395+bluesky013@users.noreply.github.com>
Agent-Logs-Url: https://github.com/bluesky013/SkyEngine/sessions/f99bbe0f-866d-458d-81ed-9c39c71bc129
---
 .github/workflows/cmake.yml       | 57 +++++++++++++++++++++++++++++++
 CMakeLists.txt                    |  3 ++
 triplets/arm64-android.cmake      |  5 +++
 triplets/arm64-ios.cmake          |  5 +++
 triplets/arm64-osx.cmake          |  5 +++
 triplets/x64-linux.cmake          |  4 +++
 triplets/x64-osx.cmake            |  5 +++
 triplets/x64-windows-static.cmake |  3 ++
 8 files changed, 87 insertions(+)
 create mode 100644 triplets/arm64-android.cmake
 create mode 100644 triplets/arm64-ios.cmake
 create mode 100644 triplets/arm64-osx.cmake
 create mode 100644 triplets/x64-linux.cmake
 create mode 100644 triplets/x64-osx.cmake
 create mode 100644 triplets/x64-windows-static.cmake

diff --git a/.github/workflows/cmake.yml b/.github/workflows/cmake.yml
index 815a3f11..0fb89124 100644
--- a/.github/workflows/cmake.yml
+++ b/.github/workflows/cmake.yml
@@ -76,3 +76,60 @@ jobs:
       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/CMakeLists.txt b/CMakeLists.txt
index 5f76e7b4..4ff41aef 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -18,6 +18,9 @@ elseif (CMAKE_TOOLCHAIN_FILE)
 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)
diff --git a/triplets/arm64-android.cmake b/triplets/arm64-android.cmake
new file mode 100644
index 00000000..c7b0cf61
--- /dev/null
+++ b/triplets/arm64-android.cmake
@@ -0,0 +1,5 @@
+set(VCPKG_TARGET_ARCHITECTURE arm64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE static)
+set(VCPKG_CMAKE_SYSTEM_NAME Android)
+set(VCPKG_CMAKE_SYSTEM_VERSION 31)
diff --git a/triplets/arm64-ios.cmake b/triplets/arm64-ios.cmake
new file mode 100644
index 00000000..779cca22
--- /dev/null
+++ b/triplets/arm64-ios.cmake
@@ -0,0 +1,5 @@
+set(VCPKG_TARGET_ARCHITECTURE arm64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE static)
+set(VCPKG_CMAKE_SYSTEM_NAME iOS)
+set(VCPKG_OSX_DEPLOYMENT_TARGET 13.0)
diff --git a/triplets/arm64-osx.cmake b/triplets/arm64-osx.cmake
new file mode 100644
index 00000000..003f813f
--- /dev/null
+++ b/triplets/arm64-osx.cmake
@@ -0,0 +1,5 @@
+set(VCPKG_TARGET_ARCHITECTURE arm64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE static)
+set(VCPKG_CMAKE_SYSTEM_NAME Darwin)
+set(VCPKG_OSX_ARCHITECTURES arm64)
diff --git a/triplets/x64-linux.cmake b/triplets/x64-linux.cmake
new file mode 100644
index 00000000..009c89c4
--- /dev/null
+++ b/triplets/x64-linux.cmake
@@ -0,0 +1,4 @@
+set(VCPKG_TARGET_ARCHITECTURE x64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE static)
+set(VCPKG_CMAKE_SYSTEM_NAME Linux)
diff --git a/triplets/x64-osx.cmake b/triplets/x64-osx.cmake
new file mode 100644
index 00000000..07af6220
--- /dev/null
+++ b/triplets/x64-osx.cmake
@@ -0,0 +1,5 @@
+set(VCPKG_TARGET_ARCHITECTURE x64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE static)
+set(VCPKG_CMAKE_SYSTEM_NAME Darwin)
+set(VCPKG_OSX_ARCHITECTURES x86_64)
diff --git a/triplets/x64-windows-static.cmake b/triplets/x64-windows-static.cmake
new file mode 100644
index 00000000..75f9b953
--- /dev/null
+++ b/triplets/x64-windows-static.cmake
@@ -0,0 +1,3 @@
+set(VCPKG_TARGET_ARCHITECTURE x64)
+set(VCPKG_CRT_LINKAGE static)
+set(VCPKG_LIBRARY_LINKAGE static)

From 9b23fa6bfce4f33633c01bbec12741a5b26035d0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 24 Mar 2026 18:26:32 +0000
Subject: [PATCH 06/11] Add vcpkg registry port definitions for sfmt, gklib,
 ispc-texcomp

Prepare port files for submission to Zhuyin-Graphics/vcpkg-registry:
- ports/sfmt: SFMT v1.5.4 with CMakeLists.txt patch and inline fix
- ports/gklib: GKlib v5.1.1 with CMake install/export patch
- ports/ispc-texcomp: ISPC Texture Compressor port
- versions/baseline.json with all port baselines
- README with submission instructions

SHA512 hashes and git-tree hashes are placeholders to be
computed when the ports are added to the actual registry.

Co-authored-by: bluesky013 <35895395+bluesky013@users.noreply.github.com>
Agent-Logs-Url: https://github.com/bluesky013/SkyEngine/sessions/ab00aac0-1112-448f-88ad-8b3b2837e3a5
---
 registry/README.md                           |  54 ++++++++
 registry/ports/gklib/fix-cmake-install.patch |  36 +++++
 registry/ports/gklib/portfile.cmake          |  22 +++
 registry/ports/gklib/vcpkg.json              |  19 +++
 registry/ports/ispc-texcomp/portfile.cmake   |  19 +++
 registry/ports/ispc-texcomp/vcpkg.json       |  18 +++
 registry/ports/sfmt/add-cmake-support.patch  | 134 +++++++++++++++++++
 registry/ports/sfmt/portfile.cmake           |  22 +++
 registry/ports/sfmt/vcpkg.json               |  17 +++
 registry/versions/baseline.json              |  20 +++
 registry/versions/g-/gklib.json              |   9 ++
 registry/versions/i-/ispc-texcomp.json       |   9 ++
 registry/versions/s-/sfmt.json               |   9 ++
 13 files changed, 388 insertions(+)
 create mode 100644 registry/README.md
 create mode 100644 registry/ports/gklib/fix-cmake-install.patch
 create mode 100644 registry/ports/gklib/portfile.cmake
 create mode 100644 registry/ports/gklib/vcpkg.json
 create mode 100644 registry/ports/ispc-texcomp/portfile.cmake
 create mode 100644 registry/ports/ispc-texcomp/vcpkg.json
 create mode 100644 registry/ports/sfmt/add-cmake-support.patch
 create mode 100644 registry/ports/sfmt/portfile.cmake
 create mode 100644 registry/ports/sfmt/vcpkg.json
 create mode 100644 registry/versions/baseline.json
 create mode 100644 registry/versions/g-/gklib.json
 create mode 100644 registry/versions/i-/ispc-texcomp.json
 create mode 100644 registry/versions/s-/sfmt.json

diff --git a/registry/README.md b/registry/README.md
new file mode 100644
index 00000000..751a4c65
--- /dev/null
+++ b/registry/README.md
@@ -0,0 +1,54 @@
+# vcpkg Registry Ports
+
+This directory contains vcpkg port definitions for packages that are not available
+in the main [microsoft/vcpkg](https://github.com/microsoft/vcpkg) registry.
+
+These ports are intended for submission to
+[Zhuyin-Graphics/vcpkg-registry](https://github.com/Zhuyin-Graphics/vcpkg-registry).
+
+## Ports
+
+| Port | Version | Description |
+|------|---------|-------------|
+| sfmt | 1.5.4 | SIMD-oriented Fast Mersenne Twister pseudorandom number generator |
+| gklib | 5.1.1 | Helper routines used by KarypisLab software (METIS, etc.) |
+| ispc-texcomp | 2024-01-01 | ISPC Texture Compressor |
+
+## How to Submit
+
+Follow the steps in the registry's
+[AddPorts.md](https://github.com/Zhuyin-Graphics/vcpkg-registry/blob/main/AddPorts.md):
+
+1. Copy the port directories from `registry/ports/` into the registry's `ports/` directory
+2. Run `vcpkg format-manifest` on each port's `vcpkg.json`
+3. Compute the SHA512 hashes for `vcpkg_from_github()` in each `portfile.cmake`
+   (replace the placeholder `0` values)
+4. Commit the ports, then use `vcpkg x-add-version` to generate proper git-tree hashes:
+   ```bash
+   cd <vcpkg-registry>
+   vcpkg x-add-version --x-builtin-ports-root=./ports \
+     --x-builtin-registry-versions-dir=./versions sfmt
+   vcpkg x-add-version --x-builtin-ports-root=./ports \
+     --x-builtin-registry-versions-dir=./versions gklib
+   vcpkg x-add-version --x-builtin-ports-root=./ports \
+     --x-builtin-registry-versions-dir=./versions ispc-texcomp
+   ```
+5. Update `versions/baseline.json` with correct baselines
+6. Commit and push, then open a merge request
+
+## SHA512 Hash Computation
+
+To compute the correct SHA512 hash for each port's `vcpkg_from_github()`:
+
+```bash
+# Download the source archive and compute its SHA512
+# For sfmt:
+wget -qO- https://github.com/MersenneTwister-Lab/SFMT/archive/refs/tags/1.5.4.tar.gz | sha512sum
+
+# For gklib:
+wget -qO- https://github.com/KarypisLab/GKlib/archive/refs/tags/METIS-v5.1.1-DistDGL-0.5.tar.gz | sha512sum
+```
+
+Or let vcpkg compute them automatically — when the hash is `0`, vcpkg will
+download the archive, print the correct hash, and fail. Copy the hash from the
+error output into the portfile.
diff --git a/registry/ports/gklib/fix-cmake-install.patch b/registry/ports/gklib/fix-cmake-install.patch
new file mode 100644
index 00000000..be6eb1ea
--- /dev/null
+++ b/registry/ports/gklib/fix-cmake-install.patch
@@ -0,0 +1,36 @@
+diff --git a/CMakeLists.txt b/CMakeLists.txt
+index 9cd1b4b..d76b570 100644
+--- a/CMakeLists.txt
++++ b/CMakeLists.txt
+@@ -12,8 +12,7 @@ include_directories(".")
+ if(MSVC)
+   include_directories("win32")
+   file(GLOB win32_sources RELATIVE "win32" "*.c")
+-else(MSVC)
+-  set(win32_sources, "")
++  file(GLOB win32_includes ${GKLIB_PATH}/win32/*.h)
+ endif(MSVC)
+ 
+ add_library(GKlib ${GKlib_sources} ${win32_sources})
+@@ -22,10 +21,12 @@ if(UNIX)
+   target_link_libraries(GKlib m)
+ endif(UNIX)
+ 
+-include_directories("test")
+-add_subdirectory("test")
+-
+ install(TARGETS GKlib
++  EXPORT gklib-targets
+   ARCHIVE DESTINATION lib/${LINSTALL_PATH}
+   LIBRARY DESTINATION lib/${LINSTALL_PATH})
++
++install(EXPORT gklib-targets
++  FILE gklib-config.cmake
++  NAMESPACE gklib::
++  DESTINATION share/gklib)
++
+ install(FILES ${GKlib_includes} DESTINATION include/${HINSTALL_PATH})
++
++if(MSVC)
++  install(FILES ${win32_includes} DESTINATION include/win32)
++endif(MSVC)
diff --git a/registry/ports/gklib/portfile.cmake b/registry/ports/gklib/portfile.cmake
new file mode 100644
index 00000000..f53d4b42
--- /dev/null
+++ b/registry/ports/gklib/portfile.cmake
@@ -0,0 +1,22 @@
+vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
+
+vcpkg_from_github(
+  OUT_SOURCE_PATH SOURCE_PATH
+  REPO KarypisLab/GKlib
+  REF METIS-v5.1.1-DistDGL-0.5
+  SHA512 0
+  HEAD_REF master
+  PATCHES
+    fix-cmake-install.patch
+)
+
+vcpkg_cmake_configure(
+  SOURCE_PATH "${SOURCE_PATH}"
+)
+
+vcpkg_cmake_install()
+vcpkg_copy_pdbs()
+
+file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
+
+file(INSTALL "${SOURCE_PATH}/LICENSE.txt" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
diff --git a/registry/ports/gklib/vcpkg.json b/registry/ports/gklib/vcpkg.json
new file mode 100644
index 00000000..e2b508a9
--- /dev/null
+++ b/registry/ports/gklib/vcpkg.json
@@ -0,0 +1,19 @@
+{
+  "name": "gklib",
+  "version": "5.1.1",
+  "port-version": 1,
+  "description": "A library of various helper routines and frameworks used by KarypisLab software (METIS, etc.).",
+  "homepage": "https://github.com/KarypisLab/GKlib",
+  "license": "Apache-2.0",
+  "supports": "windows | osx",
+  "dependencies": [
+    {
+      "name": "vcpkg-cmake",
+      "host": true
+    },
+    {
+      "name": "vcpkg-cmake-config",
+      "host": true
+    }
+  ]
+}
diff --git a/registry/ports/ispc-texcomp/portfile.cmake b/registry/ports/ispc-texcomp/portfile.cmake
new file mode 100644
index 00000000..6505365d
--- /dev/null
+++ b/registry/ports/ispc-texcomp/portfile.cmake
@@ -0,0 +1,19 @@
+vcpkg_from_github(
+  OUT_SOURCE_PATH SOURCE_PATH
+  REPO bluesky013/ISPCTextureCompressor
+  REF "${VERSION}"
+  SHA512 0
+  HEAD_REF master
+)
+
+vcpkg_cmake_configure(
+  SOURCE_PATH "${SOURCE_PATH}"
+)
+
+vcpkg_cmake_install()
+vcpkg_copy_pdbs()
+
+file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
+
+file(INSTALL "${SOURCE_PATH}/ispc_texcomp/license.txt"
+  DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
diff --git a/registry/ports/ispc-texcomp/vcpkg.json b/registry/ports/ispc-texcomp/vcpkg.json
new file mode 100644
index 00000000..949f2e3b
--- /dev/null
+++ b/registry/ports/ispc-texcomp/vcpkg.json
@@ -0,0 +1,18 @@
+{
+  "name": "ispc-texcomp",
+  "version-date": "2024-01-01",
+  "description": "ISPC Texture Compressor - fast texture compression using ISPC.",
+  "homepage": "https://github.com/bluesky013/ISPCTextureCompressor",
+  "license": "MIT",
+  "supports": "windows | osx",
+  "dependencies": [
+    {
+      "name": "vcpkg-cmake",
+      "host": true
+    },
+    {
+      "name": "vcpkg-cmake-config",
+      "host": true
+    }
+  ]
+}
diff --git a/registry/ports/sfmt/add-cmake-support.patch b/registry/ports/sfmt/add-cmake-support.patch
new file mode 100644
index 00000000..0d6c2df8
--- /dev/null
+++ b/registry/ports/sfmt/add-cmake-support.patch
@@ -0,0 +1,134 @@
+diff --git a/CMakeLists.txt b/CMakeLists.txt
+new file mode 100644
+index 0000000..969bc4d
+--- /dev/null
++++ b/CMakeLists.txt
+@@ -0,0 +1,106 @@
++# CMake minimum version
++cmake_minimum_required(VERSION 3.10)
++
++# project name and languages
++project(SFMT C)
++
++# options
++option(USE_SSE2 "Use SSE2" OFF)
++option(USE_AVX2 "Use AVX2" OFF)
++option(USE_AVX512 "Use AVX512" OFF)
++option(USE_ALTI "Use ALTI" OFF)
++option(USE_OSX_ALTI "Use OSX ALTI" OFF)
++option(USE_BIG64 "Use BIG64" OFF)
++
++option(USE_M607 "Use M607" OFF)
++option(USE_M1279 "Use M1279" OFF)
++option(USE_M2281 "Use M2281" OFF)
++option(USE_M11213 "Use M11213" OFF)
++option(USE_M19937 "Use M19937" OFF)
++option(USE_M44497 "Use M44497" OFF)
++option(USE_M86243 "Use M86243" OFF)
++option(USE_M132049 "Use M132049" OFF)
++option(USE_M216091 "Use M216091" OFF)
++
++# MEXP variable
++if(USE_M607)
++    set(MEXP 607)
++elseif(USE_M1279)
++    set(MEXP 1279)
++elseif(USE_M2281)
++    set(MEXP 2281)
++elseif(USE_M11213)
++    set(MEXP 11213)
++elseif(USE_M19937)
++    set(MEXP 19937)
++elseif(USE_M44497)
++    set(MEXP 44497)
++elseif(USE_M86243)
++    set(MEXP 86243)
++elseif(USE_M132049)
++    set(MEXP 132049)
++elseif(USE_M216091)
++    set(MEXP 216091)
++else()
++    set(MEXP 19937) # default
++endif()
++
++# optimize
++set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O2 -DNDEBUG")
++
++# SFMT_DEFS and CMAKE_C_FLAGS
++if(MSVC) # Visual C++
++    if(USE_SSE2)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_SSE2=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /arch:SSE2")
++    elseif(USE_AVX2)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_SSE2=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /arch:AVX2")
++    elseif(USE_AVX512)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_SSE2=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /arch:AVX512")
++    else()
++        set(SFMT_DEFS SFMT_MEXP=${MEXP}) # default
++    endif()
++else()
++    if(USE_SSE2)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_SSE2=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -msse")
++    elseif(USE_AVX2)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_SSE2=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mavx2")
++    elseif(USE_AVX512)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_SSE2=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mavx512vl")
++    elseif(USE_ALTI)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_ALTIVEC=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mabi=altivec -maltivec")
++    elseif(USE_OSX_ALTI)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} HAVE_ALTIVEC=1)
++        set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -faltivec -maltivec")
++    elseif(USE_BIG64)
++        set(SFMT_DEFS SFMT_MEXP=${MEXP} ONLY64=1)
++    else()
++        set(SFMT_DEFS SFMT_MEXP=${MEXP}) # default
++    endif()
++endif()
++
++# libSFMT.a --- the static library
++add_library(SFMT STATIC SFMT.c)
++target_compile_definitions(SFMT PRIVATE ${SFMT_DEFS})
++target_include_directories(SFMT PUBLIC
++    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
++    $<INSTALL_INTERFACE:include>
++)
++
++install(TARGETS SFMT
++    EXPORT sfmt-targets
++    ARCHIVE DESTINATION lib
++    LIBRARY DESTINATION lib)
++
++install(EXPORT sfmt-targets
++    FILE sfmt-config.cmake
++    NAMESPACE sfmt::
++    DESTINATION share/sfmt)
++
++install(FILES
++    SFMT.h
++    SFMT-alti.h
++    SFMT-avx256.h
++    SFMT-common.h
++    SFMT-neon.h
++    SFMT-sse2.h
++    SFMT-sse2-msc.h
++    SFMT-params.h
++    SFMT-params19937.h
++    DESTINATION include)
+diff --git a/SFMT.h b/SFMT.h
+index 34d9e74..06b4bee 100644
+--- a/SFMT.h
++++ b/SFMT.h
+@@ -46,7 +46,6 @@ extern "C" {
+ #elif defined(_MSC_VER) || defined(__BORLANDC__)
+   typedef unsigned int uint32_t;
+   typedef unsigned __int64 uint64_t;
+-  #define inline __inline
+ #else
+   #include <inttypes.h>
+   #if defined(__GNUC__)
diff --git a/registry/ports/sfmt/portfile.cmake b/registry/ports/sfmt/portfile.cmake
new file mode 100644
index 00000000..63682187
--- /dev/null
+++ b/registry/ports/sfmt/portfile.cmake
@@ -0,0 +1,22 @@
+vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
+
+vcpkg_from_github(
+  OUT_SOURCE_PATH SOURCE_PATH
+  REPO MersenneTwister-Lab/SFMT
+  REF ${VERSION}
+  SHA512 0
+  HEAD_REF master
+  PATCHES
+    add-cmake-support.patch
+)
+
+vcpkg_cmake_configure(
+  SOURCE_PATH "${SOURCE_PATH}"
+)
+
+vcpkg_cmake_install()
+vcpkg_copy_pdbs()
+
+file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
+
+vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE.txt")
diff --git a/registry/ports/sfmt/vcpkg.json b/registry/ports/sfmt/vcpkg.json
new file mode 100644
index 00000000..677e62e0
--- /dev/null
+++ b/registry/ports/sfmt/vcpkg.json
@@ -0,0 +1,17 @@
+{
+  "name": "sfmt",
+  "version": "1.5.4",
+  "description": "SIMD-oriented Fast Mersenne Twister (SFMT) pseudorandom number generator.",
+  "homepage": "https://github.com/MersenneTwister-Lab/SFMT",
+  "license": "BSD-3-Clause",
+  "dependencies": [
+    {
+      "name": "vcpkg-cmake",
+      "host": true
+    },
+    {
+      "name": "vcpkg-cmake-config",
+      "host": true
+    }
+  ]
+}
diff --git a/registry/versions/baseline.json b/registry/versions/baseline.json
new file mode 100644
index 00000000..722e97a9
--- /dev/null
+++ b/registry/versions/baseline.json
@@ -0,0 +1,20 @@
+{
+  "default": {
+    "crc32c": {
+      "baseline": "1.1.2",
+      "port-version": 0
+    },
+    "sfmt": {
+      "baseline": "1.5.4",
+      "port-version": 0
+    },
+    "gklib": {
+      "baseline": "5.1.1",
+      "port-version": 1
+    },
+    "ispc-texcomp": {
+      "baseline": "2024-01-01",
+      "port-version": 0
+    }
+  }
+}
diff --git a/registry/versions/g-/gklib.json b/registry/versions/g-/gklib.json
new file mode 100644
index 00000000..e0566140
--- /dev/null
+++ b/registry/versions/g-/gklib.json
@@ -0,0 +1,9 @@
+{
+  "versions": [
+    {
+      "git-tree": "0000000000000000000000000000000000000000",
+      "version": "5.1.1",
+      "port-version": 1
+    }
+  ]
+}
diff --git a/registry/versions/i-/ispc-texcomp.json b/registry/versions/i-/ispc-texcomp.json
new file mode 100644
index 00000000..c5cb5cee
--- /dev/null
+++ b/registry/versions/i-/ispc-texcomp.json
@@ -0,0 +1,9 @@
+{
+  "versions": [
+    {
+      "git-tree": "0000000000000000000000000000000000000000",
+      "version-date": "2024-01-01",
+      "port-version": 0
+    }
+  ]
+}
diff --git a/registry/versions/s-/sfmt.json b/registry/versions/s-/sfmt.json
new file mode 100644
index 00000000..9a837fc4
--- /dev/null
+++ b/registry/versions/s-/sfmt.json
@@ -0,0 +1,9 @@
+{
+  "versions": [
+    {
+      "git-tree": "0000000000000000000000000000000000000000",
+      "version": "1.5.4",
+      "port-version": 0
+    }
+  ]
+}

From 14c044eb64e295ac1bca0e92cff321d58ab337f1 Mon Sep 17 00:00:00 2001
From: Yiwen Xue <15225434259xue@gmail.com>
Date: Sun, 29 Mar 2026 15:13:51 +0800
Subject: [PATCH 07/11] add adaption roadmap and vcpkg booststrap utils

---
 cmake/thirdparty.cmake                      |  18 ++
 cmake/vcpkg_bootstrap.cmake                 |  90 +++++++++
 docs/README.md                              |   5 +
 docs/dependency/vcpkg-adaptation-roadmap.md | 196 ++++++++++++++++++++
 vcpkg-configuration.json                    |   6 +-
 5 files changed, 311 insertions(+), 4 deletions(-)
 create mode 100644 cmake/vcpkg_bootstrap.cmake
 create mode 100644 docs/README.md
 create mode 100644 docs/dependency/vcpkg-adaptation-roadmap.md

diff --git a/cmake/thirdparty.cmake b/cmake/thirdparty.cmake
index 49dc95f5..a2b6a001 100644
--- a/cmake/thirdparty.cmake
+++ b/cmake/thirdparty.cmake
@@ -1,6 +1,24 @@
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${ENGINE_ROOT}/cmake/thirdparty)
 include(${ENGINE_ROOT}/cmake/thirdparty_helpers.cmake)
 
+## vcpkg booststrap
+
+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")
+list(APPEND VCPKG_FEATURE_FLAGS manifests)
+
+# detect platform
+# TODO: try to adapt to more platforms
+if(WIN32)
+  set(VCPKG_TARGET_TRIPLET x64-windows)
+elseif(UNIX)
+  set(VCPKG_TARGET_TRIPLET x64-linux)
+endif()
+
 # ---------------------------------------------------------------------------
 # Detect which mode to use:
 #   1. vcpkg   – when CMAKE_TOOLCHAIN_FILE points at the vcpkg toolchain
diff --git a/cmake/vcpkg_bootstrap.cmake b/cmake/vcpkg_bootstrap.cmake
new file mode 100644
index 00000000..d4555f05
--- /dev/null
+++ b/cmake/vcpkg_bootstrap.cmake
@@ -0,0 +1,90 @@
+# Copyright (c) 2022 by Osyotr
+# https://gist.github.com/Osyotr/e2d415312a10183bc7c614013494bf21
+# Boost Software License
+# Permission is hereby granted, free of charge, to any person or organization
+# obtaining a copy of the software and accompanying documentation covered by
+# this license (the "Software") to use, reproduce, display, distribute,
+# execute, and transmit the Software, and to prepare derivative works of the
+# Software, and to permit third-parties to whom the Software is furnished to
+# do so, all subject to the following:
+#
+# The copyright notices in the Software and this entire statement, including
+# the above license grant, this restriction and the following disclaimer,
+# must be included in all copies of the Software, in whole or in part, and
+# all derivative works of the Software, unless such copies or derivative
+# works are solely in the form of machine-executable object code generated by
+# a source language processor.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+# SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+# FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+include_guard(GLOBAL)
+
+function(x_vcpkg_bootstrap)
+    if(NOT GIT_EXECUTABLE)
+        find_package(Git REQUIRED)
+    endif()
+
+    set(X_VCPKG_GIT_REPOSITORY_URL "https://github.com/Microsoft/vcpkg" CACHE STRING "Vcpkg git repository")
+	set(X_VCPKG_CLONE_DIR "${CMAKE_SOURCE_DIR}/vcpkg" CACHE PATH "Vcpkg clone directory")
+
+    if(NOT EXISTS "${X_VCPKG_CLONE_DIR}/.git")
+        message(STATUS "Cloning vcpkg into ${X_VCPKG_CLONE_DIR}")
+        execute_process(
+            COMMAND "${GIT_EXECUTABLE}" clone --quiet "${X_VCPKG_GIT_REPOSITORY_URL}" "${X_VCPKG_CLONE_DIR}"
+            ERROR_VARIABLE _vcpkg_git_clone_error
+        )
+        if(_vcpkg_git_clone_error)
+            message(FATAL_ERROR "Could not clone vcpkg repository from ${X_VCPKG_GIT_REPOSITORY_URL}\nMake sure you have access rights and the URL is valid.")
+        endif()
+        message(STATUS "Cloning vcpkg into ${X_VCPKG_CLONE_DIR} - done")
+    endif()
+
+    execute_process(
+        COMMAND "${GIT_EXECUTABLE}" rev-parse HEAD
+        WORKING_DIRECTORY "${X_VCPKG_CLONE_DIR}"
+        OUTPUT_VARIABLE _vcpkg_current_head_sha
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        COMMAND_ERROR_IS_FATAL ANY
+    )
+    set(_baseline_sha "${_vcpkg_current_head_sha}")
+
+    file(READ "${CMAKE_SOURCE_DIR}/vcpkg-configuration.json" _vcpkg_configuration_json_contents)
+    string(JSON _baseline_sha ERROR_VARIABLE _get_baseline_err GET "${_vcpkg_configuration_json_contents}" "default-registry" "baseline")
+
+    set(_should_update_vcpkg FALSE)
+    if(NOT "${_vcpkg_current_head_sha}" STREQUAL "${_baseline_sha}")
+        set(_should_update_vcpkg TRUE)
+    endif()
+
+    if(_should_update_vcpkg)
+        message(STATUS "Fetching changes from vcpkg upstream")
+        execute_process(
+            COMMAND "${GIT_EXECUTABLE}" fetch --quiet --prune
+            WORKING_DIRECTORY "${X_VCPKG_CLONE_DIR}"
+            # No error checking here to allow offline usage
+        )
+        message(STATUS "Fetching changes from vcpkg upstream - done")
+
+        message(STATUS "Switching vcpkg HEAD to ${_baseline_sha}")
+        execute_process(
+            COMMAND "${GIT_EXECUTABLE}" reset --quiet --hard "${_baseline_sha}"
+            COMMAND "${GIT_EXECUTABLE}" clean -qfd
+            WORKING_DIRECTORY "${X_VCPKG_CLONE_DIR}"
+            COMMAND_ERROR_IS_FATAL ANY
+        )
+        message(STATUS "Switching vcpkg HEAD to ${_baseline_sha} - done")
+
+        # Remove vcpkg executable to trigger bootstrap
+        if(CMAKE_HOST_SYSTEM_NAME STREQUAL "Windows")
+            file(REMOVE "${X_VCPKG_CLONE_DIR}/vcpkg.exe")
+        else()
+            file(REMOVE "${X_VCPKG_CLONE_DIR}/vcpkg")
+        endif()
+    endif()
+endfunction()
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..c17a4e88
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,5 @@
+# SkyEngine Documentation
+
+## Build And Dependency
+
+- [Third-Party vcpkg Adaptation Roadmap](dependency/vcpkg-adaptation-roadmap.md)
diff --git a/docs/dependency/vcpkg-adaptation-roadmap.md b/docs/dependency/vcpkg-adaptation-roadmap.md
new file mode 100644
index 00000000..501f1327
--- /dev/null
+++ b/docs/dependency/vcpkg-adaptation-roadmap.md
@@ -0,0 +1,196 @@
+---
+title: "SkyEngine Third-Party Package Adaptation to vcpkg + Custom Registry"
+description: "Complete adaptation inventory, tasks, constraints, and phased roadmap for SkyEngine third-party dependencies."
+module: "build-system"
+updated: "2026-03-29"
+---
+
+## Scope And Sources
+
+This document is based on the current dependency definitions and build wiring in:
+- CMake manifest and feature mapping in `CMakeLists.txt` and `cmake/vcpkg.cmake`
+- Dependency declarations in `vcpkg.json` and `vcpkg-configuration.json`
+- Legacy third-party source list in `cmake/thirdparty.json`
+- Plugin switches in `plugins/plugins.json`
+- Attached custom registry in `vcpkg-registry/`
+
+The goal is to manage third-party packages consistently through vcpkg, while using a custom registry for ports that are missing or require project-specific behavior.
+
+## 0) Package Classification: Adaptable vs Others
+
+### 0.1 Adaptable Packages (Directly Manageable Through vcpkg)
+
+| Package | Current State | Platform Notes | Adaptation Level |
+|---|---|---|---|
+| boost-container | Already in `vcpkg.json` | all | Done (maintain) |
+| boost-graph | Already in `vcpkg.json` | all | Done (maintain) |
+| sfmt | Already in `vcpkg.json` | all | Done (maintain) |
+| rapidjson | Already in `vcpkg.json` | all | Done (maintain) |
+| taskflow | Already in `vcpkg.json` | all | Done (maintain) |
+| sdl2 | Already in `vcpkg.json` | windows, osx, linux | Done (maintain) |
+| vulkan-memory-allocator | Already in `vcpkg.json` | all | Done (maintain) |
+| imgui (+ docking-experimental) | Already in `vcpkg.json` | all | Done (maintain) |
+| gtest | Already in `vcpkg.json` | all | Done (maintain) |
+| glslang | Already in `vcpkg.json` | all | Done (maintain) |
+| spirv-cross | Already in `vcpkg.json` | all | Done (maintain) |
+| directx-dxc | Already in `vcpkg.json` | windows | Done (maintain) |
+| assimp | vcpkg feature `editor` | windows, osx | Done (maintain) |
+| meshoptimizer | vcpkg feature `editor` | windows, osx | Done (maintain) |
+| stb | vcpkg feature `editor` | windows, osx | Done (maintain) |
+| imguizmo | vcpkg feature `editor` | windows, osx | Done (maintain) |
+| gklib | vcpkg feature `editor` | windows, osx | Adaptable (custom registry hardening needed) |
+| metis | vcpkg feature `editor` | windows, osx | Done (maintain) |
+| ispc-texcomp | vcpkg feature `editor` | windows, osx | Adaptable (custom registry hardening needed) |
+| bullet3 | vcpkg feature `bullet` | all | Done (maintain) |
+| recastnavigation | vcpkg feature `recast` | all | Done (maintain) |
+| tracy | vcpkg feature `tracy` | all | Done (maintain) |
+| freetype | vcpkg feature `freetype` | all | Done (maintain) |
+| lz4 | vcpkg feature `compression` | all | Done (maintain) |
+| zlib | transitive today | all | Adaptable (optional explicit pin if reproducibility required) |
+
+### 0.2 Other Packages (Not Yet In vcpkg Flow, Or Should Stay Outside)
+
+| Package / Dependency | Why It Is Not In Current vcpkg Flow | Recommendation |
+|---|---|---|
+| OpenXR (openxr-loader) | XR plugin uses legacy `FindOpenXR.cmake`, no vcpkg alias in `cmake/vcpkg.cmake` | Adapt to vcpkg in phase 2 |
+| Python runtime/dev (Python3::Python) | Resolved from host environment; version can drift across machines | Decide policy: keep system Python or pin with vcpkg/python3 |
+| Qt5 Widgets | Treated as host SDK/framework dependency for editor/tooling | Keep external for now; evaluate Qt via vcpkg only if full toolchain migration is desired |
+| Vulkan SDK (Vulkan::Vulkan) | Usually provided by OS SDK / LunarG SDK, not locked by vcpkg manifest | Keep external SDK dependency |
+| game-activity (Android) | Android NDK ecosystem package, outside vcpkg mainstream flow | Keep NDK-managed |
+| GLES/EGL libs | Platform graphics runtime libs, often system-provided | Keep system/SDK-managed |
+| ios-cmake | Build toolchain helper rather than runtime package | Keep as tool dependency |
+| crc32c in attached custom registry | Registry contains crc32c port but project currently references `crc32` package name and does not consume it in manifest | Reconcile naming and consume only if external crc32c is needed |
+
+## 1) Adaptation Tasks For Each Adaptable Package
+
+Task format:
+- T1: Align version strategy (overrides / baseline)
+- T2: Verify target mapping in `cmake/vcpkg.cmake`
+- T3: Validate platform guards and feature guards
+- T4: Add CI lock checks (configure + build matrix)
+
+| Package | Concrete Adaptation Tasks |
+|---|---|
+| boost-container | T1 pin retained; T2 verify `Boost::container`; T4 verify all desktop builds |
+| boost-graph | T1 pin retained; T2 verify `Boost::graph`; T4 verify all desktop builds |
+| sfmt | T1 keep version stable; T2 verify `sfmt::sfmt`; T4 test core module |
+| rapidjson | T1 keep stable; T2 verify `rapidjson` include target alias; T4 run serialization tests |
+| taskflow | T1 keep stable; T2 verify `Taskflow::Taskflow`; T4 run task scheduler tests |
+| sdl2 | T1 keep override; T2 verify `SDL2::SDL2` + `SDL2::SDL2main`; T3 validate non-mobile guards |
+| vulkan-memory-allocator | T1 keep override; T2 verify `GPUOpen::VulkanMemoryAllocator`; T4 run render backend tests |
+| imgui | T1 keep feature `docking-experimental`; T2 verify alias; T4 run editor UI build |
+| gtest | T1 keep stable; T2 verify `GTest::gtest`; T4 execute unit tests in CI |
+| glslang | T1 keep override; T2 verify component aliases; T4 run shader compile tests |
+| spirv-cross | T1 keep override; T2 verify six component package lookups; T4 run shader reflection tests |
+| directx-dxc | T1 windows-only lock; T2 verify `Microsoft::DirectXShaderCompiler`; T3 enforce WIN32 guard |
+| assimp | T1 feature-scoped version lock; T2 verify `assimp::assimp`; T3 editor-only guard |
+| meshoptimizer | T1 feature-scoped lock; T2 verify `meshoptimizer::meshoptimizer`; T3 editor-only guard |
+| stb | T1 ensure registry/default source is deterministic; T2 verify include alias creation; T3 editor-only guard |
+| imguizmo | T1 feature-scoped lock; T2 verify `imguizmo::imguizmo`; T3 editor-only guard |
+| gklib | T1 add/verify custom port baseline and version DB; T2 verify `gklib::gklib`; T3 editor-only + os support checks |
+| metis | T1 feature-scoped lock; T2 verify `metis::metis`; T3 editor-only + os support checks |
+| ispc-texcomp | T1 add/verify custom port baseline and version DB; T2 verify `ispc_texcomp::ispc_texcomp`; T3 editor-only + os support checks |
+| bullet3 | T1 feature-scoped lock; T2 verify all Bullet component targets; T4 run physics plugin tests |
+| recastnavigation | T1 feature-scoped lock; T2 verify RecastNavigation target set; T4 run navmesh plugin tests |
+| tracy | T1 keep override; T2 verify `Tracy::TracyClient`; T3 ensure compile define `TRACY_ENABLE` only when enabled |
+| freetype | T1 feature-scoped lock; T2 verify `Freetype::Freetype`; T4 run text rendering tests |
+| lz4 | T1 feature-scoped lock; T2 verify `lz4::lz4`; T4 run compression plugin tests |
+| zlib (optional explicit) | T1 add explicit dependency only if direct use required; T2 wire alias if promoted to direct package; T4 verify no duplicate linkage |
+
+## 2) Other Packages: Reasons And Adaptation Plan
+
+### OpenXR
+Reason:
+- XR code depends on `3rdParty::OpenXR`, but vcpkg bridge does not yet map this target.
+
+Adaptation plan:
+1. Add `openxr-loader` dependency under a new vcpkg feature (for example `xr`).
+2. Add `find_package(OpenXR CONFIG REQUIRED)` + alias `3rdParty::OpenXR` in `cmake/vcpkg.cmake`.
+3. Keep platform guard matching `SKY_BUILD_XR` behavior.
+4. Validate on at least Windows + one Unix-like target.
+
+### Python3
+Reason:
+- Current vcpkg mode uses `find_package(Python3 COMPONENTS Development REQUIRED)` from host environment.
+- This is less reproducible than manifest-pinned dependency resolution.
+
+Adaptation plan:
+1. Decide policy: reproducibility-first or host-Python-first.
+2. If reproducibility-first, add `python3` to dedicated feature and use imported targets from vcpkg prefix.
+3. Keep dynamic runtime loading strategy in plugin unchanged.
+4. Add CI check that embeds Python and loads plugin successfully.
+
+### Qt5
+Reason:
+- Qt tooling (moc/uic/rcc + platform plugins) is often managed as host SDK.
+- Migrating to vcpkg is feasible but high-touch and developer-environment sensitive.
+
+Adaptation plan:
+1. Short term: keep external SDK and document required version.
+2. Mid term: prototype vcpkg-based Qt on one platform in a branch.
+3. Long term: either fully migrate or formalize external-SDK standard with bootstrap checks.
+
+### Vulkan SDK
+Reason:
+- Vulkan loader/headers and validation ecosystem are usually handled by system SDK.
+
+Adaptation plan:
+1. Keep as external requirement.
+2. Add preconfigure diagnostics for missing Vulkan SDK to improve onboarding.
+
+### game-activity / GLES / ios-cmake
+Reason:
+- These are platform-ecosystem dependencies (Android/iOS/system graphics stack), not ideal as normal cross-platform vcpkg manifest items.
+
+Adaptation plan:
+1. Keep external toolchain/SDK ownership.
+2. Add platform-specific setup docs and configure-time checks.
+3. Add CI smoke jobs on relevant platform targets.
+
+### crc32c Custom Registry Entry (Attached Registry)
+Reason:
+- Attached custom registry includes `crc32c`, while project config registers package name `crc32`.
+- Current engine CRC32 implementation is internal and does not consume this package from `vcpkg.json`.
+
+Adaptation plan:
+1. Decide whether external crc32/c library is needed at all.
+2. If needed, normalize naming (`crc32c` preferred for clarity) across:
+   - custom registry package name
+   - `vcpkg-configuration.json` `packages` list
+   - `vcpkg.json` dependencies
+3. If not needed, remove stale registry entry from project config to reduce confusion.
+
+## 4) Execution Plan And Adaptation Roadmap
+
+### Phase A (Stabilize Existing vcpkg Flow, 1-2 days)
+1. Freeze dependency policy for current manifest features.
+2. Validate all existing vcpkg aliases and feature toggles.
+3. Add CI matrix: core, editor, bullet, recast, freetype, compression, tracy.
+4. Deliverable: stable reproducible builds across supported desktop targets.
+
+### Phase B (Custom Registry Governance, 1 day)
+1. Decide single source of truth for custom ports:
+   - external git registry only, or
+   - in-repo registry only.
+2. Reconcile custom package naming mismatch (`crc32` vs `crc32c`).
+3. Add checklist for port add/update process (format, x-add-version, baseline bump).
+4. Deliverable: deterministic custom registry consumption policy.
+
+### Phase C (Expand vcpkg Coverage, 2-4 days)
+1. Add `xr` feature and OpenXR package mapping.
+2. Decide and implement Python strategy (host vs pinned vcpkg).
+3. Add optional explicit zlib pin only if direct linkage is required.
+4. Deliverable: wider vcpkg ownership without breaking platform SDK assumptions.
+
+### Phase D (Platform And Tooling Hardening, ongoing)
+1. Add configure-time diagnostics for Qt, Vulkan SDK, Android NDK, iOS toolchain.
+2. Add developer bootstrap script for all non-vcpkg dependencies.
+3. Audit quarterly dependency updates and lockfile/baseline changes.
+4. Deliverable: lower onboarding cost and fewer environment-related failures.
+
+## Recommended Immediate Actions
+
+1. Fix the custom registry naming mismatch before further migration work.
+2. Add XR dependency migration (OpenXR) as the next concrete package adaptation.
+3. Decide Python dependency policy and codify it in vcpkg features.
+4. Keep Qt/Vulkan/system graphics dependencies external until a dedicated migration spike is approved.
diff --git a/vcpkg-configuration.json b/vcpkg-configuration.json
index 0fecf0ef..b76df75d 100644
--- a/vcpkg-configuration.json
+++ b/vcpkg-configuration.json
@@ -11,10 +11,8 @@
 			"repository": "https://github.com/Zhuyin-Graphics/vcpkg-registry",
 			"baseline": "303d3f22e71e31ded282ff6dfe103ed27723682c",
 			"packages": [
-				"sfmt",
-				"gklib",
-				"ispc-texcomp"
+				"crc32c"
 			]
 		}
 	]
-}
+}
\ No newline at end of file

From cf32d8b45a2232a98b5ed17c2de777b936c11fbe Mon Sep 17 00:00:00 2001
From: Yiwen Xue <15225434259xue@gmail.com>
Date: Sun, 29 Mar 2026 19:20:51 +0800
Subject: [PATCH 08/11] adapt some packages and update registry baseline, fix
 some build problems

---
 .gitignore                                  |   2 +
 CMakeLists.txt                              |  68 ++++++++++-
 README.md                                   |  38 +++++-
 cmake/options.cmake                         |   5 +
 cmake/thirdparty.cmake                      |  44 +++----
 docs/dependency/vcpkg-adaptation-roadmap.md | 126 ++++++++++----------
 vcpkg-configuration.json                    |  29 ++++-
 vcpkg.json                                  |  48 +-------
 8 files changed, 220 insertions(+), 140 deletions(-)

diff --git a/.gitignore b/.gitignore
index 9323d058..a08929b8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,3 +23,5 @@
 # generated PDF documentation
 /docs/pdf/
 .DS_Store
+/vcpkg/
+/.thirdparty/
\ No newline at end of file
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4ff41aef..70218e7a 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,5 +1,71 @@
 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.
@@ -7,7 +73,7 @@ cmake_minimum_required(VERSION 3.19)  # 3.19+ required for string(JSON ...)
 # but must be evaluated before project() because vcpkg runs at that point.
 # ---------------------------------------------------------------------------
 set(_sky_vcpkg_detected FALSE)
-if (SKY_USE_VCPKG)
+if (SKY_THIRDPARTY_MODE STREQUAL "LOCAL")
     set(_sky_vcpkg_detected TRUE)
 elseif (CMAKE_TOOLCHAIN_FILE)
     string(FIND "${CMAKE_TOOLCHAIN_FILE}" "vcpkg" _vcpkg_idx)
diff --git a/README.md b/README.md
index 8ecf0ee9..b404d381 100644
--- 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]
@@ -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
diff --git a/cmake/options.cmake b/cmake/options.cmake
index c8dfa656..94300aa4 100644
--- a/cmake/options.cmake
+++ b/cmake/options.cmake
@@ -1,5 +1,10 @@
 SET(3RD_PATH "" CACHE STRING "SkyEngine 3rd path")
 
+set(SKY_THIRDPARTY_MODE "${SKY_THIRDPARTY_MODE}" 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 "${SKY_THIRDPARTY_ROOT}" CACHE PATH "Local third-party root for downloads/installed/cache")
+
 if (3RD_PATH STREQUAL "" AND EXISTS "${ENGINE_ROOT}/build_3rd/thirdparty_cache.cmake")
     include("${ENGINE_ROOT}/build_3rd/thirdparty_cache.cmake")
 endif ()
diff --git a/cmake/thirdparty.cmake b/cmake/thirdparty.cmake
index a2b6a001..131573a3 100644
--- a/cmake/thirdparty.cmake
+++ b/cmake/thirdparty.cmake
@@ -1,33 +1,16 @@
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${ENGINE_ROOT}/cmake/thirdparty)
 include(${ENGINE_ROOT}/cmake/thirdparty_helpers.cmake)
 
-## vcpkg booststrap
-
-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")
-list(APPEND VCPKG_FEATURE_FLAGS manifests)
-
-# detect platform
-# TODO: try to adapt to more platforms
-if(WIN32)
-  set(VCPKG_TARGET_TRIPLET x64-windows)
-elseif(UNIX)
-  set(VCPKG_TARGET_TRIPLET x64-linux)
-endif()
-
 # ---------------------------------------------------------------------------
-# Detect which mode to use:
-#   1. vcpkg   – when CMAKE_TOOLCHAIN_FILE points at the vcpkg toolchain
-#   2. legacy  – when 3RD_PATH is set (pre-built tree from python/third_party.py)
+# Detect which mode to use (configured by SKY_THIRDPARTY_MODE in top-level CMake):
+#   1. LOCAL    – vcpkg manifest mode (download/build/cache under SKY_THIRDPARTY_ROOT)
+#   2. PREBUILT – pre-built tree from python/third_party.py via 3RD_PATH
 # ---------------------------------------------------------------------------
-if (DEFINED VCPKG_TOOLCHAIN OR SKY_USE_VCPKG)
-    message(STATUS "[SkyEngine] Using vcpkg for third-party dependencies")
+if (SKY_THIRDPARTY_MODE STREQUAL "LOCAL")
+    message(STATUS "[SkyEngine] Third-party mode: LOCAL (vcpkg)")
+    message(STATUS "[SkyEngine] Third-party root: ${SKY_THIRDPARTY_ROOT}")
     include(${ENGINE_ROOT}/cmake/vcpkg.cmake)
-elseif(EXISTS ${3RD_PATH})
+elseif (SKY_THIRDPARTY_MODE STREQUAL "PREBUILT" AND EXISTS ${3RD_PATH})
     function(sky_find_3rd)
         cmake_parse_arguments(TMP
             ""
@@ -104,11 +87,14 @@ elseif(EXISTS ${3RD_PATH})
         sky_find_3rd(TARGET metis         DIR metis)
         sky_find_3rd(TARGET ImGuizmo      DIR ImGuizmo)
     endif ()
-else()
+elseif (SKY_THIRDPARTY_MODE STREQUAL "PREBUILT")
     message(FATAL_ERROR
-        "No third-party source configured.\n"
-        "Either:\n"
-        "  1. Use vcpkg: cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake\n"
-        "  2. Use pre-built: cmake -B build -D3RD_PATH=<path-to-prebuilt-3rdparty>\n"
+        "Third-party mode is PREBUILT but 3RD_PATH is not available.\n"
+        "Use one of:\n"
+        "  1. Build prebuilt third-party tree: python3 python/third_party.py -p <platform>\n"
+        "  2. Configure 3RD_PATH explicitly: cmake -B build -DSKY_THIRDPARTY_MODE=PREBUILT -D3RD_PATH=<path>\n"
+        "  3. Switch mode: cmake -B build -DSKY_THIRDPARTY_MODE=LOCAL\n"
     )
+else()
+    message(FATAL_ERROR "Unsupported SKY_THIRDPARTY_MODE='${SKY_THIRDPARTY_MODE}'")
 endif()
diff --git a/docs/dependency/vcpkg-adaptation-roadmap.md b/docs/dependency/vcpkg-adaptation-roadmap.md
index 501f1327..30e20ce7 100644
--- a/docs/dependency/vcpkg-adaptation-roadmap.md
+++ b/docs/dependency/vcpkg-adaptation-roadmap.md
@@ -20,46 +20,46 @@ The goal is to manage third-party packages consistently through vcpkg, while usi
 
 ### 0.1 Adaptable Packages (Directly Manageable Through vcpkg)
 
-| Package | Current State | Platform Notes | Adaptation Level |
-|---|---|---|---|
-| boost-container | Already in `vcpkg.json` | all | Done (maintain) |
-| boost-graph | Already in `vcpkg.json` | all | Done (maintain) |
-| sfmt | Already in `vcpkg.json` | all | Done (maintain) |
-| rapidjson | Already in `vcpkg.json` | all | Done (maintain) |
-| taskflow | Already in `vcpkg.json` | all | Done (maintain) |
-| sdl2 | Already in `vcpkg.json` | windows, osx, linux | Done (maintain) |
-| vulkan-memory-allocator | Already in `vcpkg.json` | all | Done (maintain) |
-| imgui (+ docking-experimental) | Already in `vcpkg.json` | all | Done (maintain) |
-| gtest | Already in `vcpkg.json` | all | Done (maintain) |
-| glslang | Already in `vcpkg.json` | all | Done (maintain) |
-| spirv-cross | Already in `vcpkg.json` | all | Done (maintain) |
-| directx-dxc | Already in `vcpkg.json` | windows | Done (maintain) |
-| assimp | vcpkg feature `editor` | windows, osx | Done (maintain) |
-| meshoptimizer | vcpkg feature `editor` | windows, osx | Done (maintain) |
-| stb | vcpkg feature `editor` | windows, osx | Done (maintain) |
-| imguizmo | vcpkg feature `editor` | windows, osx | Done (maintain) |
-| gklib | vcpkg feature `editor` | windows, osx | Adaptable (custom registry hardening needed) |
-| metis | vcpkg feature `editor` | windows, osx | Done (maintain) |
-| ispc-texcomp | vcpkg feature `editor` | windows, osx | Adaptable (custom registry hardening needed) |
-| bullet3 | vcpkg feature `bullet` | all | Done (maintain) |
-| recastnavigation | vcpkg feature `recast` | all | Done (maintain) |
-| tracy | vcpkg feature `tracy` | all | Done (maintain) |
-| freetype | vcpkg feature `freetype` | all | Done (maintain) |
-| lz4 | vcpkg feature `compression` | all | Done (maintain) |
-| zlib | transitive today | all | Adaptable (optional explicit pin if reproducibility required) |
+| Package                        | Current State               | Platform Notes      | Adaptation Level                                              |
+| ------------------------------ | --------------------------- | ------------------- | ------------------------------------------------------------- |
+| boost-container                | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| boost-graph                    | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| sfmt                           | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| rapidjson                      | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| taskflow                       | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| sdl2                           | Already in `vcpkg.json`     | windows, osx, linux | Done (maintain)                                               |
+| vulkan-memory-allocator        | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| imgui (+ docking-experimental) | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| gtest                          | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| glslang                        | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| spirv-cross                    | Already in `vcpkg.json`     | all                 | Done (maintain)                                               |
+| directx-dxc                    | Already in `vcpkg.json`     | windows             | Done (maintain)                                               |
+| assimp                         | vcpkg feature `editor`      | windows, osx        | Done (maintain)                                               |
+| meshoptimizer                  | vcpkg feature `editor`      | windows, osx        | Done (maintain)                                               |
+| stb                            | vcpkg feature `editor`      | windows, osx        | Done (maintain)                                               |
+| imguizmo                       | vcpkg feature `editor`      | windows, osx        | Done (maintain)                                               |
+| gklib                          | vcpkg feature `editor`      | windows, osx        | Adaptable (custom registry hardening needed)                  |
+| metis                          | vcpkg feature `editor`      | windows, osx        | Done (maintain)                                               |
+| ispc-texcomp                   | vcpkg feature `editor`      | windows, osx        | Adaptable (custom registry hardening needed)                  |
+| bullet3                        | vcpkg feature `bullet`      | all                 | Done (maintain)                                               |
+| recastnavigation               | vcpkg feature `recast`      | all                 | Done (maintain)                                               |
+| tracy                          | vcpkg feature `tracy`       | all                 | Done (maintain)                                               |
+| freetype                       | vcpkg feature `freetype`    | all                 | Done (maintain)                                               |
+| lz4                            | vcpkg feature `compression` | all                 | Done (maintain)                                               |
+| zlib                           | transitive today            | all                 | Adaptable (optional explicit pin if reproducibility required) |
 
 ### 0.2 Other Packages (Not Yet In vcpkg Flow, Or Should Stay Outside)
 
-| Package / Dependency | Why It Is Not In Current vcpkg Flow | Recommendation |
-|---|---|---|
-| OpenXR (openxr-loader) | XR plugin uses legacy `FindOpenXR.cmake`, no vcpkg alias in `cmake/vcpkg.cmake` | Adapt to vcpkg in phase 2 |
-| Python runtime/dev (Python3::Python) | Resolved from host environment; version can drift across machines | Decide policy: keep system Python or pin with vcpkg/python3 |
-| Qt5 Widgets | Treated as host SDK/framework dependency for editor/tooling | Keep external for now; evaluate Qt via vcpkg only if full toolchain migration is desired |
-| Vulkan SDK (Vulkan::Vulkan) | Usually provided by OS SDK / LunarG SDK, not locked by vcpkg manifest | Keep external SDK dependency |
-| game-activity (Android) | Android NDK ecosystem package, outside vcpkg mainstream flow | Keep NDK-managed |
-| GLES/EGL libs | Platform graphics runtime libs, often system-provided | Keep system/SDK-managed |
-| ios-cmake | Build toolchain helper rather than runtime package | Keep as tool dependency |
-| crc32c in attached custom registry | Registry contains crc32c port but project currently references `crc32` package name and does not consume it in manifest | Reconcile naming and consume only if external crc32c is needed |
+| Package / Dependency                 | Why It Is Not In Current vcpkg Flow                                                                                     | Recommendation                                                                           |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| OpenXR (openxr-loader)               | XR plugin uses legacy `FindOpenXR.cmake`, no vcpkg alias in `cmake/vcpkg.cmake`                                         | Adapt to vcpkg in phase 2                                                                |
+| Python runtime/dev (Python3::Python) | Resolved from host environment; version can drift across machines                                                       | Decide policy: keep system Python or pin with vcpkg/python3                              |
+| Qt5 Widgets                          | Treated as host SDK/framework dependency for editor/tooling                                                             | Keep external for now; evaluate Qt via vcpkg only if full toolchain migration is desired |
+| Vulkan SDK (Vulkan::Vulkan)          | Usually provided by OS SDK / LunarG SDK, not locked by vcpkg manifest                                                   | Keep external SDK dependency                                                             |
+| game-activity (Android)              | Android NDK ecosystem package, outside vcpkg mainstream flow                                                            | Keep NDK-managed                                                                         |
+| GLES/EGL libs                        | Platform graphics runtime libs, often system-provided                                                                   | Keep system/SDK-managed                                                                  |
+| ios-cmake                            | Build toolchain helper rather than runtime package                                                                      | Keep as tool dependency                                                                  |
+| crc32c in attached custom registry   | Registry contains crc32c port but project currently references `crc32` package name and does not consume it in manifest | Reconcile naming and consume only if external crc32c is needed                           |
 
 ## 1) Adaptation Tasks For Each Adaptable Package
 
@@ -69,32 +69,32 @@ Task format:
 - T3: Validate platform guards and feature guards
 - T4: Add CI lock checks (configure + build matrix)
 
-| Package | Concrete Adaptation Tasks |
-|---|---|
-| boost-container | T1 pin retained; T2 verify `Boost::container`; T4 verify all desktop builds |
-| boost-graph | T1 pin retained; T2 verify `Boost::graph`; T4 verify all desktop builds |
-| sfmt | T1 keep version stable; T2 verify `sfmt::sfmt`; T4 test core module |
-| rapidjson | T1 keep stable; T2 verify `rapidjson` include target alias; T4 run serialization tests |
-| taskflow | T1 keep stable; T2 verify `Taskflow::Taskflow`; T4 run task scheduler tests |
-| sdl2 | T1 keep override; T2 verify `SDL2::SDL2` + `SDL2::SDL2main`; T3 validate non-mobile guards |
-| vulkan-memory-allocator | T1 keep override; T2 verify `GPUOpen::VulkanMemoryAllocator`; T4 run render backend tests |
-| imgui | T1 keep feature `docking-experimental`; T2 verify alias; T4 run editor UI build |
-| gtest | T1 keep stable; T2 verify `GTest::gtest`; T4 execute unit tests in CI |
-| glslang | T1 keep override; T2 verify component aliases; T4 run shader compile tests |
-| spirv-cross | T1 keep override; T2 verify six component package lookups; T4 run shader reflection tests |
-| directx-dxc | T1 windows-only lock; T2 verify `Microsoft::DirectXShaderCompiler`; T3 enforce WIN32 guard |
-| assimp | T1 feature-scoped version lock; T2 verify `assimp::assimp`; T3 editor-only guard |
-| meshoptimizer | T1 feature-scoped lock; T2 verify `meshoptimizer::meshoptimizer`; T3 editor-only guard |
-| stb | T1 ensure registry/default source is deterministic; T2 verify include alias creation; T3 editor-only guard |
-| imguizmo | T1 feature-scoped lock; T2 verify `imguizmo::imguizmo`; T3 editor-only guard |
-| gklib | T1 add/verify custom port baseline and version DB; T2 verify `gklib::gklib`; T3 editor-only + os support checks |
-| metis | T1 feature-scoped lock; T2 verify `metis::metis`; T3 editor-only + os support checks |
-| ispc-texcomp | T1 add/verify custom port baseline and version DB; T2 verify `ispc_texcomp::ispc_texcomp`; T3 editor-only + os support checks |
-| bullet3 | T1 feature-scoped lock; T2 verify all Bullet component targets; T4 run physics plugin tests |
-| recastnavigation | T1 feature-scoped lock; T2 verify RecastNavigation target set; T4 run navmesh plugin tests |
-| tracy | T1 keep override; T2 verify `Tracy::TracyClient`; T3 ensure compile define `TRACY_ENABLE` only when enabled |
-| freetype | T1 feature-scoped lock; T2 verify `Freetype::Freetype`; T4 run text rendering tests |
-| lz4 | T1 feature-scoped lock; T2 verify `lz4::lz4`; T4 run compression plugin tests |
+| Package                  | Concrete Adaptation Tasks                                                                                                           |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| boost-container          | T1 pin retained; T2 verify `Boost::container`; T4 verify all desktop builds                                                         |
+| boost-graph              | T1 pin retained; T2 verify `Boost::graph`; T4 verify all desktop builds                                                             |
+| sfmt                     | T1 keep version stable; T2 verify `sfmt::sfmt`; T4 test core module                                                                 |
+| rapidjson                | T1 keep stable; T2 verify `rapidjson` include target alias; T4 run serialization tests                                              |
+| taskflow                 | T1 keep stable; T2 verify `Taskflow::Taskflow`; T4 run task scheduler tests                                                         |
+| sdl2                     | T1 keep override; T2 verify `SDL2::SDL2` + `SDL2::SDL2main`; T3 validate non-mobile guards                                          |
+| vulkan-memory-allocator  | T1 keep override; T2 verify `GPUOpen::VulkanMemoryAllocator`; T4 run render backend tests                                           |
+| imgui                    | T1 keep feature `docking-experimental`; T2 verify alias; T4 run editor UI build                                                     |
+| gtest                    | T1 keep stable; T2 verify `GTest::gtest`; T4 execute unit tests in CI                                                               |
+| glslang                  | T1 keep override; T2 verify component aliases; T4 run shader compile tests                                                          |
+| spirv-cross              | T1 keep override; T2 verify six component package lookups; T4 run shader reflection tests                                           |
+| directx-dxc              | T1 windows-only lock; T2 verify `Microsoft::DirectXShaderCompiler`; T3 enforce WIN32 guard                                          |
+| assimp                   | T1 feature-scoped version lock; T2 verify `assimp::assimp`; T3 editor-only guard                                                    |
+| meshoptimizer            | T1 feature-scoped lock; T2 verify `meshoptimizer::meshoptimizer`; T3 editor-only guard                                              |
+| stb                      | T1 ensure registry/default source is deterministic; T2 verify include alias creation; T3 editor-only guard                          |
+| imguizmo                 | T1 feature-scoped lock; T2 verify `imguizmo::imguizmo`; T3 editor-only guard                                                        |
+| gklib                    | T1 add/verify custom port baseline and version DB; T2 verify `gklib::gklib`; T3 editor-only + os support checks                     |
+| metis                    | T1 feature-scoped lock; T2 verify `metis::metis`; T3 editor-only + os support checks                                                |
+| ispc-texcomp             | T1 add/verify custom port baseline and version DB; T2 verify `ispc_texcomp::ispc_texcomp`; T3 editor-only + os support checks       |
+| bullet3                  | T1 feature-scoped lock; T2 verify all Bullet component targets; T4 run physics plugin tests                                         |
+| recastnavigation         | T1 feature-scoped lock; T2 verify RecastNavigation target set; T4 run navmesh plugin tests                                          |
+| tracy                    | T1 keep override; T2 verify `Tracy::TracyClient`; T3 ensure compile define `TRACY_ENABLE` only when enabled                         |
+| freetype                 | T1 feature-scoped lock; T2 verify `Freetype::Freetype`; T4 run text rendering tests                                                 |
+| lz4                      | T1 feature-scoped lock; T2 verify `lz4::lz4`; T4 run compression plugin tests                                                       |
 | zlib (optional explicit) | T1 add explicit dependency only if direct use required; T2 wire alias if promoted to direct package; T4 verify no duplicate linkage |
 
 ## 2) Other Packages: Reasons And Adaptation Plan
diff --git a/vcpkg-configuration.json b/vcpkg-configuration.json
index b76df75d..bb9d0600 100644
--- a/vcpkg-configuration.json
+++ b/vcpkg-configuration.json
@@ -9,9 +9,34 @@
 		{
 			"kind": "git",
 			"repository": "https://github.com/Zhuyin-Graphics/vcpkg-registry",
-			"baseline": "303d3f22e71e31ded282ff6dfe103ed27723682c",
+			"baseline": "e8c9c2888b269152ee7bcf9eca74258b6c581025",
 			"packages": [
-				"crc32c"
+				"assimp",
+				"boost-container",
+				"boost-graph",
+				"bullet3",
+				"crc32c",
+				"directx-dxc",
+				"freetype",
+				"gklib",
+				"glslang",
+				"gtest",
+				"imgui",
+				"imguizmo",
+				"ispc-texcomp",
+				"lz4",
+				"meshoptimizer",
+				"metis",
+				"rapidjson",
+				"recastnavigation",
+				"sdl2",
+				"sfmt",
+				"spirv-cross",
+				"stb",
+				"taskflow",
+				"tracy",
+				"vulkan-memory-allocator",
+				"zlib"
 			]
 		}
 	]
diff --git a/vcpkg.json b/vcpkg.json
index d9fcc6fd..fa34ef4e 100644
--- a/vcpkg.json
+++ b/vcpkg.json
@@ -4,14 +4,8 @@
 	"version-string": "0.1.0",
 	"description": "SkyEngine - A cross-platform game engine",
 	"dependencies": [
-		{
-			"name": "boost-container",
-			"version>=": "1.88.0"
-		},
-		{
-			"name": "boost-graph",
-			"version>=": "1.88.0"
-		},
+		"boost-container",
+		"boost-graph",
 		"sfmt",
 		"rapidjson",
 		"taskflow",
@@ -98,39 +92,5 @@
 				"lz4"
 			]
 		}
-	},
-	"overrides": [
-		{
-			"name": "boost-container",
-			"version": "1.88.0"
-		},
-		{
-			"name": "boost-graph",
-			"version": "1.88.0"
-		},
-		{
-			"name": "sdl2",
-			"version": "2.32.6"
-		},
-		{
-			"name": "taskflow",
-			"version": "3.7.0"
-		},
-		{
-			"name": "vulkan-memory-allocator",
-			"version": "3.2.1"
-		},
-		{
-			"name": "glslang",
-			"version": "15.3.0"
-		},
-		{
-			"name": "spirv-cross",
-			"version": "1.4.313.0"
-		},
-		{
-			"name": "tracy",
-			"version": "0.11.1"
-		}
-	]
-}
+	}
+}
\ No newline at end of file

From c52984c2f427754e7f051229a6af724ec9ad276d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 29 Mar 2026 12:14:06 +0000
Subject: [PATCH 09/11] Initial plan


From d566fd382adb85411af3f5cd7fe41d4075dc8529 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 29 Mar 2026 12:18:16 +0000
Subject: [PATCH 10/11] docs: add build system refactor design document

Agent-Logs-Url: https://github.com/bluesky013/SkyEngine/sessions/5585620d-c615-4f67-b174-bef0bb818c7e

Co-authored-by: yiwenxue <24495793+yiwenxue@users.noreply.github.com>
---
 docs/build-system-refactor.md | 552 ++++++++++++++++++++++++++++++++++
 1 file changed, 552 insertions(+)
 create mode 100644 docs/build-system-refactor.md

diff --git a/docs/build-system-refactor.md b/docs/build-system-refactor.md
new file mode 100644
index 00000000..321bcf9b
--- /dev/null
+++ b/docs/build-system-refactor.md
@@ -0,0 +1,552 @@
+---
+title: "SkyEngine Build System Refactor"
+description: "Design document for a unified, dual-mode build system supporting local vcpkg builds and CI-published prebuilds."
+module: "build-system"
+updated: "2026-03-29"
+---
+
+## 1. Goals
+
+| # | Goal |
+|---|------|
+| 1 | **Dual-mode support** – developers can choose either a *local build* (vcpkg compiles dependencies from source) or a *prebuild* mode (pre-compiled artifacts published by CI are downloaded automatically). |
+| 2 | **vcpkg-first** – local mode exclusively uses vcpkg for version pinning, triplet selection, and feature gating; the legacy `python/third_party.py` / `3RD_PATH` path is retired. |
+| 3 | **Transparent vcpkg discovery** – check for a global vcpkg installation first; fall back to cloning and bootstrapping a local copy only when no global instance is found. |
+| 4 | **Prebuilds via CI/CD** – artifacts are built per-platform per-triplet in CI, published to a release/artifact store, and downloaded on demand during the engine CMake configure step. |
+| 5 | **Simplicity** – the build system should be expressed in ≤ 5 CMake files with clear, single-responsibility roles and no duplicated logic. |
+| 6 | **Full triplet coverage** – every declared dependency must build cleanly for all six supported triplets; a CMake helper selects the correct triplet automatically based on host/target platform. |
+
+---
+
+## 2. Current State Summary
+
+### 2.1 File Layout
+
+```
+CMakeLists.txt                  top-level: vcpkg feature mapping + project()
+cmake/
+  options.cmake                 SKY_BUILD_* option declarations
+  configuration.cmake           platform compile-flag setup
+  thirdparty.cmake              mode dispatch: vcpkg | 3RD_PATH | fatal error
+  vcpkg.cmake                   vcpkg mode: find_package + 3rdParty:: alias targets
+  vcpkg_bootstrap.cmake         clone/pin microsoft/vcpkg locally
+  thirdparty_helpers.cmake      shared helpers (sky_vcpkg_alias, etc.)
+  thirdparty/                   legacy Find*.cmake modules (3RD_PATH mode)
+  thirdparty.json               package list for python/third_party.py
+python/
+  third_party.py                legacy builder: git-clone + cmake + archive
+triplets/
+  arm64-android.cmake
+  arm64-ios.cmake
+  arm64-osx.cmake
+  x64-linux.cmake
+  x64-osx.cmake
+  x64-windows-static.cmake
+vcpkg.json                      manifest with version pins and feature gates
+vcpkg-configuration.json        registry sources (microsoft/vcpkg + custom)
+```
+
+### 2.2 Known Pain Points
+
+| Pain Point | Detail |
+|---|---|
+| Two divergent paths | vcpkg mode and 3RD_PATH mode share no code and can silently diverge in what gets linked. |
+| `vcpkg_bootstrap.cmake` always clones | Does not probe `VCPKG_ROOT` or `PATH` before initiating a network clone. |
+| Triplet auto-detection is incomplete | `thirdparty.cmake` only maps `WIN32 → x64-windows` and `UNIX → x64-linux`; macOS ARM, iOS, Android are never set automatically. |
+| No prebuild download path | Prebuild archives exist on disk (python script creates them) but there is no CMake-side logic to fetch them from a remote store. |
+| Legacy mode can diverge | `python/third_party.py` clones specific git tags; package versions can drift from vcpkg-pinned versions. |
+| `x64-windows` vs `x64-windows-static` mismatch | CI sets `VCPKG_DEFAULT_TRIPLET=x64-windows-static`, but `thirdparty.cmake` picks `x64-windows` on Windows (a different triplet). |
+
+---
+
+## 3. Proposed Architecture
+
+### 3.1 Overview
+
+```
+CMakeLists.txt
+└── cmake/sky_build_mode.cmake      ← NEW: single entry point, picks mode
+    ├── [mode = local-vcpkg]
+    │   ├── cmake/sky_vcpkg_find.cmake   ← NEW: global vcpkg probe / bootstrap
+    │   ├── cmake/sky_triplet.cmake      ← NEW: triplet auto-selection
+    │   └── cmake/sky_packages.cmake     ← RENAMED from vcpkg.cmake
+    └── [mode = prebuild]
+        └── cmake/sky_prebuild.cmake     ← NEW: download + unpack prebuilts
+```
+
+All downstream engine code continues to consume `3rdParty::<name>` interface targets regardless of mode; only the two leaf cmake files differ.
+
+### 3.2 Mode Selection
+
+A single CMake option controls the mode:
+
+```cmake
+# cmake/options.cmake  (new addition)
+option(SKY_PREBUILD_MODE "Use pre-compiled third-party artifacts instead of building from source" OFF)
+```
+
+When `SKY_PREBUILD_MODE=ON`:
+
+1. CMake reads the artifact metadata from `cmake/prebuild_manifest.json` (see §5).
+2. Downloads the archive for the current triplet if not already present.
+3. Unpacks to `${CMAKE_BINARY_DIR}/_prebuilts/<triplet>/`.
+4. Sets `CMAKE_PREFIX_PATH` so that `find_package` resolves against the unpacked tree.
+5. Includes `cmake/sky_packages.cmake` as usual — all `find_package` + alias calls are identical to local mode.
+
+When `SKY_PREBUILD_MODE=OFF` (default):
+
+1. Runs vcpkg discovery and optional bootstrap.
+2. Sets `CMAKE_TOOLCHAIN_FILE` to the located vcpkg toolchain.
+3. vcpkg manifest mode installs exactly the packages listed in `vcpkg.json`.
+
+---
+
+## 4. vcpkg Discovery and Bootstrap
+
+### 4.1 Search Order (`cmake/sky_vcpkg_find.cmake`)
+
+```
+1. VCPKG_ROOT environment variable (user-managed global install)
+2. CMAKE_TOOLCHAIN_FILE already pointing at vcpkg (passed on command line)
+3. Well-known system locations:
+     Windows : %LOCALAPPDATA%\vcpkg  |  C:\vcpkg
+     macOS/Linux : $HOME/.vcpkg  |  /usr/local/vcpkg  |  /opt/vcpkg
+4. Local clone at ${CMAKE_SOURCE_DIR}/vcpkg  (created by bootstrap if needed)
+```
+
+Only step 4 triggers a network operation.  The existing `cmake/vcpkg_bootstrap.cmake` is refactored into a private sub-function called exclusively from step 4.
+
+```cmake
+# cmake/sky_vcpkg_find.cmake  (pseudocode)
+
+function(sky_find_or_bootstrap_vcpkg OUT_TOOLCHAIN)
+    # Steps 1-3: probe candidates
+    foreach(candidate IN LISTS _sky_vcpkg_candidates)
+        if(EXISTS "${candidate}/scripts/buildsystems/vcpkg.cmake")
+            set(${OUT_TOOLCHAIN} "${candidate}/scripts/buildsystems/vcpkg.cmake" PARENT_SCOPE)
+            message(STATUS "[SkyEngine] Found vcpkg at ${candidate}")
+            return()
+        endif()
+    endforeach()
+
+    # Step 4: bootstrap local clone
+    message(STATUS "[SkyEngine] No global vcpkg found – bootstrapping local copy")
+    _sky_vcpkg_bootstrap()  # clone + pin + compile vcpkg binary
+    set(${OUT_TOOLCHAIN} "${CMAKE_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake" PARENT_SCOPE)
+endfunction()
+```
+
+The bootstrap function retains the git-pin-to-baseline logic from the existing `vcpkg_bootstrap.cmake`, but pins the commit from `vcpkg-configuration.json`'s `default-registry.baseline` automatically, removing the separate hardcoded SHA.
+
+### 4.2 Usage in `CMakeLists.txt`
+
+```cmake
+# Must run before project()
+if(NOT SKY_PREBUILD_MODE)
+    include(cmake/sky_vcpkg_find.cmake)
+    sky_find_or_bootstrap_vcpkg(_sky_toolchain)
+    set(CMAKE_TOOLCHAIN_FILE "${_sky_toolchain}" CACHE STRING "" FORCE)
+endif()
+
+set(VCPKG_OVERLAY_TRIPLETS "${CMAKE_CURRENT_SOURCE_DIR}/triplets" CACHE STRING "" FORCE)
+# ... feature mapping ...
+project(SkyEngine)
+```
+
+---
+
+## 5. Triplet Selection
+
+### 5.1 Current Triplets
+
+| Triplet file | OS | Arch | CRT | Library |
+|---|---|---|---|---|
+| `x64-windows-static` | Windows | x64 | static | static |
+| `x64-linux` | Linux | x64 | dynamic | static |
+| `x64-osx` | macOS | x86_64 | dynamic | static |
+| `arm64-osx` | macOS | arm64 | dynamic | static |
+| `arm64-ios` | iOS | arm64 | dynamic | static |
+| `arm64-android` | Android | arm64 | dynamic | static |
+
+### 5.2 Triplet Issues
+
+| Issue | Detail |
+|---|---|
+| No `x64-windows` triplet | CI sets `x64-windows-static` but old thirdparty.cmake detected `x64-windows`. Should be unified to `x64-windows-static` on all paths. |
+| `x64-linux` missing `VCPKG_BUILD_TYPE` | Should set `VCPKG_BUILD_TYPE release` for CI prebuilts (release-only) or leave blank for dev (debug+release). |
+| `arm64-android` missing toolchain vars | Does not set `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` pointing to NDK toolchain, which causes failures for some packages. |
+| No `x86_64-android` triplet | Some older Android devices still use x86_64; add if XR or broad device support is required. |
+
+### 5.3 Auto-Selection Logic (`cmake/sky_triplet.cmake`)
+
+```cmake
+# cmake/sky_triplet.cmake
+
+function(sky_select_triplet OUT_TRIPLET)
+    # Cross-compile targets override host detection
+    if(CMAKE_SYSTEM_NAME STREQUAL "Android")
+        set(_triplet "arm64-android")
+    elseif(CMAKE_SYSTEM_NAME STREQUAL "iOS")
+        set(_triplet "arm64-ios")
+    elseif(WIN32)
+        set(_triplet "x64-windows-static")
+    elseif(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+        # Apple Silicon vs Intel
+        if(CMAKE_SYSTEM_PROCESSOR MATCHES "arm64|aarch64" OR
+           CMAKE_OSX_ARCHITECTURES STREQUAL "arm64")
+            set(_triplet "arm64-osx")
+        else()
+            set(_triplet "x64-osx")
+        endif()
+    elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+        set(_triplet "x64-linux")
+    else()
+        message(FATAL_ERROR "[SkyEngine] Unsupported platform: ${CMAKE_SYSTEM_NAME}")
+    endif()
+
+    set(${OUT_TRIPLET} "${_triplet}" PARENT_SCOPE)
+    message(STATUS "[SkyEngine] Auto-selected triplet: ${_triplet}")
+endfunction()
+```
+
+This replaces the ad-hoc `if(WIN32)` / `elseif(UNIX)` block in `thirdparty.cmake` and is called from `CMakeLists.txt` before `project()`.
+
+### 5.4 Triplet Fixes Required
+
+| Triplet | Required Change |
+|---|---|
+| `arm64-android.cmake` | Add `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` pointing to `$ENV{ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake`; set `VCPKG_CMAKE_CONFIGURE_OPTIONS -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-31`. |
+| `x64-linux.cmake` | Add `set(VCPKG_BUILD_TYPE release)` when building release-only CI artifacts (controlled by a `VCPKG_RELEASE_ONLY` overlay or CI env var). |
+| `arm64-ios.cmake` | Verify `VCPKG_OSX_DEPLOYMENT_TARGET 13.0` is honored by all port portfiles; add note about required Xcode version. |
+
+---
+
+## 6. Package Compatibility Matrix
+
+The table below maps each package against each triplet and marks known blockers.
+
+| Package | x64-win-static | x64-linux | x64-osx | arm64-osx | arm64-ios | arm64-android |
+|---|---|---|---|---|---|---|
+| boost-container | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| boost-graph | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| sfmt | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| rapidjson | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| taskflow | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| sdl2 | ✅ | ✅ | ✅ | ✅ | ❌ (no SDL on iOS) | ❌ (no SDL on Android) |
+| vulkan-memory-allocator | ✅ | ✅ | ✅ | ✅ | ⚠️ MoltenVK only | ✅ |
+| imgui | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| glslang | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| spirv-cross | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| directx-dxc | ✅ | ❌ (WIN32 only) | ❌ (WIN32 only) | ❌ | ❌ | ❌ |
+| gtest | ✅ | ✅ | ✅ | ✅ | ⚠️ no runner | ⚠️ no runner |
+| lz4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| freetype | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tracy | ✅ | ✅ | ✅ | ✅ | ⚠️ limited | ⚠️ limited |
+| bullet3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| recastnavigation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| assimp (editor) | ✅ | ❌ (editor=win/osx) | ✅ | ✅ | ❌ | ❌ |
+| meshoptimizer (editor) | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
+| stb (editor) | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
+| imguizmo (editor) | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
+| gklib (editor) | ✅ | ❌ | ✅ | ⚠️ custom port | ❌ | ❌ |
+| metis (editor) | ✅ | ❌ | ✅ | ⚠️ custom port | ❌ | ❌ |
+| ispc-texcomp (editor) | ✅ | ❌ | ✅ | ⚠️ ISPC compiler needed | ❌ | ❌ |
+
+Legend: ✅ known-good | ⚠️ needs verification or minor fix | ❌ unsupported by design
+
+**Rule for platform guards in `vcpkg.json`:**
+
+```json
+{ "name": "sdl2",     "platform": "windows | osx | linux" }
+{ "name": "directx-dxc", "platform": "windows" }
+```
+
+Editor feature should restrict its dependencies to `"platform": "windows | osx"` as it does today; this is correct.
+
+---
+
+## 7. Prebuild Mode: CI/CD Pipeline and Download
+
+### 7.1 Artifact Naming Convention
+
+Each CI run that publishes prebuilts produces one archive per triplet:
+
+```
+skyengine-prebuilts-<triplet>-<vcpkg_baseline_short>.tar.zst
+```
+
+Example: `skyengine-prebuilts-x64-windows-static-c3867e71.tar.zst`
+
+The archive is a flat install tree matching the vcpkg installed layout:
+
+```
+<triplet>/
+  include/
+  lib/
+  share/       ← cmake config files live here
+  bin/         ← DLLs / dylibs (when LIBRARY_LINKAGE=dynamic)
+  debug/
+    lib/
+    bin/
+```
+
+### 7.2 Prebuild Manifest (`cmake/prebuild_manifest.json`)
+
+```json
+{
+  "vcpkg_baseline": "c3867e714dd3a51c272826eea77267876517ed99",  // microsoft/vcpkg tag 2026.03.18
+  "triplets": {
+    "x64-windows-static": {
+      "url": "https://github.com/bluesky013/SkyEngine/releases/download/prebuilts-20260329/skyengine-prebuilts-x64-windows-static-c3867e71.tar.zst",
+      "sha256": "<hash>"
+    },
+    "x64-linux": {
+      "url": "...",
+      "sha256": "<hash>"
+    },
+    "x64-osx": { "url": "...", "sha256": "<hash>" },
+    "arm64-osx": { "url": "...", "sha256": "<hash>" },
+    "arm64-ios": { "url": "...", "sha256": "<hash>" },
+    "arm64-android": { "url": "...", "sha256": "<hash>" }
+  }
+}
+```
+
+This file is committed to the repository and updated by an automated CI step when a new prebuild batch is published.
+
+### 7.3 CMake Download Logic (`cmake/sky_prebuild.cmake`)
+
+```cmake
+# cmake/sky_prebuild.cmake  (pseudocode)
+
+function(sky_download_prebuilts TRIPLET)
+    file(READ "${CMAKE_SOURCE_DIR}/cmake/prebuild_manifest.json" _manifest)
+    string(JSON _url    GET "${_manifest}" "triplets" "${TRIPLET}" "url")
+    string(JSON _sha256 GET "${_manifest}" "triplets" "${TRIPLET}" "sha256")
+
+    set(_archive_dir "${CMAKE_BINARY_DIR}/_prebuilts")
+    set(_archive     "${_archive_dir}/${TRIPLET}.tar.zst")
+    set(_unpack_dir  "${_archive_dir}/${TRIPLET}")
+
+    # Skip if already unpacked and manifest hash matches
+    set(_stamp "${_unpack_dir}/.stamp_${_sha256}")
+    if(EXISTS "${_stamp}")
+        message(STATUS "[SkyEngine] Prebuilts for ${TRIPLET} are up-to-date")
+    else()
+        message(STATUS "[SkyEngine] Downloading prebuilts for ${TRIPLET} ...")
+        file(DOWNLOAD "${_url}" "${_archive}"
+            EXPECTED_HASH SHA256=${_sha256}
+            SHOW_PROGRESS
+            STATUS _dl_status
+        )
+        list(GET _dl_status 0 _dl_code)
+        if(NOT _dl_code EQUAL 0)
+            message(FATAL_ERROR "[SkyEngine] Failed to download prebuilts: ${_dl_status}")
+        endif()
+        file(ARCHIVE_EXTRACT INPUT "${_archive}" DESTINATION "${_unpack_dir}")
+        file(TOUCH "${_stamp}")
+        message(STATUS "[SkyEngine] Prebuilts extracted to ${_unpack_dir}")
+    endif()
+
+    # Expose to find_package
+    list(PREPEND CMAKE_PREFIX_PATH "${_unpack_dir}")
+    set(CMAKE_PREFIX_PATH "${CMAKE_PREFIX_PATH}" PARENT_SCOPE)
+endfunction()
+```
+
+After `sky_download_prebuilts` runs, `cmake/sky_packages.cmake` (the renamed `vcpkg.cmake`) is included and all `find_package` calls resolve against the unpacked tree without any code changes.
+
+### 7.4 CI Pipeline Design
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  GitHub Actions: "Publish Prebuilts" (manual or tag-driven) │
+│                                                             │
+│  Matrix:                                                    │
+│    triplet: [x64-windows-static, x64-linux, x64-osx,       │
+│              arm64-osx, arm64-ios, arm64-android]           │
+│                                                             │
+│  Steps per triplet:                                         │
+│  1. Checkout                                                │
+│  2. Setup vcpkg (lukka/run-vcpkg@v11 with baseline commit)  │
+│  3. cmake configure (vcpkg toolchain, selected triplet,     │
+│       SKY_BUILD_EDITOR=ON, all optional features ON)        │
+│  4. cmake --build (no engine code, just vcpkg install)      │
+│     Tip: use "cmake -P cmake/vcpkg_export.cmake" to export  │
+│     only the installed tree without building engine code.   │
+│  5. Pack: tar --zstd -cf <triplet>.tar.zst installed/       │
+│  6. Upload artifact to GitHub Release                       │
+│                                                             │
+│  Final step (after matrix):                                 │
+│  7. Update cmake/prebuild_manifest.json with new URLs+SHA   │
+│  8. Open automated PR to commit the updated manifest        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+The CI job that builds the engine (push/PR workflow) is separate and uses `SKY_PREBUILD_MODE=ON` by default to avoid recompiling dependencies on every build.
+
+---
+
+## 8. Unified CMake Entry Point
+
+After the refactor, `CMakeLists.txt` becomes:
+
+```cmake
+cmake_minimum_required(VERSION 3.19)
+
+# ---- Options needed before project() ----
+include(cmake/options.cmake)       # SKY_BUILD_*, SKY_PREBUILD_MODE
+include(cmake/sky_triplet.cmake)   # sky_select_triplet()
+
+sky_select_triplet(VCPKG_TARGET_TRIPLET)
+set(VCPKG_OVERLAY_TRIPLETS "${CMAKE_CURRENT_SOURCE_DIR}/triplets" CACHE STRING "" FORCE)
+
+if(NOT SKY_PREBUILD_MODE)
+    include(cmake/sky_vcpkg_find.cmake)
+    sky_find_or_bootstrap_vcpkg(_sky_toolchain)
+    set(CMAKE_TOOLCHAIN_FILE "${_sky_toolchain}" CACHE STRING "" FORCE)
+    include(cmake/sky_vcpkg_features.cmake)  # map SKY_BUILD_* → VCPKG_MANIFEST_FEATURES
+endif()
+
+project(SkyEngine)
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+
+set(ENGINE_ROOT ${CMAKE_CURRENT_LIST_DIR})
+
+include(cmake/functions.cmake)
+include(cmake/plugin_switches.cmake)
+include(cmake/configuration.cmake)
+
+# ---- Third-party resolution ----
+if(SKY_PREBUILD_MODE)
+    include(cmake/sky_prebuild.cmake)
+    sky_download_prebuilts("${VCPKG_TARGET_TRIPLET}")
+endif()
+include(cmake/sky_packages.cmake)   # renamed vcpkg.cmake; works in both modes
+
+# ---- Engine targets ----
+if(NOT ANDROID)
+    set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${ENGINE_ROOT}/output/bin)
+    set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${ENGINE_ROOT}/output/bin)
+endif()
+
+if(SKY_BUILD_TEST)
+    enable_testing()
+endif()
+
+add_subdirectory(engine)
+add_subdirectory(plugins)
+if(SKY_BUILD_TOOL)
+    add_subdirectory(tools)
+endif()
+```
+
+---
+
+## 9. File Responsibility Map (After Refactor)
+
+| File | Responsibility |
+|---|---|
+| `CMakeLists.txt` | Top-level: option wiring, triplet selection, vcpkg/prebuild dispatch, `project()`, add_subdirectory |
+| `cmake/options.cmake` | All `option()` and `set(CACHE ...)` declarations |
+| `cmake/sky_triplet.cmake` | Auto-detect correct vcpkg triplet from CMake platform/arch variables |
+| `cmake/sky_vcpkg_find.cmake` | Probe global vcpkg installations; bootstrap local clone as last resort |
+| `cmake/sky_vcpkg_features.cmake` | Map `SKY_BUILD_*` options to `VCPKG_MANIFEST_FEATURES` (moved out of CMakeLists.txt) |
+| `cmake/sky_packages.cmake` | `find_package` calls + `3rdParty::` alias targets; mode-agnostic |
+| `cmake/sky_prebuild.cmake` | Read `prebuild_manifest.json`, download and unpack prebuilt archive |
+| `cmake/prebuild_manifest.json` | Maps triplet → download URL + SHA256; updated by CI automation |
+| `cmake/configuration.cmake` | Compile flags, platform defines (unchanged) |
+| `cmake/functions.cmake` | sky_add_exe, sky_add_lib helpers (unchanged) |
+| `triplets/*.cmake` | vcpkg triplet definitions (see §5.4 for required fixes) |
+| `vcpkg.json` | Dependency manifest with version overrides and feature gates |
+| `vcpkg-configuration.json` | Registry sources (unchanged) |
+
+Files **removed** or retired after the refactor:
+
+| File | Disposition |
+|---|---|
+| `cmake/thirdparty.cmake` | Replaced by `sky_packages.cmake` + `sky_prebuild.cmake` |
+| `cmake/vcpkg.cmake` | Renamed/merged into `sky_packages.cmake` |
+| `cmake/vcpkg_bootstrap.cmake` | Functionality absorbed into `sky_vcpkg_find.cmake` |
+| `cmake/thirdparty_helpers.cmake` | Merged into `sky_packages.cmake` (one small function) |
+| `python/third_party.py` | Retired; prebuild artifacts are now produced by CI vcpkg |
+| `cmake/thirdparty.json` | Retired; packages are tracked in `vcpkg.json` |
+| `cmake/thirdparty/Find*.cmake` | Retired; only `find_package` with vcpkg prefix paths needed |
+
+---
+
+## 10. Migration Checklist
+
+### Phase 1: vcpkg Stabilization (1–2 days)
+
+- [ ] Fix triplet auto-selection (`sky_triplet.cmake`) and remove hardcoded `x64-windows` / `x64-linux` strings from thirdparty.cmake
+- [ ] Unify Windows triplet to `x64-windows-static` in all paths (CMakeLists.txt, CI yaml)
+- [ ] Fix `arm64-android.cmake`: add `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` and configure options
+- [ ] Verify global vcpkg probe order; refactor `vcpkg_bootstrap.cmake` to check env vars first
+- [ ] Validate all `find_package` + alias pairs in `cmake/vcpkg.cmake` for all desktop triplets in CI
+- [ ] Remove or guard deprecated `cxxopts` target (present in legacy list but absent from vcpkg.json)
+
+### Phase 2: Prebuild Infrastructure (2–3 days)
+
+- [ ] Define `cmake/prebuild_manifest.json` schema
+- [ ] Write `cmake/sky_prebuild.cmake` (download, verify SHA256, unpack, set `CMAKE_PREFIX_PATH`)
+- [ ] Add `SKY_PREBUILD_MODE` option to `cmake/options.cmake`
+- [ ] Create CI workflow `publish-prebuilts.yml` with matrix across all triplets
+- [ ] Add automated manifest-update step and PR creation to CI pipeline
+- [ ] Validate that `sky_packages.cmake` resolves identically in both modes
+
+### Phase 3: Cleanup and Documentation (1 day)
+
+- [ ] Remove `python/third_party.py` and `cmake/thirdparty.json` (or archive in a `legacy/` folder)
+- [ ] Remove `cmake/thirdparty/` Find modules
+- [ ] Update top-level `README.md` with new build instructions (local-build and prebuild)
+- [ ] Update `.github/workflows/cmake.yml`: replace legacy job with prebuild-mode job
+
+---
+
+## 11. Developer Usage After Refactor
+
+### Local Build (vcpkg auto-bootstrapped)
+
+```bash
+# First time: vcpkg is found via VCPKG_ROOT or auto-bootstrapped
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+### Local Build (explicit global vcpkg)
+
+```bash
+cmake -B build \
+  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
+  -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+### Prebuild Mode (fast, no source compilation of dependencies)
+
+```bash
+cmake -B build \
+  -DSKY_PREBUILD_MODE=ON \
+  -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+The first configure run downloads and unpacks `~300 MB` of prebuilt libraries for the detected triplet.  Subsequent configures use the cached unpack directory (verified by SHA256 stamp).
+
+### Cross-Compile for Android
+
+```bash
+cmake -B build \
+  -DCMAKE_SYSTEM_NAME=Android \
+  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
+  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
+  -DANDROID_ABI=arm64-v8a \
+  -DANDROID_PLATFORM=android-31 \
+  -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+Triplet `arm64-android` is selected automatically by `sky_triplet.cmake`.

From d86cca75bc7b196fd3816aa3dbbea73b0d65cc91 Mon Sep 17 00:00:00 2001
From: Yiwen Xue <15225434259xue@gmail.com>
Date: Fri, 3 Apr 2026 22:15:14 +0800
Subject: [PATCH 11/11] fix compile

---
 .gitignore                                    |   1 +
 CMakePresets.json                             |  49 ++++++++
 README.md                                     |  26 ++---
 cmake/vcpkg.cmake                             | 107 ++++++++++++++++--
 engine/render/backend/vulkan/CMakeLists.txt   |  11 +-
 engine/render/imgui/src/ImGuiInstance.cpp     |  53 +++++++++
 .../render/shader/src/ShaderCompilerGlsl.cpp  |  54 ++++++---
 engine/render/tool/image/src/GuiRender.cpp    |   2 +
 vcpkg-configuration.json                      |   2 +-
 vcpkg.json                                    |   6 +
 10 files changed, 268 insertions(+), 43 deletions(-)
 create mode 100644 CMakePresets.json

diff --git a/.gitignore b/.gitignore
index a08929b8..5df6e21d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,4 +24,5 @@
 /docs/pdf/
 .DS_Store
 /vcpkg/
+/vcpkg_installed/
 /.thirdparty/
\ No newline at end of file
diff --git a/CMakePresets.json b/CMakePresets.json
new file mode 100644
index 00000000..6048bb7f
--- /dev/null
+++ 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
index b404d381..0bf51e40 100644
--- a/README.md
+++ b/README.md
@@ -11,12 +11,12 @@ SkyEngine supports two CMake-selectable third-party modes:
 
 Key CMake cache options:
 
-| option | description |
-|---|---|
-| `SKY_THIRDPARTY_MODE` | `LOCAL` or `PREBUILT` |
-| `SKY_THIRDPARTY_ROOT` | local dependency root for downloads/installed/cache |
+| 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 |
+| `3RD_PATH`                    | required in `PREBUILT` mode                                            |
 
 Examples:
 
@@ -36,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
 
@@ -81,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    |
diff --git a/cmake/vcpkg.cmake b/cmake/vcpkg.cmake
index 93188957..d2f54450 100644
--- a/cmake/vcpkg.cmake
+++ b/cmake/vcpkg.cmake
@@ -2,7 +2,14 @@
 # Bridge module: creates 3rdParty:: targets from vcpkg-installed packages.
 # Included automatically when vcpkg toolchain is detected.
 
-include(${ENGINE_ROOT}/cmake/thirdparty_helpers.cmake)
+Include(${ENGINE_ROOT}/cmake/thirdparty_helpers.cmake)
+
+# CMake 4.x strict validation of transitive INTERFACE_LINK_LIBRARIES can fail
+# when targets are created via function overrides (like vcpkg's add_library).
+# Disable CMP0189 to use pre-4.1 behavior.
+if(POLICY CMP0189)
+    cmake_policy(SET CMP0189 OLD)
+endif()
 
 # ---------------------------------------------------------------------------
 # Helper: create a 3rdParty::<name> INTERFACE target forwarding to vcpkg
@@ -21,12 +28,63 @@ endfunction()
 # ===========================================================================
 
 # --- boost ------------------------------------------------------------------
+# Pre-create Boost::headers as GLOBAL with explicit include path to work around
+# CMake 4.x issue where _IMPORT_PREFIX computes incorrectly in vcpkg's function-override
+# context, resulting in "${_IMPORT_PREFIX}/include" = "/include" at generate time.
+if(NOT TARGET Boost::headers)
+    find_path(_SKY_BOOST_INC boost/version.hpp
+        PATHS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/include"
+        NO_DEFAULT_PATH)
+    if(_SKY_BOOST_INC)
+        _add_library(Boost::headers INTERFACE IMPORTED GLOBAL)
+        set_target_properties(Boost::headers PROPERTIES
+            INTERFACE_INCLUDE_DIRECTORIES "${_SKY_BOOST_INC}")
+    endif()
+endif()
+
 find_package(Boost REQUIRED COMPONENTS container graph)
-sky_vcpkg_alias(3rdParty::boost Boost::container Boost::graph)
+
+# Create/replace 3rdParty::boost as a proper INTERFACE IMPORTED target that directly uses 
+# the found boost include/lib paths WITHOUT relying on Boost::container/Boost::graph targets,
+# which may not be visible due to CMake 4.x scoping issues in vcpkg's function overrides.
+
+# Find boost include directory directly
+find_path(_SKY_BOOST_INC boost/version.hpp
+    PATHS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/include"
+    NO_DEFAULT_PATH)
+
+# Find boost libraries directly  
+find_library(_SKY_BOOST_GRAPH libboost_graph.a
+         PATHS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/lib"
+         NO_DEFAULT_PATH)
+find_library(_SKY_BOOST_CONTAINER libboost_container.a
+    PATHS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/lib"
+    NO_DEFAULT_PATH)
+
+# Create or replace 3rdParty::boost
+if(TARGET 3rdParty::boost)
+    # Target already exists (possibly created implicitly), replace its properties
+    set_target_properties(3rdParty::boost PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${_SKY_BOOST_INC}"
+        INTERFACE_LINK_LIBRARIES "")
+    target_link_libraries(3rdParty::boost INTERFACE ${_SKY_BOOST_CONTAINER} ${_SKY_BOOST_GRAPH})
+else()
+    # Create new target
+    add_library(3rdParty::boost INTERFACE IMPORTED GLOBAL)
+    set_target_properties(3rdParty::boost PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${_SKY_BOOST_INC}")
+    if(_SKY_BOOST_CONTAINER OR _SKY_BOOST_GRAPH)
+        target_link_libraries(3rdParty::boost INTERFACE ${_SKY_BOOST_CONTAINER} ${_SKY_BOOST_GRAPH})
+    endif()
+endif()
+
+unset(_SKY_BOOST_INC)
+unset(_SKY_BOOST_CONTAINER)
+unset(_SKY_BOOST_GRAPH)
 
 # --- sfmt -------------------------------------------------------------------
 find_package(sfmt CONFIG REQUIRED)
-sky_vcpkg_alias(3rdParty::sfmt sfmt::sfmt)
+sky_vcpkg_alias(3rdParty::sfmt sfmt::SFMT)
 
 # --- taskflow ---------------------------------------------------------------
 find_package(Taskflow CONFIG REQUIRED)
@@ -56,7 +114,6 @@ sky_vcpkg_alias(3rdParty::glslang
     glslang::glslang
     glslang::glslang-default-resource-limits
     glslang::SPIRV
-    glslang::SPVRemapper
 )
 
 # --- SPIRV-Cross ------------------------------------------------------------
@@ -103,6 +160,34 @@ endif()
 
 # --- freetype (text plugin) -------------------------------------------------
 if (SKY_BUILD_FREETYPE)
+    # Pre-create ZLIB::ZLIB as GLOBAL so freetype-targets.cmake (CMake 4.x)
+    # can validate it in INTERFACE_LINK_LIBRARIES at generate time.
+    if(NOT TARGET ZLIB::ZLIB)
+        find_path(_sky_zlib_inc NAMES zlib.h
+            PATHS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/include"
+            NO_DEFAULT_PATH)
+        find_library(_sky_zlib_rel NAMES z zlib
+            PATHS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/lib"
+            NO_DEFAULT_PATH)
+        find_library(_sky_zlib_dbg NAMES z zlib
+            PATHS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/debug/lib"
+            NO_DEFAULT_PATH)
+        _add_library(ZLIB::ZLIB UNKNOWN IMPORTED GLOBAL)
+        set_target_properties(ZLIB::ZLIB PROPERTIES
+            INTERFACE_INCLUDE_DIRECTORIES "${_sky_zlib_inc}"
+            IMPORTED_LOCATION "${_sky_zlib_rel}")
+        if(_sky_zlib_rel)
+            set_property(TARGET ZLIB::ZLIB APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE)
+            set_target_properties(ZLIB::ZLIB PROPERTIES IMPORTED_LOCATION_RELEASE "${_sky_zlib_rel}")
+        endif()
+        if(_sky_zlib_dbg)
+            set_property(TARGET ZLIB::ZLIB APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG)
+            set_target_properties(ZLIB::ZLIB PROPERTIES IMPORTED_LOCATION_DEBUG "${_sky_zlib_dbg}")
+        endif()
+        set(ZLIB_FOUND TRUE CACHE BOOL "" FORCE)
+        set(ZLIB_LIBRARY "${_sky_zlib_rel}" CACHE FILEPATH "" FORCE)
+        set(ZLIB_INCLUDE_DIRS "${_sky_zlib_inc}" CACHE PATH "" FORCE)
+    endif()
     find_package(Freetype REQUIRED)
     sky_vcpkg_alias(3rdParty::freetype Freetype::Freetype)
 endif()
@@ -118,13 +203,13 @@ endif()
 if (SKY_BUILD_BULLET)
     find_package(Bullet CONFIG REQUIRED)
     sky_vcpkg_alias(3rdParty::bullet3
-        Bullet3Common::Bullet3Common
-        Bullet3Collision::Bullet3Collision
-        Bullet3Dynamics::Bullet3Dynamics
-        Bullet3Geometry::Bullet3Geometry
-        BulletCollision::BulletCollision
-        BulletDynamics::BulletDynamics
-        LinearMath::LinearMath
+        Bullet3Common
+        Bullet3Collision
+        Bullet3Dynamics
+        Bullet3Geometry
+        BulletCollision
+        BulletDynamics
+        LinearMath
     )
 endif()
 
diff --git a/engine/render/backend/vulkan/CMakeLists.txt b/engine/render/backend/vulkan/CMakeLists.txt
index 8cf89250..2ad41711 100644
--- a/engine/render/backend/vulkan/CMakeLists.txt
+++ b/engine/render/backend/vulkan/CMakeLists.txt
@@ -3,7 +3,8 @@ file(GLOB_RECURSE INC_FILES include/*)
 
 find_package(Vulkan)
 if (NOT Vulkan_FOUND)
-    message("vulkan sdk not found")
+    message(WARNING "Vulkan SDK not found - skipping Vulkan backend")
+    return()
 endif()
 
 add_library(VulkanSdk INTERFACE IMPORTED GLOBAL
@@ -13,8 +14,12 @@ add_library(VulkanSdk INTERFACE IMPORTED GLOBAL
     ../../tool/image/src/ImageTool.cpp
     ../../core/include/render/mesh/MeshInterface.h
     ../../core/include/render/resource/StaticMesh.h)
-target_link_libraries(VulkanSdk INTERFACE ${Vulkan_LIBRARIES})
-target_include_directories(VulkanSdk INTERFACE ${Vulkan_INCLUDE_DIRS})
+if(Vulkan_LIBRARIES)
+    target_link_libraries(VulkanSdk INTERFACE ${Vulkan_LIBRARIES})
+endif()
+if(Vulkan_INCLUDE_DIRS)
+    target_include_directories(VulkanSdk INTERFACE ${Vulkan_INCLUDE_DIRS})
+endif()
 
 if (WIN32)
     file(GLOB_RECURSE PLATFORM_SRC platform/windows/*)
diff --git a/engine/render/imgui/src/ImGuiInstance.cpp b/engine/render/imgui/src/ImGuiInstance.cpp
index 51d8ba14..30813b4a 100644
--- a/engine/render/imgui/src/ImGuiInstance.cpp
+++ b/engine/render/imgui/src/ImGuiInstance.cpp
@@ -20,6 +20,37 @@ namespace sky {
         ImVec2 translate;
     };
 
+    static ImGuiKey ConvertImGuiKey(ScanCode key)
+    {
+        switch (key) {
+            case ScanCode::KEY_TAB: return ImGuiKey_Tab;
+            case ScanCode::KEY_LEFT: return ImGuiKey_LeftArrow;
+            case ScanCode::KEY_RIGHT: return ImGuiKey_RightArrow;
+            case ScanCode::KEY_UP: return ImGuiKey_UpArrow;
+            case ScanCode::KEY_DOWN: return ImGuiKey_DownArrow;
+            case ScanCode::KEY_PAGEUP: return ImGuiKey_PageUp;
+            case ScanCode::KEY_PAGEDOWN: return ImGuiKey_PageDown;
+            case ScanCode::KEY_HOME: return ImGuiKey_Home;
+            case ScanCode::KEY_END: return ImGuiKey_End;
+            case ScanCode::KEY_INSERT: return ImGuiKey_Insert;
+            case ScanCode::KEY_DELETE: return ImGuiKey_Delete;
+            case ScanCode::KEY_BACKSPACE: return ImGuiKey_Backspace;
+            case ScanCode::KEY_SPACE: return ImGuiKey_Space;
+            case ScanCode::KEY_RETURN: return ImGuiKey_Enter;
+            case ScanCode::KEY_ESCAPE: return ImGuiKey_Escape;
+            case ScanCode::KEY_KP_ENTER: return ImGuiKey_KeypadEnter;
+            case ScanCode::KEY_A: return ImGuiKey_A;
+            case ScanCode::KEY_C: return ImGuiKey_C;
+            case ScanCode::KEY_V: return ImGuiKey_V;
+            case ScanCode::KEY_X: return ImGuiKey_X;
+            case ScanCode::KEY_Y: return ImGuiKey_Y;
+            case ScanCode::KEY_Z: return ImGuiKey_Z;
+            default:
+                break;
+        }
+        return ImGuiKey_None;
+    }
+
     void ImContext::Init()
     {
         imContext = ImGui::CreateContext();
@@ -84,6 +115,7 @@ namespace sky {
 
         ImGuiIO& io = ImGui::GetIO();
 
+    #if IMGUI_VERSION_NUM < 18700
         io.KeyMap[ImGuiKey_Tab]         = static_cast<int>(ScanCode::KEY_TAB);
         io.KeyMap[ImGuiKey_LeftArrow]   = static_cast<int>(ScanCode::KEY_LEFT);
         io.KeyMap[ImGuiKey_RightArrow]  = static_cast<int>(ScanCode::KEY_RIGHT);
@@ -108,6 +140,7 @@ namespace sky {
         io.KeyMap[ImGuiKey_X]           = static_cast<int>(ScanCode::KEY_X);
         io.KeyMap[ImGuiKey_Y]           = static_cast<int>(ScanCode::KEY_Y);
         io.KeyMap[ImGuiKey_Z]           = static_cast<int>(ScanCode::KEY_Z);
+#endif
 
 
         io.SetClipboardTextFn = [](void* user_data, const char* text){
@@ -351,19 +384,39 @@ namespace sky {
     void ImGuiInstance::OnKeyUp(const KeyboardEvent &event)
     {
         ImGuiIO& io = ImGui::GetIO();
+#if IMGUI_VERSION_NUM >= 18700
+        const auto key = ConvertImGuiKey(event.scanCode);
+        if (key != ImGuiKey_None) {
+            io.AddKeyEvent(key, false);
+        }
+        io.AddKeyEvent(ImGuiMod_Shift, static_cast<bool>(event.mod & KeyMod::SHIFT));
+        io.AddKeyEvent(ImGuiMod_Ctrl, static_cast<bool>(event.mod & KeyMod::CTRL));
+        io.AddKeyEvent(ImGuiMod_Alt, static_cast<bool>(event.mod & KeyMod::ALT));
+#else
         io.KeysDown[static_cast<uint32_t>(event.scanCode)] = false;
         io.KeyShift = static_cast<bool>(event.mod & KeyMod::SHIFT);
         io.KeyCtrl = static_cast<bool>(event.mod & KeyMod::CTRL);
         io.KeyAlt = static_cast<bool>(event.mod & KeyMod::ALT);
+#endif
     }
 
     void ImGuiInstance::OnKeyDown(const KeyboardEvent &event)
     {
         ImGuiIO& io = ImGui::GetIO();
+#if IMGUI_VERSION_NUM >= 18700
+        const auto key = ConvertImGuiKey(event.scanCode);
+        if (key != ImGuiKey_None) {
+            io.AddKeyEvent(key, true);
+        }
+        io.AddKeyEvent(ImGuiMod_Shift, static_cast<bool>(event.mod & KeyMod::SHIFT));
+        io.AddKeyEvent(ImGuiMod_Ctrl, static_cast<bool>(event.mod & KeyMod::CTRL));
+        io.AddKeyEvent(ImGuiMod_Alt, static_cast<bool>(event.mod & KeyMod::ALT));
+#else
         io.KeysDown[static_cast<uint32_t>(event.scanCode)] = true;
         io.KeyShift = static_cast<bool>(event.mod & KeyMod::SHIFT);
         io.KeyCtrl = static_cast<bool>(event.mod & KeyMod::CTRL);
         io.KeyAlt = static_cast<bool>(event.mod & KeyMod::ALT);
+#endif
     }
 
     void ImGuiInstance::OnTextInput(WindowID winID, const char *text)
diff --git a/engine/render/shader/src/ShaderCompilerGlsl.cpp b/engine/render/shader/src/ShaderCompilerGlsl.cpp
index 3af8d463..fd2f9893 100644
--- a/engine/render/shader/src/ShaderCompilerGlsl.cpp
+++ b/engine/render/shader/src/ShaderCompilerGlsl.cpp
@@ -6,7 +6,6 @@
 #include <glslang/SPIRV/GlslangToSpv.h>
 #include <glslang/Public/ResourceLimits.h>
 #include <glslang/Public/ShaderLang.h>
-#include <glslang/Include/Types.h>
 
 #if ENABLE_SPIRV_TOOLS
 #include <spirv-tools/libspirv.hpp>
@@ -49,14 +48,23 @@ namespace sky {
         return EShLangCount;
     }
 
-    static rhi::BaseType GetBaseType(const glslang::TType* type)
+    static rhi::BaseType GetBaseType(int glType)
     {
-        switch (type->getBasicType()) {
-            case glslang::EbtFloat:
+        switch (glType) {
+            case 0x1406: // GL_FLOAT
+            case 0x8B50: // GL_FLOAT_VEC2
+            case 0x8B51: // GL_FLOAT_VEC3
+            case 0x8B52: // GL_FLOAT_VEC4
                 return rhi::BaseType::FLOAT;
-            case glslang::EbtInt:
+            case 0x1404: // GL_INT
+            case 0x8B53: // GL_INT_VEC2
+            case 0x8B54: // GL_INT_VEC3
+            case 0x8B55: // GL_INT_VEC4
                 return rhi::BaseType::INT;
-            case glslang::EbtUint:
+            case 0x1405: // GL_UNSIGNED_INT
+            case 0x8DC6: // GL_UNSIGNED_INT_VEC2
+            case 0x8DC7: // GL_UNSIGNED_INT_VEC3
+            case 0x8DC8: // GL_UNSIGNED_INT_VEC4
                 return rhi::BaseType::UINT;
             default:
                 break;
@@ -64,6 +72,26 @@ namespace sky {
         return rhi::BaseType::UNDEFINED;
     }
 
+    static uint32_t GetVectorSize(int glType)
+    {
+        switch (glType) {
+            case 0x8B50: // GL_FLOAT_VEC2
+            case 0x8B53: // GL_INT_VEC2
+            case 0x8DC6: // GL_UNSIGNED_INT_VEC2
+                return 2;
+            case 0x8B51: // GL_FLOAT_VEC3
+            case 0x8B54: // GL_INT_VEC3
+            case 0x8DC7: // GL_UNSIGNED_INT_VEC3
+                return 3;
+            case 0x8B52: // GL_FLOAT_VEC4
+            case 0x8B55: // GL_INT_VEC4
+            case 0x8DC8: // GL_UNSIGNED_INT_VEC4
+                return 4;
+            default:
+                return 1;
+        }
+    }
+
     std::string ShaderCompilerGlsl::Disassemble(const std::vector<uint32_t>& binary, ShaderCompileTarget target) const
     {
         std::string text;
@@ -128,21 +156,17 @@ namespace sky {
         auto num = program.getNumPipeInputs();
         for (int i = 0; i < num && desc.stage == rhi::ShaderStageFlagBit::VS; ++i) {
             const auto &refl = program.getPipeInput(i);
-            const auto *type = refl.getType();
-            if (type->isBuiltIn()) {
+            if (refl.name.rfind("gl_", 0) == 0) {
                 continue;
             }
 
-            std::string semantic;
-            if (refl.getType()->getQualifier().semanticName) {
-                semantic = refl.getType()->getQualifier().semanticName;
-            }
+            std::string semantic = refl.name;
 
             attributes.emplace_back(VertexStageAttribute{
                 semantic,
-                refl.getType()->getQualifier().layoutLocation,
-                static_cast<uint32_t>(type->getVectorSize()),
-                GetBaseType(type)
+                refl.layoutLocation(),
+                GetVectorSize(refl.glDefineType),
+                GetBaseType(refl.glDefineType)
             });
         }
 
diff --git a/engine/render/tool/image/src/GuiRender.cpp b/engine/render/tool/image/src/GuiRender.cpp
index 3fc837fa..53245cdc 100644
--- a/engine/render/tool/image/src/GuiRender.cpp
+++ b/engine/render/tool/image/src/GuiRender.cpp
@@ -157,6 +157,7 @@ namespace sky {
         ImGui::CreateContext();
         ImGuiIO& io = ImGui::GetIO();
 
+    #if IMGUI_VERSION_NUM < 18700
         io.KeyMap[ImGuiKey_Tab]         = static_cast<int>(ScanCode::KEY_TAB);
         io.KeyMap[ImGuiKey_LeftArrow]   = static_cast<int>(ScanCode::KEY_LEFT);
         io.KeyMap[ImGuiKey_RightArrow]  = static_cast<int>(ScanCode::KEY_RIGHT);
@@ -178,6 +179,7 @@ namespace sky {
         io.KeyMap[ImGuiKey_X]           = static_cast<int>(ScanCode::KEY_X);
         io.KeyMap[ImGuiKey_Y]           = static_cast<int>(ScanCode::KEY_Y);
         io.KeyMap[ImGuiKey_Z]           = static_cast<int>(ScanCode::KEY_Z);
+    #endif
 
         io.DisplaySize = ImVec2(static_cast<float>(window->GetWidth()), static_cast<float>(window->GetHeight()));
         io.DisplayFramebufferScale = ImVec2(1.f, 1.f);
diff --git a/vcpkg-configuration.json b/vcpkg-configuration.json
index bb9d0600..27af5e57 100644
--- a/vcpkg-configuration.json
+++ b/vcpkg-configuration.json
@@ -9,7 +9,7 @@
 		{
 			"kind": "git",
 			"repository": "https://github.com/Zhuyin-Graphics/vcpkg-registry",
-			"baseline": "e8c9c2888b269152ee7bcf9eca74258b6c581025",
+			"baseline": "f98934032b79a5c207edde10f87edbf7e83b0f45",
 			"packages": [
 				"assimp",
 				"boost-container",
diff --git a/vcpkg.json b/vcpkg.json
index fa34ef4e..7956d253 100644
--- a/vcpkg.json
+++ b/vcpkg.json
@@ -3,6 +3,12 @@
 	"name": "skyengine",
 	"version-string": "0.1.0",
 	"description": "SkyEngine - A cross-platform game engine",
+	"default-features": [
+		"bullet",
+		"recast",
+		"freetype",
+		"compression"
+	],
 	"dependencies": [
 		"boost-container",
 		"boost-graph",