Blender 新欢 Armory3D - Khamake & Khafile.js
继 Armory Traits 介绍完混入式编程的 5 种类型后，Armory 游戏编程方面基本上算是一只脚跨进大门了，接下来还有更多的内容等着探索。下沉到 Haxe 语言的系统，横着的是 Blender 场景设计与模型打造，甚至是 Armory3D 本身也有许多模块需要深入研究。本文着重介绍其中的 Kha 构建脚本的一些常识。以下 5 种 Armory Traits 扩展将伴随所有的 Armory 游戏项目的开发过程：
1. **haXe** 脚本代码文件；
2. **Nodes** 使用 Logic Node Editor 可视化编程工具定义的节点树；
3. **UI** - User Interface (Canvas trait)，使用 Armory2D 用户界面编辑进行可视化编辑；
4. **Bundled** Armory Engine 预定义 Haxe 脚本，是 `Trait` 类型的扩展；
5. **Wasm** 使用 WebAssembly 字节码程序；
# ✨ 源文档 https://github.com/Jeangowhy/opendocs/blob/main/Haxe.md
🐥 Khamake & khafile.js
* [khafile.js](https://github.com/Kode/Kha/wiki/khafile.js)
* [Third Party Libraries|Libraries](https://github.com/Kode/Kha/wiki/Third-Party-Libraries|Libraries)
* [System Defines](https://github.com/Kode/Kha/wiki/System-Defines)
* [Profiling](https://github.com/Kode/Kha/wiki/Profiling)
* [Managing Your Assets](https://github.com/Kode/Kha/wiki/Managing-Your-Assets)
Kha 是一套 API 或称为一个开发库，它使用的构建工具称为 **khamake**，以及一个着色器交叉编译器 **Krafix**，使其能够支持多个图形 API。支持平台包含：Web, Mobile, Desktop, and Consoles，使用 OpenGL, WebGL, DirectX, Vulcan, 以及 Metal 等图形 APIs。
Kha 编译得到目标程序程序是 targets，最典型就是 C++ ( with Kore ), Krom, Web, 和 HashLink (HL)。
Blender 中执行 Armory3D 构建时，引擎插件会将所有资源、着色器、纹理等等都存放在 compiled 目录下，最后打包到输出目录，主要是 krom 和 krom-resources 两个目录。构建脚本 khafile.js 也自动生成。而手动执行 Kha 构建时，就需要自动处理，包括配置 khafile.js 脚本，当然可以调用 khamake 生成。为了方便调用 Khamake，可以创建一个 kmake.bat 批处理文件：
# Kha init
node.exe C:\HaxeToolkit\armsdk\Kha\make --init
# kmake.bat
node.exe C:\HaxeToolkit\armsdk\Kha\make %*
以下是 Armory 插件运行时的基本操作，操作包括：
1. 导出内嵌在 .blend 内部的资源文件；
2. 调用 cmft - cubemap filtering tool 生成纹理图像 LOD 分级细节贴图；
3. 期间会在 compiled\Assets 和 Shaders 目录下生成各种默认配置的资源、着色器程序；
Armory 运行时会自动生成 khafile.js 构建脚本，脚本中使用到的对象类型定义在 Kha 源代码中。就脚本中的 `Project` 对象来自源代码：
armsdk\Kha\Tools\khamake\src\Project.ts
各个方法说明如下：
使用 `Project()` 方法注册一个工程标识，格式为：name_version。
使用 `addLibrary("/armsdk/armory")` 等等引入模块。
使用 `addAssets()` 方法添加资源引用。
使用 `addParameter()` 给 Haxe 添加编译参数设置，比如 addParameter('-main Main')。
使用 `addDefine('arm_physics')` 添加符号定义来启用相应模块或者条件编译，这里添加物理引擎模块。
所有 `rp_` 前缀的符号定义基本都与 Render Path 功能相关。
其中 `js-es` 符号用来指定转译得到的 ECMAScript，即 JavsScript 版本号。
使用 `resolve(project)` 替换旧版本 Kha 脚本的 return 方式。
模块默认位于 Libraries 目录，project.localLibraryPath 属性可以指定模块目录。
构建脚本中经常使用 `addParameter()` 告诉 Haxe 编译时调用 macro 函数。Haxe 初始化宏是一种在命令行中调用宏的方式，[Initialization Macros] 命令行格式 `--macro callExpr(args)`。它用来向编译器注册一个函数，使其在宏上下文创建后得到调用，比如，keep() 就是一个宏初始化调用。宏初始化必需在 `--main` 参数之前指定。
如果 `--macro` 调用的是一个 plain identifier，就会在 Haxe Standard Library 中的`haxe.macro.Compiler` 内定位这个标识，这里定义多个非常有用的初始化宏：
haxe\std\haxe\macro\Compiler.hx
比如，`include` 初始化宏在编译时用来引入整个包，可以递归地处理引入，当然也可以自定义宏：
--macro include('some.pack', true)
--macro some.Class.theMacro(args)
由于所有宏共享相同的 [Macro Context]，初始化宏可以设置其他宏用作配置的静态字段的值。
1. `Compiler.include` Includes all modules in package `pack` in the compilation.
2. `Compiler.keep` Marks types or packages to be kept by DCE (Dead Code Elimination).
官方提供的 Armory Examples Browser 项目就是一个 Haxe Web 应用，配置中就调用了自定义宏。当然，Haxe 开发 Web 应用，体验上远不及 React/Vue/Angular 等更现代的组件式 Web 开发框架。Haxe 提供的 js 模块设计上相当于 jQuery 时代的水平，需要调用 Document API 构建 HTML。https://github.com/armory3d/armory_examples_browser
BG-36's Tutorials - SaveLoadMechanism 教程演示了 Haxe 代码如何与 UI 交互。
https://github.com/BlackGoku36/armory-tutorial-download/tree/master/SaveLoadMechanism
Kha 构建 HTML5 或 Flash 应用时，如果有 .wav 等等资源文件，就需要指定 ffmpeg 工具来转换格式。声波文件在 HTML5 平台中需要转换为 .ogg 文件，在 Flash 平台中转换为 .mp3 文件，优化文件大小。
node Kha/make html5 --ffmpeg "/path/to/ffmpeg.exe"
khamake 期待的资源文件格式如下，其它格式资源通过 Assets.blobs 作为 Blob 对象访问：
01. **images**: png, jpg, hdr
02. **sounds**: wav (sample rate: 44100Hz 16 bit)
03. **videos**: mp4
04. **fonts**: ttf
资源一般使用 assets 目录，但不强制使用此目录，可以使用多个资源目录。
假设 assets 资源目录包含文件如下：
在构建脚本中添加引用后，就可以通过 `Assets.types.nameOfAsset` 这样的语法来读取资源到内存中。比如，读取以上的图像资源就是 kha.Assets.images.map1_tiles 或者 map2_tiles，目录使用下划线分隔。已经有对应分类的资源就可以相应的分类访问，无分类的资源就作为大二进制数据对象 `Assets.blobs`。
但是注意，数据文件经过处理后，目录结构被碾平，假设以上两个目录中在同同名两个文件，如 a.dat，那么 kha.Assets.blobs.a_dat 只能访问到其中一个数据文件，为了解决这个问题，Kha 提供了路径映射，生成的代码保持目录结构，以访问 map1_a_dat 和 map2_a_dat 两个数据资源：
不要创建名称为 Haxe 关键字的文件，如 default.png 就不好，应该用 `_default.png` 这样的名称。因为在 Assets 中显示的资源名称是使用输出资源目录的 macro 和 json 文件导入的，所有资源命名必须符合变量、函数的命名规则。资源导出目标为 `<build target>-resources`，比如 Krom 导出方式，资源目录就是 krom-resources 目录。
构建脚本 khafile.js 中的其它配置参考：
