rocketbox-avatars-glb + three.js教程:5行代码渲染140个GLB角色
rocketbox-avatars-glb + three.js教程:5行代码渲染140个GLB角色
rocketbox-avatars-glb 是一个开源免费的 3D 角色资产库,收录 140 个带骨骼的 GLB 角色模型(商务人士、警察、消防员、军人、成人与儿童,以及马、牛、鸡、狗等农场动物)。搭配 three.js 的 GLTFLoader,只需 5 行核心代码就能让角色出现在屏幕上——不需要 3D 引擎,也不需要建模软件。
先克隆仓库,把模型文件拉到本地:
git clone https://gitcode.com/hf_mirrors/codepawl/rocketbox-avatars-glb
rocketbox-avatars-glb 是什么:140个角色共用一套骨骼
- 🧍 140 个角色:覆盖商务、医疗、警务、消防、军事、建筑、飞行员、运动等职业,加上成人/儿童与农场动物
- 🦴 共用骨骼:所有人物使用同一套
Bip01骨架(80 根骨骼),一段动画可以直接驱动全部角色,无需重定向 - 😊 175 个面部 blendshapes:包含 viseme 口型、FACS 与 ARKit 通道,做说话、表情动画开箱即用
- 📊 MIT 许可:可免费商用,许可文本见 LICENSES.md
30秒选对GLB文件:6个文件夹快速对照
同一个角色在仓库里准备了 6 个"版本",按场景挑文件夹即可,无需任何转换:
| 文件夹 | 大小 | 内容 | 适用场景 |
|---|---|---|---|
| objects/ | 268.4 MB | meshopt 压缩 + WebP 贴图 | three.js / Babylon.js 通用网页 |
| objects_ktx2/ | 379.3 MB | meshopt + KTX2 压缩贴图 | WebGL / WebGPU 游戏,显存占用低 |
| lods/ | 254.6 MB | 50% / 20% / 6% 三档减面 | 距离 LOD、大量人群场景 |
| mobile/ | 78.9 MB | 25% 三角面 + 512px KTX2 | 手机、低配笔记本 |
| engine/ | 3.97 GB | 无压缩、无量化 | Blender 与桌面引擎 |
| collision/ | 0.4 MB | 凸包碰撞体 | Rapier、Jolt、PhysX 等物理 |
各档位的解码要求(详见 README.md):
objects/→ 需要MeshoptDecoderobjects_ktx2/、mobile/→ 需要MeshoptDecoder+KTX2Loaderengine/、collision/→ 纯 glTF,GLTFLoader直接加载,什么都不用配
5行核心代码:用three.js渲染第一个GLB角色
下面的示例用 engine/ 档的纯 glTF 文件,零解码器配置,最快上手:
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(55, 2, 0.1, 50);
camera.position.set(1.4, 1.3, 2.2);
camera.lookAt(0, 0.9, 0);
const renderer = new THREE.WebGLRenderer({ antialias: true });
scene.add(new THREE.HemisphereLight(0xffffff, 0x445566, 3));
// 核心 5 行:创建加载器 → 加载 GLB → 加入场景 → 建相机 → 启动渲染循环
new GLTFLoader().load('engine/business-female-01/business-female-01.glb', (gltf) => {
scene.add(gltf.scene);
renderer.setAnimationLoop(() => renderer.render(scene, camera));
});
换成任何角色都一样,比如 objects/bird-duck-male-01/ 下的鸭子,只需要改文件路径。
加载 web 档:给加载器挂上解码器
想省流量就改用 objects/(中位数仅 2.4 MB/个),多挂一个解码器即可:
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
const gltf = await loader.loadAsync('objects/business-female-01/business-female-01.glb');
渲染大量角色:LOD、KTX2 与碰撞体技巧
场景里要摆几百个角色时,三招就能保住帧率:
- ⚡ 远距离角色换 LOD:把路径换成 lods/ 下的
*_lod2.glb(20% 面)或*_lod3.glb(6% 面)。实测 lod2 档位中位数仅 0.6 MB,帧耗时 0.6 ms - 🎮 显存敏感用 KTX2:
objects_ktx2/的贴图在 GPU 上保持块压缩,实测显存占用从 106.9 MiB 降到 18.9 MiB(中位数):
const ktx2 = new KTX2Loader().setTranscoderPath('basis/').detectSupport(renderer);
const loader = new GLTFLoader().setKTX2Loader(ktx2).setMeshoptDecoder(MeshoptDecoder);
const gltf = await loader.loadAsync('objects_ktx2/business-female-01/business-female-01.glb');
- 🛡️ 物理碰撞用凸包:collision/ 里每个角色都有一个只有约 3 KB 的凸碰撞体(如
collision/business-female-01/business-female-01_collision.glb),可直接喂给 Rapier、Jolt、PhysX
由于所有人物共用 Bip01 骨架,你给一个角色做的走跑跳动画,可以直接套用到其余 139 个人物上;面部驱动同理,175 个 blendshape 全库统一。
用 metadata.jsonl 快速查参数
每个角色的三角面数、骨骼数、blendshape 数和各档位文件大小,都记录在 metadata.jsonl 里(每行一个角色)。以 business-female-01 为例,关键字段如下:
| 字段 | 含义 | 示例值 |
|---|---|---|
triangles |
三角面数 | 8966 |
bones |
骨骼数 | 80 |
blendshapes |
面部混合变形数 | 175 |
files |
各档位文件路径 | web / ktx2 / lod1~3 / mobile / engine / collision |
web_bytes |
web 档文件字节数 | 2420540 |
批量处理时也可以直接读 data/ 下的 4 个 parquet 分片(如 data/train-00000-of-00004.parquet),里面嵌入了网格数据(Mesh)和缩略图(Image)。另外 preview/ 下有 15 份轻量副本,适合快速浏览。
MIT许可:免费商用与引用说明
- 全部文件遵循 MIT 许可(源自 Microsoft Rocketbox Avatar Library),免费商用
- 许可全文见 LICENSES.md,分发副本时请随附该文件
- 用于学术研究时,建议引用:Gonzalez-Franco et al., The Rocketbox library and the utility of freely available rigged avatars, Frontiers in Virtual Reality, 2020
常用路径速查
| 路径 | 说明 |
|---|---|
| README.md | 完整说明、性能实测数据与加载示例 |
| metadata.jsonl | 140 个角色的元数据(每行一条) |
| objects/ | web 档 GLB(meshopt + WebP) |
| lods/ | 三档减面 LOD 文件 |
| mobile/ | 移动端优化档 |
| engine/ | 无压缩版,供 Blender 与桌面引擎 |
| collision/ | 凸包碰撞体 |
| LICENSES.md | MIT 许可文本 |
140 个角色、一套骨骼、六档文件——把路径换一换,你的 three.js 场景里就能站满整条街 🎬