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 自带的解码文件:

bash
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 完整替换为:

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 扩展决定:

js
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。

构建生产包并逐项验收

在项目根目录运行开发服务,再用浏览器访问终端输出的本地地址:

bash
npm run dev

预期结果:浏览器显示两个角色、动作列表、状态和资源信息。npm run dev 会持续运行,构建步骤应在另一个终端执行。

假设目标部署路径是 /showcase/,用同样的基路径构建和预览:

bash
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 内存数值受驱动缓存和垃圾回收影响,不应把“卸载后立即归零”当作通过条件。只有上述六项都通过,展示页才可作为后续资产更新的回归验收入口。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

交付可切换动作的角色展示页

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通