SuperAPI AI 工具集

iwsdk-asset-pipeline

编程与开发

查看项目

更新于 11-17 00:29

技能介绍

用途:该技能面向 IWSDK 1.x(含 1.0.1)WebXR 项目的资源管线,目标平台为 Meta Quest。IWSDK 不会替开发者优化资源:Vite 会原样复制 public/ 下的文件,原 @iwsdk/vite-plugin-gltf-optimizer 已在 0.5 退役,因此模型与纹理需在放入 public/ 之前完成优化。

IWSDK 能加载什么:GLTF 类型(.glb/.gltf,唯一支持的 3D 格式)由 three 的 GLTFLoader 配合 DRACOLoader 与 KTX2Loader 加载;Texture 类型走 TextureLoader,支持 JPG、PNG、WebP,manifest 中的独立 .ktx2 不被支持,KTX2 纹理应嵌入 glTF;HDRTexture 支持 .hdr/.exr;Audio 支持 MP3、WAV、OGG;UIKitML 为 public/ui/.uikitml。清单路径可加载 KHR_draco_mesh_compression、KHR_texture_basisu、KHR_mesh_quantization、EXT_mesh_gpu_instancing、EXT_texture_webp/avif、KHR_texture_transform、KHR_lights_punctual 及各类 KHR_materials_ 等扩展,但不支持 EXT_meshopt_compression(未设置 Meshopt 解码器会报错),而 gltf-transform optimize 默认正是 Meshopt。Draco 解码器与 Basis 转码器在运行时从 unpkg.com 拉取,应用需能访问该域名及 cdn.jsdelivr.net;原生场景加载时单模型上限 64 MiB、合计 256 MiB。

自定义加载器:对由代码放置的资源,可绕过 manifest 直接用 three 的 loader 加载,从而读取 Meshopt 文件与独立 .ktx2,并让解码器全部来自自有域名(Basis 转码器需复制到 public/decoders/basis/)。代价是这些资源不在 manifest 中,编辑器无法放置,也没有优先级、30 秒超时与 AssetLoadError,且需自行释放几何体、材质与纹理。该路径在 IWER 模拟器的 1.0.1 原型中验证过,Quest 实机加载时间尚未验证。

获取与检查:自有或转换资源可经 Blender 导入后导出 GLB(1 单位=1 米、+Y 向上、原点在触地处、朝向 -Z)。Meta 资产库可用 metavr 命令行搜索;IWSDK 自带示例模型来自 jsDelivr 上的 @iwsdk/example-assets@0.4.2,需锁定版本,生产环境建议镜像到 public/ 并设置 VITE_IWSDK_EXAMPLE_ASSET_BASE_URL。下载资源需核对许可证并记录来源,例如 Kenney 为 CC0,Quaternius 新旧包许可不同。可用 check-gltf.mjs 检查可加载性与体积,或用 @gltf-transform/cli inspect 查看完整报告。

优化:使用 npx @gltf-transform/cli optimize 并显式传入 --compress draco(不要保留默认 meshopt)、--texture-compress ktx2(需 KTX-Software 4.4.0+)、按需设置 --texture-size。若代码或动画按名称引用部件,应关闭 --join-named/--flatten。脚本化调用时注意:palette() 会把 UV 写到下一个空闲槽位,可能导致合并材质后渲染发黑或条纹;join() 会跳过蒙皮、带动画、实例化、含 morph target 与 KHR_materials_volume 的节点。

注册与验证:在 src/assets.ts 用 defineAssets 注册,URL 基于 import.meta.env.BASE_URL 构建,显式设置 critical/background/lazy 优先级(未设置按 critical 处理)。完成后运行检查脚本、npm run build 检查产物体积,并在浏览器日志与头戴设备上确认加载时间与帧率。文档还附有常见问题排查表(Meshopt 报错、纹理发白、命名部件消失等)。