Kool资源加载实战:加载glTF模型、纹理并开启阴影映射与环境光遮蔽只需几行代码
Kool资源加载实战:加载glTF模型、纹理并开启阴影映射与环境光遮蔽只需几行代码
kool 是一个用 Kotlin 编写的跨平台 3D 游戏引擎,同时支持 Vulkan / WebGPU / OpenGL,可运行在 Desktop JVM、Android 和浏览器(JS/WASM)上。这篇文章以官方演示项目为准,带你快速完成三件事:加载 glTF/glTF 二进制(.glb)模型、加载纹理与 HDR 环境贴图,以及开启阴影映射与环境光遮蔽(AO),全程只需几行代码。
1. 资源加载的两大入口:Assets 与 ResourceGroup
在 kool 中,所有资源加载都围绕协程(suspend)异步接口展开,主入口是 Assets 和 AssetLoader。
如果你需要批量管理多种资源(模型 + 多张纹理 + HDRI),推荐用 ResourceGroup:它把 texture2d、hdriImage、model 等资源注册成惰性属性,统一调用 loadSequential() 或 loadParallel() 加载,并自动处理资源释放,非常适合新手组织项目资源。
2. 快速加载 glTF 模型:一行 loadGltfModel
glTF 模块位于 kool-core/src/commonMain/kotlin/de/fabmax/kool/modules/gltf/,核心扩展函数是 loadGltfModel,支持 .gltf 与 .glb 两种格式:
val model = Assets.loadGltfModel("assets/fox.glb", modelCfg).getOrThrow()
model.transform.scale(0.01f)
addNode(model)
官方演示 GltfDemo.kt 中实际加载了 Flight Helmet、Fox、Camera 等 8 个模型,并用 async 并发加载,逐个显示加载进度。
GltfLoadConfig:控制加载行为的关键配置
加载选项由 GltfLoadConfig 控制,常用字段包括:
| 配置项 | 作用 |
|---|---|
generateNormals |
模型没有法线时自动生成 |
loadAnimations / applySkins |
是否加载动画与骨骼蒙皮 |
applyMorphTargets |
是否应用形态目标(Morph Target) |
mergeMeshesByMaterial |
按材质合并网格,减少 DrawCall |
materialConfig |
材质与着色器配置(见下文) |
3. 纹理与环境贴图:纹理加载与 PBR 材质
普通 2D 纹理(颜色、法线、粗糙度、AO 贴图等)通过 ResourceGroup.texture2d 或 Assets.loadTexture2d 加载;HDR 环境贴图(IBL 光源)则用 hdriImage 生成 EnvironmentMap。
glTF 模型的 PBR 材质要接入延迟渲染管线时,用 GltfMaterialConfig 指定环境贴图与着色器工厂即可:
val materialCfg = GltfMaterialConfig(
environmentMap = envMap, // HDRI 环境贴图
shaderFactory = GltfDeferredShaderFactory
)
这样模型的金属度/粗糙度等 PBR 属性就会自动与场景光照、阴影和环境光遮蔽联动。
4. 开启阴影映射:createShadowMaps 一行搞定
阴影映射(Shadow Mapping)由 Deferred2Pipeline.kt 中的 Lighting.createShadowMaps 扩展函数一键创建:
val shadows = mainScene.lighting.createShadowMaps(sceneContent, camera)
shadows.forEach { it.addToScene(mainScene) }
- 方向光(Directional)自动使用级联阴影贴图(CascadedShadowMap)
- 聚光灯(Spot)使用
SimpleShadowMap - 点光源暂不支持阴影(代码中有日志提示)
range(光照范围)与 mapSize(贴图分辨率,默认 2048)均可按场景调整。
5. 环境光遮蔽(AO)与延迟渲染管线
把上面所有东西串起来的“胶水”是 Deferred2Pipeline,构造时传入场景内容节点、相机、光照和阴影配置:
deferredPipeline = Deferred2Pipeline(
content = sceneContent,
scene = mainScene,
ibl = envMap,
camera = camera,
lighting = mainScene.lighting,
shadowMapConfig = shadows.toConfig()
)
AO 通道(ComputeAoPass)随管线自动创建,只需一行设置遮蔽半径:
deferredPipeline.aoPass.radius = AoRadius.absoluteRadius(0.2f)
半径定义见 AoRadius。最后把 defaultOutputQuad 加入场景完成输出,即可看到带阴影与 AO 的最终画面。
6. 小结:完整流程清单
- 注册资源:用
ResourceGroup声明模型、纹理与 HDRI 环境贴图 - 加载模型:
Assets.loadGltfModel(path, GltfLoadConfig(...)) - 创建阴影:
lighting.createShadowMaps(content, camera) - 搭建管线:
Deferred2Pipeline+shadowMapConfig - 调 AO:
aoPass.radius = AoRadius.absoluteRadius(...)
完整可运行示例请见 GltfDemo.kt(含模型切换、SSR 开关与相机轨道控制);其他演示代码集中在 kool-demo/src/commonMain/kotlin/de/fabmax/kool/demo/ 目录下,可直接参考学习。
