mcpField
T
threejs-loaders

threejs-loaders

github.com/akillness开发5256 次安装1 天前更新
代码仓库

关于 threejs-loaders

用于管理 Three.js 资源加载全流程的技能，涵盖获取、解码、缓存和清理。面向构建 3D 场景的开发者，提供加载器配置、进度跟踪、故障处理和资源所有权方面的指导。

主要功能

  1. 01加载模型、纹理和环境资源
  2. 02配置 Draco 与 KTX2 解码器
  3. 03跟踪整体加载进度
  4. 04通过上下文诊断信息处理故障
  5. 05缓存共享资源并克隆场景状态
  6. 06在卸载时释放资源

适用场景

  1. 01在 Three.js 场景中加载 GLB 或 GLTF 模型
  2. 02排查解码器路径、CORS 故障或资源缺失
  3. 03替换资源时避免重复获取和资源泄漏

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/akillness/jeo-skills --skill threejs-loaders

安装后在 Claude Code 中输入/threejs-loaders确认已加载。

附带文件SKILL.toonevals/evals.json

详细介绍

Three.js 加载器

使用此技能处理资源获取/解码生命周期、加载器配置、缓存、进度和清理。模型加载后的处理方式请交由 threejs-animation、threejs-materials、threejs-textures 或 threejs-geometry。

何时使用此技能

  • 加载 GLB/GLTF 模型、纹理、立方体贴图、HDR/EXR 资源或其他 Three.js 格式
  • 配置 Draco 和 KTX2 转码，使路径与部署环境兼容
  • 将基于回调的加载转换为可取消、可观测的功能边界
  • 排查资源缺失、CORS 失败、解码器路径错误、重复获取或资源泄漏

说明

步骤 1：检查部署和资源限制
  1. 确认已安装的 Three.js 版本，并从项目支持的路径导入附加组件，通常为 three/addons/...。
  2. 确定经打包工具/基础路径转换后的资源 URL；不要硬编码会在生产环境中失效的本地 开发路径。
  3. 在添加加载器或解码器之前，确认资源所需的许可、大小预算、压缩、CORS 和运行时支持。
步骤 2：在每条资源管线中只配置一次加载
import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";

const manager = new THREE.LoadingManager();
manager.onError = (url) => console.error(`Failed to load ${url}`);

const draco = new DRACOLoader(manager);
draco.setDecoderPath("/draco/");

const loader = new GLTFLoader(manager);
loader.setDRACOLoader(draco);
const gltf = await loader.loadAsync("/models/product.glb");
scene.add(gltf.scene);

负责配置并复用加载器。首次请求前配置 DRACO/KTX2 解码器；使用浏览器网络面板验证已部署的解码器文件和 MIME 类型。

步骤 3：分离传输、准备和所有权
阶段职责
获取/解码加载器和 LoadingManager
规范化名称验证、缩放/原点策略、材质/动画准备
缓存明确的资源键和共享所有权策略
挂载功能负责场景挂载和每个实例的状态
释放仅释放没有任何活动使用者共享的资源

返回有类型的资源结果，或抛出包含上下文的错误。避免吞掉加载错误并渲染无提示的空场景。仅当使用者对可变性达成一致时，才缓存已解码的共享资源；在进行实例级修改前克隆场景图。

步骤 4：如实处理进度和失败

使用 LoadingManager 获取总体进度，但将字节进度视为可选项，因为服务器可能不提供内容长度。在宿主 UI 中呈现可恢复的加载/错误状态，并在诊断信息中包含失败 URL 和状态上下文。

步骤 5：验证生产环境行为
  • 测试清除缓存后的生产构建，而不仅仅是开发服务器。
  • 测试资源不可用、解码器 URL 失败、响应缓慢和格式不受支持的情况。
  • 根据实际导出的资源，确认 GLTF 动画/模型名称相关假设。
  • 反复挂载/卸载或替换资源；不应累积保留的场景节点或重复获取。

示例

加载 HDR 环境

使用匹配的 HDR/EXR 加载器，然后将纹理交给 threejs-textures/threejs-lighting，以便进行适配渲染器版本的预过滤并管理环境所有权。

加载多个资源

仅当功能必须等待所有资源就绪才能渲染时，才创建 Promise.all 之类的显式 Promise 边界。对于渐进式场景，资源安全独立时应在其到达后立即挂载，并为每项资源保留明确的回退/错误状态。

最佳实践

  1. 复用已配置的加载器和管理器，而不是每次渲染时都创建新的实例。
  2. 将解码器/转码器目录视为需要随应用部署的资源，并对其进行测试。
  3. 将 GLB/GLTF 用作主要模型交换格式；只有确实需要处理相应输入时，才添加旧格式加载器。
  4. 缓存共享的不可变资源，并有意克隆每个实例的场景状态。
  5. 在拆卸时释放解码器和功能拥有的 Three.js 资源。

参考资料

评论

支持 Markdown