Kool资源加载实战:加载glTF模型、纹理并开启阴影映射与环境光遮蔽只需几行代码

原创2026-11-16 16:52:391,902 阅读

Kool资源加载实战:加载glTF模型、纹理并开启阴影映射与环境光遮蔽只需几行代码

kool 是一个用 Kotlin 编写的跨平台 3D 游戏引擎,同时支持 Vulkan / WebGPU / OpenGL,可运行在 Desktop JVM、Android 和浏览器(JS/WASM)上。这篇文章以官方演示项目为准,带你快速完成三件事:加载 glTF/glTF 二进制(.glb)模型、加载纹理与 HDR 环境贴图,以及开启阴影映射与环境光遮蔽(AO),全程只需几行代码。

Kool 引擎内置字体纹理资源示例

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. 小结:完整流程清单

  1. 注册资源:用 ResourceGroup 声明模型、纹理与 HDRI 环境贴图
  2. 加载模型:Assets.loadGltfModel(path, GltfLoadConfig(...))
  3. 创建阴影:lighting.createShadowMaps(content, camera)
  4. 搭建管线:Deferred2Pipeline + shadowMapConfig
  5. 调 AO:aoPass.radius = AoRadius.absoluteRadius(...)

完整可运行示例请见 GltfDemo.kt(含模型切换、SSR 开关与相机轨道控制);其他演示代码集中在 kool-demo/src/commonMain/kotlin/de/fabmax/kool/demo/ 目录下,可直接参考学习。

登录后查看全文
kool