Web 图形与 3D / 系统课时
交付可切换动作的角色展示页
交付可切换动作的角色展示页
完成一个可以直接部署的 Three.js 角色验收页:页面展示两个骨骼角色、动作列表、暂停与继续、加载进度和资源统计,并能主动卸载、失败重试。最后通过生产构建检查压缩模型、纹理与解码器的访问路径。
学习目标
- 将压缩 GLB、KTX2 纹理及其解码器接入 Vite 页面。
- 用共享动画片段和独立 Mixer 实现双角色动作控制。
- 验证失败重试、资源释放和子路径部署的实际行为。
准备资源与页面
使用 Node.js 20.19+ 或 22.12+、npm 和支持 WebGL 2 的浏览器。准备 hero.glb:它应包含可显示的蒙皮网格和至少两段动作,例如 Idle、Walk。几何体可以采用 Draco 或 Meshopt 压缩;如使用 KTX2,纹理必须在导出资产时已编码并正确引用。加载器只负责解码,不会自动压缩图片或 GLB。
在 macOS、Linux 或 WSL 的 Bash 中建立 Vite 原生 JavaScript 项目,并复制 Three.js 自带的解码文件:
npm create vite@latest hero-preview -- --template vanilla
cd hero-preview
npm install
npm install three
mkdir -p public/models public/basis public/draco
cp -R node_modules/three/examples/jsm/libs/basis/. public/basis/
cp -R node_modules/three/examples/jsm/libs/draco/. public/draco/预期结果:项目包含 index.html、src/main.js、public/models/、public/basis/ 和 public/draco/;安装过程没有依赖错误。将已制作的模型放到 public/models/hero.glb,若资产依赖外部纹理,保留与 GLB 内 URI 一致的相对路径。
将根目录的 index.html 完整替换为:
<!doctype html>
<html lang='zh-CN'>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1'>
<title>角色动作验收</title>
<style>
body { margin: 0; background: #eef2f6; color: #263648; font: 16px system-ui; }
main { max-width: 1040px; margin: 20px auto; padding: 0 16px; }
#view { width: 100%; height: 440px; border-radius: 12px; overflow: hidden; }
.controls { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; }
button, select { padding: 8px 12px; }
</style>
</head>
<body>
<main>
<h1>角色动作验收</h1>
<div id='view' aria-label='两个角色的三维预览'></div>
<p id='status' role='status'>等待加载</p>
<p id='info'>资源信息尚未加载</p>
<div class='controls'>
<label>角色 A 动作 <select id='clips' disabled></select></label>
<button id='pause' disabled>暂停 A</button>
<button id='release' disabled>卸载模型</button>
<button id='retry' disabled>重新加载</button>
</div>
</main>
<script type='module' src='/src/main.js'></script>
</body>
</html>生效效果:页面上方是固定高度的预览区;下方状态、动作下拉框和控制按钮分别承担进度反馈、切换、暂停、卸载及重试职责。
连接加载器与独立动作实例
资源加载成功后,gltf.scene 是共享模板,gltf.animations 是可复用片段;每个可动角色必须由 SkeletonUtils.clone() 单独克隆骨骼层级,再建立自己的 AnimationMixer。几何体、材质与纹理可以共享,但不能为两个角色共用同一个 Mixer。

将 src/main.js 完整替换为下列主示例。这里同时注册 Draco、Meshopt、KTX2 解码支持,具体会使用哪种解码路径由资产中声明的 glTF 扩展决定:
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
const $ = (selector) => document.querySelector(selector);
const view = $('#view');
const status = $('#status');
const info = $('#info');
const clips = $('#clips');
const pause = $('#pause');
const release = $('#release');
const retry = $('#retry');
const base = import.meta.env.BASE_URL;
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.outputColorSpace = THREE.SRGBColorSpace;
view.appendChild(renderer.domElement);
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf5f7fa);
scene.add(new THREE.HemisphereLight(0xffffff, 0x788596, 2));
const light = new THREE.DirectionalLight(0xffffff, 3);
light.position.set(3, 5, 4);
scene.add(light);
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(0, 1.5, 8);
camera.lookAt(0, 1, 0);
const draco = new DRACOLoader().setDecoderPath(`${base}draco/`);
const ktx2 = new KTX2Loader()
.setTranscoderPath(`${base}basis/`)
.detectSupport(renderer);
const loader = new GLTFLoader()
.setDRACOLoader(draco)
.setKTX2Loader(ktx2)
.setMeshoptDecoder(MeshoptDecoder);
let asset = null;
let actors = [];
let generation = 0;
// 模板资源由所有实例共享;只在全部实例移除后释放。
function disposeTemplate(root) {
const geometries = new Set();
const materials = new Set();
const textures = new Set();
root.traverse((node) => {
if (node.isSkinnedMesh) node.skeleton.dispose();
if (node.geometry) geometries.add(node.geometry);
const items = Array.isArray(node.material)
? node.material : node.material ? [node.material] : [];
for (const material of items) {
materials.add(material);
for (const value of Object.values(material)) {
if (value?.isTexture) textures.add(value);
}
}
});
textures.forEach((texture) => texture.dispose());
materials.forEach((material) => material.dispose());
geometries.forEach((geometry) => geometry.dispose());
}
function clearAsset() {
for (const actor of actors) {
actor.mixer.stopAllAction();
actor.mixer.uncacheRoot(actor.root);
actor.root.traverse((node) => {
if (node.isSkinnedMesh) node.skeleton.dispose();
});
scene.remove(actor.holder);
}
actors = [];
if (asset) disposeTemplate(asset.scene);
asset = null;
}
function playClip(actor, clip) {
actor.action?.stop();
actor.action = actor.mixer.clipAction(clip);
actor.action.reset().play();
}
async function loadAsset() {
const current = ++generation;
clearAsset();
clips.disabled = pause.disabled = release.disabled = retry.disabled = true;
clips.replaceChildren();
info.textContent = '正在读取资源信息';
status.textContent = '开始加载';
try {
const gltf = await loader.loadAsync(`${base}models/hero.glb`, (event) => {
if (current !== generation) return;
status.textContent = event.total > 0
? `下载中 ${Math.round(event.loaded / event.total * 100)}%`
: `下载中 ${Math.round(event.loaded / 1024)} KiB(总量未知)`;
});
if (current !== generation) {
disposeTemplate(gltf.scene);
return;
}
asset = gltf;
if (gltf.animations.length < 2) {
throw new Error('GLB 至少需要两段 AnimationClip');
}
const bounds = new THREE.Box3().setFromObject(gltf.scene);
if (bounds.isEmpty()) throw new Error('GLB 不含可显示的网格');
const center = bounds.getCenter(new THREE.Vector3());
const size = bounds.getSize(new THREE.Vector3());
const scale = 2 / Math.max(size.y, 0.01);
// 克隆骨骼,但共享几何材质;使用外层组调整位置,避免覆盖根节点动画。
for (const x of [-1.5, 1.5]) {
const root = SkeletonUtils.clone(gltf.scene);
const normalizer = new THREE.Group();
normalizer.scale.setScalar(scale);
normalizer.add(root);
const holder = new THREE.Group();
holder.position.set(x - center.x * scale, -bounds.min.y * scale,
-center.z * scale);
holder.add(normalizer);
scene.add(holder);
actors.push({
root, holder, mixer: new THREE.AnimationMixer(root), action: null
});
}
gltf.animations.forEach((clip, index) => {
const option = document.createElement('option');
option.value = String(index);
option.textContent = `${clip.name || `动作 ${index + 1}`} (${clip.duration.toFixed(2)} 秒)`;
clips.appendChild(option);
});
playClip(actors[0], gltf.animations[0]);
playClip(actors[1], gltf.animations[1]);
clips.value = '0';
let meshes = 0;
let triangles = 0;
gltf.scene.traverse((node) => {
if (!node.isMesh) return;
meshes++;
const geometry = node.geometry;
triangles += Math.floor(
(geometry.index?.count ?? geometry.attributes.position?.count ?? 0) / 3
);
});
info.textContent = `hero.glb|动作 ${gltf.animations.length}|实例 2|`
+ `模板网格 ${meshes}|模板三角面约 ${triangles}`;
status.textContent = '加载完成';
clips.disabled = pause.disabled = release.disabled = false;
pause.textContent = '暂停 A';
} catch (error) {
if (current !== generation) return;
clearAsset();
status.textContent = `加载失败:${error.message}`;
retry.disabled = false;
}
}
clips.addEventListener('change', () => {
if (!asset || !actors[0]) return;
playClip(actors[0], asset.animations[Number(clips.value)]);
pause.textContent = '暂停 A';
});
pause.addEventListener('click', () => {
const action = actors[0]?.action;
if (!action) return;
action.paused = !action.paused;
pause.textContent = action.paused ? '继续 A' : '暂停 A';
});
release.addEventListener('click', () => {
++generation;
clearAsset();
clips.disabled = pause.disabled = release.disabled = true;
retry.disabled = false;
status.textContent = '模型已卸载,可以重新加载';
info.textContent = '实例 0';
});
retry.addEventListener('click', loadAsset);
const clock = new THREE.Clock();
renderer.setAnimationLoop(() => {
const delta = Math.min(clock.getDelta(), 0.05);
for (const actor of actors) actor.mixer.update(delta);
renderer.render(scene, camera);
});
const observer = new ResizeObserver(() => {
const width = Math.max(view.clientWidth, 1);
const height = Math.max(view.clientHeight, 1);
camera.aspect = width / height;
camera.updateProjectionMatrix();
renderer.setSize(width, height);
});
observer.observe(view);
// 离开整页时释放渲染器和解码工作线程;保留 BFCache 页面以便恢复。
window.addEventListener('pagehide', (event) => {
if (event.persisted) return;
++generation;
clearAsset();
renderer.setAnimationLoop(null);
observer.disconnect();
draco.dispose();
ktx2.dispose();
renderer.dispose();
});
loadAsset();预期结果:成功时状态显示“加载完成”,两个角色位于画面左右两侧,下拉框列出 GLB 内实际动作名称和时长;角色 A 的切换与暂停不会改变角色 B 的播放。若 GLB 使用根位移动画或非标准朝向,应先在资产端统一朝向、尺度及动作根节点,再重新检查镜头构图。
验证失败路径与释放边界
先将 A 切换到 Walk,点击“暂停 A”:A 应停在当前姿势,B 仍持续动作;点击“继续 A”后 A 恢复。这验证的是两个独立 Mixer,而非仅有两份可见网格。
再点击“卸载模型”,两个实例应从场景消失;随后点“重新加载”,动作列表和角色应重新出现。代码先停止并注销每个 Mixer、移除克隆骨骼,最后才对共享模板的几何体、材质和纹理调用 dispose()。如果在卸载其中一个角色时就释放共享材质,另一个角色可能出现贴图丢失或渲染异常。
故障验证时,将 hero.glb 暂时改名再刷新页面:状态应显示加载失败,动作和暂停按钮保持禁用。恢复文件名,点击“重新加载”应恢复正常。下载百分比只反映浏览器报告的传输进度,并不代表 Draco、Meshopt 或 KTX2 已完成解码;当服务端未提供总长度时,页面改为显示已下载 KiB。
构建生产包并逐项验收
在项目根目录运行开发服务,再用浏览器访问终端输出的本地地址:
npm run dev预期结果:浏览器显示两个角色、动作列表、状态和资源信息。npm run dev 会持续运行,构建步骤应在另一个终端执行。
假设目标部署路径是 /showcase/,用同样的基路径构建和预览:
npm run build -- --base=/showcase/
npm run preview -- --base=/showcase/预期结果:构建命令成功生成 dist/,预览服务启动;访问预览地址下的 /showcase/ 路径,网络面板应能成功读取 /showcase/models/hero.glb 以及实际需要的 /showcase/basis/ 或 /showcase/draco/ 文件。<PORT> 以终端显示的端口为准。正式服务器必须将 /showcase/ 映射到构建产物并保留其资源层级。
| 验收项 | 通过条件 |
|---|---|
| 压缩资源 | GLB、需要的 KTX2 与解码器请求均成功,无 404、CORS、解码错误 |
| 动作切换 | 下拉框至少两项,切换 A 后动作实际变化 |
| 实例隔离 | 暂停 A 不影响 B 的动作进度 |
| 异常重试 | 模型 404 时出现错误信息,恢复后可以重载 |
| 资源卸载 | 两个角色消失,重载正常,重复 5 次无持续增长的 GPU 资源趋势 |
| 生产部署 | /showcase/ 下刷新页面和重新加载模型均成功 |
用浏览器开发者工具的 Network 面板查看请求及实际传输体积,用 Performance 或 Memory 工具观察多次卸载和加载后的变化。单次 GPU 内存数值受驱动缓存和垃圾回收影响,不应把“卸载后立即归零”当作通过条件。只有上述六项都通过,展示页才可作为后续资产更新的回归验收入口。