KBEngine Nex

Appearance

生成 Visual Studio 工程 ​

KBEngine Nex 的 Windows 默认安装流程使用 Ninja Multi-Config。需要在 Visual Studio 中浏览工程结构、编译目标或调试 C++ 组件时，可以额外生成 CMake 管理的 Visual Studio Solution。

生成的 .sln 只是另一种 CMake 构建入口，不是独立维护的旧版工程。目标、源码、编译选项和 vcpkg 依赖仍由主工程的 CMakeLists.txt、CMakePresets.json 和 vcpkg.json 统一管理。

前置条件 ​

生成工程前需要准备：

  • Visual Studio 2022 或 Visual Studio 2026；
  • “使用 C++ 的桌面开发”工作负载；
  • Windows SDK；
  • Git 和 CMake 3.25 或更高版本；
  • 可访问 vcpkg 仓库及第三方依赖下载地址的网络环境。

建议先完成 Windows 安装。如果尚未初始化 kbe/vcpkg，生成脚本也会自动克隆并引导 vcpkg；首次 CMake 配置会恢复依赖，因此可能需要较长时间。

使用生成脚本 ​

在引擎仓库根目录运行：

powershell
.\install\generate_vs_project.bat

未指定版本时，脚本会要求选择 Visual Studio 2022 或 Visual Studio 2026。也可以直接指定版本，避免交互输入：

powershell
# 生成 Visual Studio 2022 工程
.\install\generate_vs_project.bat -VisualStudioVersion 2022

# 生成 Visual Studio 2026 工程
.\install\generate_vs_project.bat -VisualStudioVersion 2026

也可以直接调用 PowerShell 脚本：

powershell
.\install\generate_vs_project.ps1 -VisualStudioVersion 2022

脚本使用 --fresh 重新执行 CMake 配置，但不会删除 vcpkg 下载缓存、已安装依赖或 Ninja 构建目录。

工程输出目录 ​

不同 Visual Studio 版本使用独立目录：

Visual Studio 版本CMake PresetSolution
Visual Studio 2022windows-vs2022kbe/src/out/build/windows-vs2022/KBEngineNex.sln
Visual Studio 2026windows-vs2026kbe/src/out/build/windows-vs2026/KBEngineNex.sln

生成完成后，可以直接打开 Solution：

powershell
start .\kbe\src\out\build\windows-vs2022\KBEngineNex.sln

Visual Studio 工程按组件、公共库、工具和测试等职责分组。_CMake 分组中的目标由 CMake 自动生成，不应手工修改生成目录里的 .sln 或 .vcxproj；需要调整工程结构、源码或编译选项时，应修改对应的 CMake 文件并重新生成。

编译配置 ​

Solution 支持 Debug 和 Release。平台应选择 x64：

配置用途
DebugC++ 本地调试，保留调试信息；仍链接 Release Python 3.12 ABI
Release性能测试和正式构建

可以在 Visual Studio 中编译 kbe_servers、kbe_tests 或具体组件，也可以继续使用对应的 CMake Build Preset：

powershell
cd kbe\src

# Visual Studio 2022
cmake --build --preset windows-vs2022-servers-debug --parallel
cmake --build --preset windows-vs2022-tests-debug --parallel

# Visual Studio 2026
cmake --build --preset windows-vs2026-servers-debug --parallel
cmake --build --preset windows-vs2026-tests-debug --parallel

将命令中的 debug 改为 release 即可构建 Release。服务端程序仍会输出到稳定运行目录 kbe/bin/server；库和测试等中间产物保留在 CMake 输出目录中。

不要混用生成目录

windows-ninja、windows-vs2022 和 windows-vs2026 使用不同生成器和构建目录。不要手工复制 CMakeCache.txt，也不要让多个生成器共用同一个 out/build 子目录。

重新生成 ​

新增源码、修改 CMake 配置、更新 vcpkg baseline 或切换依赖版本后，重新运行相同命令即可：

powershell
.\install\generate_vs_project.bat -VisualStudioVersion 2022

CMake 和 Visual Studio 通常可以自动检测普通 CMakeLists.txt 变更，但显式重新生成更适合验证 Preset、工具链或依赖层面的修改。

常见问题 ​

找不到 Visual Studio 生成器 ​

确认已安装对应版本的 Visual Studio、C++ 工作负载和 Windows SDK。Visual Studio 2026 还要求当前 CMake 已提供 Visual Studio 18 2026 生成器；不满足时请升级 CMake，或显式选择 Visual Studio 2022。

vcpkg 恢复依赖失败 ​

先检查 Git、代理、证书和第三方源码下载地址。不要把下载不完整的 buildtrees 当成可复用缓存，也不要通过修改生成的 .vcxproj 绕过依赖问题。

修改生成的工程后丢失 ​

.sln 和 .vcxproj 是 CMake 生成产物，重新配置时会被更新。永久修改必须落在源码、CMakeLists.txt、CMake 模块或 Preset 中。

如何调试服务端组件 ​

生成工程只负责提供 IDE 构建入口。组件调试还需要正确设置 Assets、环境变量、启动参数和依赖组件，详见 VS 调试。