rocketbox-avatars-glb + three.js教程:5行代码渲染140个GLB角色

原创2026-11-18 16:47:21344 阅读
文章标签:数据集3D建模游戏开发

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/ → 需要 MeshoptDecoder
  • objects_ktx2/、mobile/ → 需要 MeshoptDecoder + KTX2Loader
  • engine/、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 场景里就能站满整条街 🎬

登录后查看全文
rocketbox-avatars-glb