08｜模型加载

scene.gltf          # JSON 主文件（场景描述）
scene.bin           # 二进制数据（顶点、索引）
texture.png         # 纹理文件

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'

/**
 * 基础模型加载
 *
 * @param url - 模型文件路径（.glb 或 .gltf）
 * @param callback - 加载完成回调，接收 GLTF 对象
 */
const loader = new GLTFLoader()
loader.load('/models/suzanne.glb', (gltf) => {
  scene.add(gltf.scene)
})

/**
 * createLoadingManager — 创建加载管理器
 *
 * 统一管理所有资源的加载进度。
 * LoadingScreen 是项目封装的全屏加载动画组件。
 */
function createLoadingManager() {
  const manager = new THREE.LoadingManager()
  const screen = new LoadingScreen({ title: '加载中…' })
  screen.show()

  manager.onLoad = () => {
    console.log('所有资源加载完成')
    screen.hide()
  }

  manager.onProgress = (url, itemsLoaded, itemsTotal) => {
    const progress = itemsTotal > 0 ? itemsLoaded / itemsTotal : 0
    console.log(`加载进度：${(progress * 100).toFixed(1)}%`)
    screen.update(progress)
  }

  manager.onError = (url) => {
    console.error('加载失败：', url)
  }

  return { manager, screen }
}

// 传给 loader 后，进度自动报告给 manager
const { manager, screen } = createLoadingManager()
const loader = new GLTFLoader(manager)

/**
 * 创建进度条 UI
 *
 * 默认 display:none，第 8 课启动时显示，
 * onLoad 触发后 opacity → 0 → display:none
 */
function createProgressBar() {
  const container = document.createElement('div')
  container.style.cssText = `
    position: fixed; top: 0; left: 0; width: 100%; height: 3px;
    background: rgba(0,0,0,0.1); z-index: 1000;
  `
  const bar = document.createElement('div')
  bar.style.cssText = `
    height: 100%; width: 0%; background: #DC2626;
    transition: width 0.3s ease;
  `
  container.appendChild(bar)
  document.body.appendChild(container)
  return { container, bar }
}

import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'

/**
 * Draco 解码器配置
 *
 * 解码器来自 three 自带的 examples/jsm/libs/draco，
 * Vite 会自动拷贝 wasm 文件到构建产物。
 */
function createGLTFLoader(
  manager: THREE.LoadingManager,
  useDraco: boolean,
): GLTFLoader {
  const loader = new GLTFLoader(manager)

  if (useDraco) {
    const dracoLoader = new DRACOLoader()
    dracoLoader.setDecoderPath('three/examples/jsm/libs/draco/')
    dracoLoader.setDecoderConfig({ type: 'wasm' })
    loader.setDRACOLoader(dracoLoader)
  }

  return loader
}

/**
 * loadModel — 模型加载函数
 *
 * 1. 计算包围盒 → 获取模型实际尺寸
 * 2. 计算缩放比例 → 目标大小
 * 3. 缩放后重新计算包围盒 → 居中
 * 4. 落地（groundSnap）
 * 5. 阴影设置
 * 6. 动画混合器
 */
interface ModelOptions {
  autoCenter?: boolean
  autoScale?: boolean
  targetSize?: number
  castShadow?: boolean
  receiveShadow?: boolean
  groundSnap?: boolean
}

async function loadModel(
  loader: GLTFLoader,
  url: string,
  options: ModelOptions = {},
) {
  const {
    autoCenter = true,
    autoScale = true,
    targetSize = 3,
    castShadow = true,
    receiveShadow = true,
    groundSnap = false,
  } = options

  return new Promise((resolve, reject) => {
    loader.load(url, (gltf) => {
      const model = gltf.scene

      // 1. 计算包围盒
      const box = new THREE.Box3().setFromObject(model)
      const size = box.getSize(new THREE.Vector3())

      // 2. 自动缩放
      if (autoScale) {
        const maxDim = Math.max(size.x, size.y, size.z)
        const scale = targetSize / maxDim
        model.scale.setScalar(scale)
      }

      // 3. 自动居中
      if (autoCenter) {
        const newBox = new THREE.Box3().setFromObject(model)
        const newCenter = newBox.getCenter(new THREE.Vector3())
        model.position.sub(newCenter)
      }

      // 3.1 落地
      if (groundSnap) {
        const newBox = new THREE.Box3().setFromObject(model)
        model.position.y -= newBox.min.y
      }

      // 4. 阴影设置
      model.traverse((child) => {
        if (child instanceof THREE.Mesh) {
          child.castShadow = castShadow
          child.receiveShadow = receiveShadow
        }
      })

      // 5. 动画混合器
      let mixer = null
      if (gltf.animations.length > 0) {
        mixer = new THREE.AnimationMixer(model)
      }

      resolve({ model, mixer, animations: gltf.animations })
    }, undefined, reject)
  })
}

/**
 * LOD — Level of Detail
 *
 * 根据相机距离自动切换不同精度的模型。
 * 这里用同一模型的多个缩放/简化版本作为示例。
 *
 * 注意：传入的 baseModel 必须保持 scale = 1；
 * LOD 内部各个 level 自己设置缩放。
 */
function createLODFromModel(baseModel: THREE.Group): THREE.LOD {
  const lod = new THREE.LOD()
  baseModel.scale.setScalar(1)

  // 高精度：原模型
  const high = baseModel
  high.traverse((c) => {
    if (c instanceof THREE.Mesh) {
      c.castShadow = true
      const mat = c.material as THREE.MeshStandardMaterial
      if (mat) mat.flatShading = false
    }
  })

  // 中精度：克隆 + 缩放 + 简化材质
  const mid = baseModel.clone(true)
  mid.scale.setScalar(0.85)
  mid.traverse((c) => {
    if (c instanceof THREE.Mesh) {
      c.castShadow = true
      const mat = c.material as THREE.MeshStandardMaterial
      if (mat) mat.flatShading = true
    }
  })

  // 低精度：克隆 + 更小 + 灰色简单材质
  const low = baseModel.clone(true)
  low.scale.setScalar(0.6)
  low.traverse((c) => {
    if (c instanceof THREE.Mesh) {
      c.castShadow = true
      const mat = c.material as THREE.MeshStandardMaterial
      if (mat) {
        mat.flatShading = true
        mat.color = new THREE.Color(0x999999)
      }
    }
  })

  lod.addLevel(high, 0)   // 0-8 米：高精度
  lod.addLevel(mid, 8)    // 8-16 米：中精度
  lod.addLevel(low, 16)   // 16+ 米：低精度

  return lod
}

/**
 * AnimationController — 动画控制器
 *
 * 封装 AnimationMixer，管理多个动画动作。
 * 支持淡入淡出切换、速度调节。
 */
class AnimationController {
  private mixer: THREE.AnimationMixer
  private actions: Map<string, THREE.AnimationAction> = new Map()
  private currentAction: THREE.AnimationAction | null = null

  constructor(mixer: THREE.AnimationMixer, clips: THREE.AnimationClip[]) {
    this.mixer = mixer
    clips.forEach((clip) => {
      const action = mixer.clipAction(clip)
      this.actions.set(clip.name || 'default', action)
    })
  }

  play(name: string, options: { loop?: boolean; speed?: number } = {}) {
    const { loop = true, speed = 1 } = options
    const action = this.actions.get(name)
    if (!action) return

    if (this.currentAction) {
      this.currentAction.fadeOut(0.3)
    }

    action.reset()
    action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, loop ? Infinity : 1)
    action.clampWhenFinished = true
    action.timeScale = speed
    action.fadeIn(0.3)
    action.play()

    this.currentAction = action
  }

  stop() {
    this.actions.forEach((action) => action.stop())
    this.currentAction = null
  }

  update(delta: number) {
    this.mixer.update(delta)
  }

  getAnimationNames(): string[] {
    return Array.from(this.actions.keys())
  }
}

// 加载模型后创建动画控制器
const { model, mixer, animations } = await loadModel(loader, url, options)

if (mixer && animations.length > 0) {
  const controller = new AnimationController(mixer, animations)
  controller.play(animations[0].name, { loop: true, speed: 1 })
}

// 动画循环中更新
manager.onUpdate((delta) => {
  controller?.update(delta)
})