02：快速掌握kanzi的文件管理

在kanzi安装完成后，系统会创建工作区目录，如D:\KanziWorkspace3_9。在D:\KanziWorkspace3_9中，文件夹结构如下：

打开 Kanzi Studio，在启动时的窗口点击

。选择创建工程的路径。根据需求在

选择工程类型。随后点击Create即可创建kanzi工程。

创建后的

如图所示：

    会创建：

适合要用 C++ / Kanzi Engine API 写逻辑的应用。

会创建：

会创建：

创建基于 Kanzi Android framework 的工程（含 Gradle 工程），用于 Android 目标平台。

会创建：

kanzi工程的文件结构如图所示：

如果创建kanzi工程时，只选择

模板（只做渲染，不带引擎应用），则

有 Application 目录，因为该类型项目不包含应用程序代码，只用于资源和场景编辑。

Tool_project 目录中包含 UI 工程和资源文件，是导出 kzb 的来源。这些目录在 Kanzi Studio 中对应 Library 面板下的 “Resource Files”，Studio 会自动与磁盘目录同步。其中主要包含这些内容：

当用Application、Application with data source plugin、Application with Kanzi Engine plugin的kanzi模板创建工程时，会自动生成 Application 目录。有应用程序代码开发相关使用者需要了解Application中的这些内容：

是 Kanzi Studio 项目的二进制打包结果，运行 Kanzi 应用必须先把项目导出为 kzb。导出的kzb文件默认放在<ProjectName>/Application/bin，或你在 Project > Properties > Binary Export Directory 里设置的目录。Kanzi 会把 kzb 中的内容加载到内存和 GPU，需要渲染时再使用这些资源。

文件

.kzb.cfg 文件的主要作用是列出并配置应用要加载的 kzb 文件，相当于“kzb 清单/配置文件”。

kzb 的内容和大小取决于项目以及导出配置，一般会包含：

：

使用菜单 File > Export > Export KZB 导出主 kzb。

Screen 节点是否导出到 kzb 会影响该 kzb 能否作为启动 kzb 使用

主题资源包是只包含某个 Theme 资源的 kzb，用于减小主 kzb、按需加载或在有限存储/内存下切换主题。

烘焙主题就是把 Theme 选择在导出时固化进 kzb，使节点直接引用最终资源，从而换取更低内存和更好性能，但失去在不加载新 kzb 的前提下自由切换主题的能力。

  当 Theme Group 启用

并使用 “Export Baked Theme Binaries” 导出时，

可以

：在 Project > Properties > Binary Export 中配置导出行为（如网格优化、图片处理、着色器源码导出等）。对于不需要的节点或资源，可在其 Properties 中启用 "Disable KZB Export" 属性，将其从 kzb 中排除。

当使用Export as KZB Player for Windows方法导出kzb后，生成的应用默认位于Tool_project\Application Player文件夹中，有 exe 文件，双击即可在 Windows 上运行。如图所示：

exe 文件运行失败常见原因：缺少运行时依赖库：需要安装 Microsoft Visual C++ 或 Java 插件路径问题：使用 Java 插件时，需将 JDK 的 bin 和 bin/server 目录加入 PATH 环境变量。

2.1 Kanzi 引擎启动时自动查找 application.cfg

2.2 解析配置文件获取 BinaryName 值

2.3 加载指定路径的 KZB 文件

2.4 反序列化二进制资源到内存

3. 加载流程2：

3.1  或在 C++ Application::onConfigure 中：configuration.binaryName = "my_application.kzb";    

3.2 Kanzi 运行时初始化

3.3 创建 Application 实例

3.4 调用 onConfigure() ← 开发者可在此设置 binaryName

kza 是 kzb 的 XML 版本，Kanzi 可以在导出 kzb 时，同时生成一个 .kza 文件，它是同一项目内容的 XML 形式表达，用于查看和分析。与 kzb 内容对应，只是以 XML 形式存储项目中的节点属性等，用于阅读和比较，而不是运行时加载。

KZA文件导出方法

即可在导出kzb文件时同时导出kza文件，kza文件与kzb文件同目录。

：当在kanzi studio中的Screens/Screen/RootPage/Viewport 2D/下添加了一个Text Box 2D节点

导出kza的XML文件中，可以清楚的看到节点节点的基本信息以及属性。描述了这个文本框节点，显示 "Hello world"，字体大小 36，宽度 400，位置 (317, 321)，水平内边距 20，垂直内边距 10。

如下图所示：

application.cfg 是 Kanzi 应用的配置文件，用来在

的情况下，设置应用启动和运行时的一系列参数。当你启动 Kanzi 应用时，应用会根据application.cfg中的参数配置你的应用。

在工程对应目录创建或编辑 application.cfg，按“键 = 值”的形式写入配置项。当application.cfg不存在/配置项缺失时，Kanzi引擎会使用系统默认配置/C++代码中Application::onConfigure设置的值。

SurfaceClientAPI = "gl"：指定渲染使用 OpenGL 作为图形 API。

GraphicsContextAPI = "wgl"：在 Windows 上使用 WGL 作为 OpenGL 上下文创建方式。

FontEngine = "freetype"：启动时加载 FreeType 字体引擎 来渲染文字（这是默认字体引擎）。SurfaceColorSpace = "srgb"：把渲染表面的颜色空间设为 sRGB，配合 线性颜色工作流 使用，由 Kanzi 负责线性↔sRGB 转换。

ModuleNames = "kztargetpreview"：启动时加载名为 kztargetpreview 的插件模块（ModuleNames 用来列出要加载的插件名）。

典型的 8‑8‑8 颜色格式（每个颜色通道 8 位），提高颜色精度；如果想让平台自己决定，可以把这些值设为 "unspecified"。

application.cfg的常用配置包括：

LogOpenGLInformation：启动时打印 GL vendor/renderer/version 等信息，便于确认 GPU 和驱动环境。

PerformanceInfoLevel：控制是否显示 FPS/完整性能 HUD，用于调试和分析性能瓶颈。

MaximumFPS：限制最大帧率（0=不限制，默认 60）。常见值 30/60，按性能消耗或流畅度需求选择。

GraphicsLoggingEnabled：输出每个图形 API 调用，适合深入调试渲染问题（但会明显影响性能）。

LogOpenGLExtensions：启动时打印支持的图形扩展列表，方便确认硬件特性。

LogOpenGLInformation：打印基础 GL 信息（厂商、渲染器、版本、着色器语言版本）。

SurfaceBitsRed/Green/Blue/Alpha：设置颜色和 Alpha 通道的位数（如 8-8-8-8），在画质和带宽/显存之间做权衡。

SurfaceColorSpace：选择输出色彩空间（如 "srgb"线性工作流，自动转换、"legacy"传统非线性工作流，无自动转换、"passthrough"直通模式，需自定义转换），决定 Kanzi 是否做线性工作流和自动 gamma 转换。

DeploymentQueueBudget：限制每帧在主线程用于“把资源部署到 GPU”的时间预算，平衡加载速度和 UI 流畅度。

LoadingThreadCount：设置后台加载资源使用的线程数，利用多核 CPU 加快纹理/网格/Shader 等从磁盘到内存的加载。（0代表禁用并行，大于0代表后台线程数）

MaxPendingResources：限制“已由加载线程处理但尚未部署到 GPU”的资源数量上限，在加载速度和峰值内存占用之间做平衡。