将工程从 Kanzi 3.9 迁移到 Kanzi 4

工程模板和插件模板在 Kanzi 3.9 和 Kanzi 4 之间发生了重大变化。Kanzi 4 Kanzi Studio 可以打开并转换 Kanzi 3.9 Kanzi Studio 工程，但其周边的构建结构（CMake 文件、构建脚本、平台配置、插件构建设置）以及默认材质和着色器不会自动迁移。本指南介绍如何将 Kanzi 3.9 应用程序或插件迁移到 Kanzi 4 的模板结构上。

本指南涵盖 工程和构建结构。有关您还必须应用的源代码和 API 更改，请参阅 Kanzi 4.0.0 迁移指南 和 Kanzi 4.1.0 迁移指南。

开始之前

备份您的 3.9 工程，或将其置于版本控制之下。 将 Kanzi 3.9 工程转换为 Kanzi 4 是 就地进行且不可逆的：当您在 Kanzi 4 Kanzi Studio 中打开 3.9 的 <ProjectName>.kzproj 并保存时，Kanzi Studio 会将整个工程（包括每个资源文件）重写为 Kanzi 4 的 <ProjectName>.proj.kzm 格式，并且无法将其转换回去。请始终迁移副本，并保持原始 3.9 工程不变。

请先阅读：已移除的功能

Kanzi 4 移除了 Kanzi 3.9 工程可能依赖的部分功能。如果您的工程依赖以下任何一项，请在开始之前规划其他升级策略，因为本指南不会恢复这些功能：

在 Kanzi 4 中移除

说明

Visual Studio 2017 和 2019 解决方案生成器

generate_cmake_vs2017_solution.bat 和 generate_cmake_vs2019_solution.bat 脚本已被移除。Kanzi 4 仅通过 generate_cmake_vs2022_solution.bat 支持 Visual Studio 2022。

Linux linux_x11_glx_cpp98 平台

C++11 之前的 Linux 平台及其 SConstruct 文件已被移除。Kanzi 4 需要 C++17 工具链。

SCons 构建辅助工具

configs/platforms/common/config.py 和 start_build.py 脚本已被移除。所有平台均使用 CMake 构建。

Kanzi 4 还将所需的最低 CMake 版本从 3.10 提高到 3.25。

选择迁移方式

对于大多数工程，请 迁移您的工程：在 Kanzi 4 Kanzi Studio 中打开并转换工程，然后移植 Kanzi 4 的构建结构和默认资源。请参阅 迁移您的工程。

如果您的工程规模较小或只是一次性原型，请 从头开始：创建新的 Kanzi 4 工程，并将您的内容导入其中。请参阅 从头开始重建。

从头开始时，除了迁移资源之外，您还必须手动重建应用程序结构，包括节点树层次结构、预设件放置、跨预设件绑定以及渲染/合成设置。

Kanzi 3.9 和 Kanzi 4 之间的变化

无论您选择哪种方式，Kanzi 3.9 和 Kanzi 4 之间都存在以下变化：

  • 工程文件格式。 3.9 的根工程文件是 <ProjectName>.kzproj；Kanzi 4 的文件是 <ProjectName>.proj.kzm。Kanzi 4 Kanzi Studio 会在您打开旧工程时对其进行转换（会要求您确认），然后在您保存时写入新格式。该转换不可逆（请参阅 开始之前）。

  • 构建系统。 Kanzi 4 新增了命令行构建包装脚本（build.bat / build.sh）以及解析器概念：cmake/kanzi-bootstrap.cmake 分派器通过 KANZI_RESOLVER CMake 缓存变量，在经典 cmake 解析器（使用本地 Kanzi SDK，为默认选项，最接近 Kanzi 3.9）和 kpm 解析器（Kanzi Package Manager）之间进行选择。

    命令

    作用

    build.bat

    使用 cmake 解析器以 Release 配置进行构建。

    build.bat <config>

    使用 cmake 解析器以指定配置（Debug、Release、Profiling）进行构建。

    build.bat kpm

    使用 kpm 解析器进行构建。

    在 Linux 和 macOS 上，将 build.bat 替换为 ./build.sh。经典解析器使用 KANZI_HOME 环境变量定位本地 SDK，与 Kanzi 3.9 中完全相同。如果您曾在命令行上传入 -DKANZI_ROOT=<path>，请将其重命名为 -DKanzi_ROOT=<path>。

    generate_cmake_vs2022_solution.bat 生成 Visual Studio 2022 解决方案；在 macOS 上，generate_cmake_xcode_ios_project.sh 生成适用于 iOS（Kanzi 4 新增平台）的 Xcode 工程。

  • 插件。 使用 Visual Studio 2022 基于 Kanzi 4 SDK 重新构建您的 Kanzi Engine 插件，然后重新导入。请参阅 迁移 Kanzi Engine 插件。

  • 默认材质和着色器。 Kanzi 4 重构了图形系统，并将默认材质类型和着色器更新为新版 GLSL。转换后的 3.9 工程会保留旧的着色器，而 Kanzi 4 不接受这些着色器。请参阅 迁移材质和着色器。

  • 导出的二进制文件。 您需要在 Kanzi 4 中重新导出 .kzb。请勿重复使用 Kanzi 3.9 的 .kzb。

迁移您的工程

  1. 转换 3.9 工程的副本。 在 Kanzi 4 Kanzi Studio 中，选择 File > Open Project，打开副本的 <ProjectName>.kzproj，确认转换提示，然后保存。Kanzi Studio 会写入 Kanzi 4 的 <ProjectName>.proj.kzm。

  2. 创建一个用于复制文件的供体工程。 在 Kanzi 4 Kanzi Studio 中，使用与您的工程相匹配的模板（例如 Application with Kanzi Engine plugin）以及与您的工程相匹配的材质（例如 High-performance vertex shaders）新建工程。请参阅 创建项目。使用相同的工程名称，以免日后重命名文件。此工程即为供体工程：您在后续步骤中复制的 Kanzi 4 构建文件和默认资源都来自该工程。

  3. 替换构建框架：

    1. 用转换后工程中的文件覆盖供体工程 Application/src 下的 .cpp 和 .hpp 文件。

    2. 删除转换后工程的 Application 文件夹。

    3. 将供体工程的 Application 复制到转换后的工程中。

  4. 重新构建并导入插件。 请按照 迁移 Kanzi Engine 插件 操作。

  5. 替换默认材质和着色器。 保留您的自定义材质，但删除转换后工程中默认的 Materials、Material Types 和 Shaders，并用供体工程中的对应项替换。

  6. 完成。 修复所有无法构建的自定义材质或着色器（请参阅 迁移材质和着色器），应用 C++ API 更改（请参阅 4.0.0 和 4.1.0 迁移指南），然后构建并重新导出 .kzb。

从头开始重建

  1. 使用与您的工程相匹配的模板（例如 Application with Kanzi Engine plugin）以及与您的工程相匹配的材质（例如 High-performance vertex shaders） 新建工程。请参阅 创建项目。此工程包含 Kanzi 4 的构建文件和默认资源。

  2. 引入并导入插件。 将插件源文件（.cpp 和 .hpp）复制到新工程的 src/plugin/src 目录中，然后按照 迁移 Kanzi Engine 插件 操作。

  3. 将您创作的内容 引入 新工程的 Tool_project：包括场景和预设件、导入的资产（3D 资产及其网格数据、图像、字体），以及您创建的所有材质和着色器。保留新工程的默认 Materials、Material Types 和 Shaders — 请勿用 3.9 的默认项覆盖它们。请参阅 共享工程项 和 将 Kanzi Studio 项目合并到 Kanzi 应用程序中。。

    备注

    导入 3D 资产时，Kanzi Studio 会填充 3D Assets 和网格数据目录。如果网格数据未能一并导入，则网格不会重新构建。

  4. 重建节点树。 使用导入的预设件和内容，在 Screen 下重新组装应用程序的层级结构。

  5. 完成。 修复所有无法构建的自定义材质或着色器（请参阅 迁移材质和着色器），应用 C++ API 更改（请参阅 4.0.0 和 4.1.0 迁移指南），然后构建并重新导出 .kzb。

迁移 Kanzi Engine 插件

  1. 列出源文件。 确保所有源文件都已列在对应 CMakeLists.txt （src/plugin 或 src/executable）的 set 命令中。

  2. 使用 Visual Studio 2022 基于 Kanzi 4 SDK 构建插件：将 KANZI_HOME 设置为您的 Kanzi 4 SDK，然后运行 build.bat 或 generate_cmake_vs2022_solution.bat。如果您之前基于其他 SDK 构建过，请先删除构建目录。

  3. 在 Library > Kanzi Engine Plugins 中注册重新构建的插件：删除现有的插件条目，然后右键单击 Kanzi Engine Plugins > Import Kanzi Engine Plugin，并选择重新构建的 DLL。

  4. 将 Preview Build Configuration （位于 Project > Properties 中）设置为您构建插件时所用的配置。

如果您的插件使用了在 Kanzi 4 中发生更改的 Kanzi Engine API（主要涉及渲染、图形和平台），请手动移植插件。请参阅：Kanzi 4.0.0 迁移指南 和 Kanzi 4.1.0 迁移指南。

迁移材质和着色器

Kanzi 4 重构了图形系统，并将默认材质类型和着色器更新为新版 GLSL。转换后的 Kanzi 3.9 工程仍带有旧的默认材质和着色器，它们使用 Kanzi 4 不接受的旧版 GLSL，因此您需要用 Kanzi 4 的默认材质和着色器替换它们。

  • 使用新的默认材质和着色器，切勿使用 3.9 的版本。

  • 将您自己编写的着色器迁移 到 Kanzi 4 GLSL。请参阅 Kanzi 4.1.0 迁移指南 中的着色器迁移步骤以及 设置 OpenGL ES 版本。

  • 修复所有无法构建的自定义材质或着色器。 按上述方法将其着色器迁移到 Kanzi 4 GLSL，或基于 Kanzi 4 默认材质类型重新创建该材质。由于材质是共享的，因此您需要按材质而不是按节点进行修复。

排除问题

  • 材质无法获取，或出现着色器编译错误，例如 ES shaders for SPIR-V require version 310 or higher。这说明您仍在使用 3.9 的默认着色器。请用 Kanzi 4 的着色器替换它们（或迁移 GLSL）。

  • 预览报告未定义的元类，或插件未加载。 插件 DLL 的构建配置与 Preview Build Configuration 不匹配，或者构建插件时 KANZI_HOME 指向了错误的 SDK。请针对正确的 SDK 重新构建并重新导入，并使 Preview Build Configuration 保持一致。

  • 出现字体引擎警告、Font Engine 列表为空（只有 “None”），或出现 “Preview cannot start” / “cannot find a font engine”。 这些都是引擎未能初始化所导致的连带症状，通常是因为材质和着色器无法构建，或 Preview Build Configuration 与重新构建的插件不匹配。请先修复这些问题。引擎初始化后，警告会消失，Font Engine 列表会自动填充可用的引擎（FreeType、iType）；您无需手动选择字体引擎来解决此问题。

各模板说明

基础应用程序

单个源文件（例如 src/basic_application.cpp）会被沿用。没有插件子树。

Kanzi Engine 插件和数据源插件

在 Kanzi 4 中，src/plugin 下的插件子树是自包含的：它有自己的 cmake/ 目录和 packages.json。插件部署使用 Application 目录中的 create_and_deploy_plugin 脚本。请按照 迁移 Kanzi Engine 插件 操作。

Android 更改

Kanzi 4 使用 Android Gradle Plugin 8，并将依赖项版本移至 configs/platforms/android_gradle/gradle/libs.versions.toml。原生构建现在位于 kanzinative Gradle 模块中，并且移除了 Kanzi 3.9 为插件模板生成的每个插件各自的 Gradle 模块。Kanzi 4 还要求 NDK 28.2.13676358 和 CMake 3.25 或更高版本；请将 Gradle 的 CMake 版本设置为 3.30.5，这是 Android SDK 提供的最低版本。请基于此布局重新应用您在 Kanzi 3.9 中的 Gradle 自定义设置，而不要复制旧的 Gradle 文件。请参阅 Kanzi 4.1.0 迁移指南。

另请参阅

Kanzi 4.0.0 迁移指南

Kanzi 4.1.0 迁移指南

创建项目

导入项目

共享工程项

将 Kanzi Studio 项目合并到 Kanzi 应用程序中。