vtj-component-model

vite-threejs 3D Component Model

Overview

All 3D components in this project follow a class-based singleton pattern. Components access shared resources through the Experience singleton and implement standardized lifecycle methods.

Core principle: Extract only what you need, implement all required lifecycle methods, always clean up resources.

When to Use

• Creating any new class in src/js/
• Building 3D objects, managers, controllers, or utilities that interact with the scene
• Wrapping Three.js functionality in reusable components

Component Template

import Experience from '@/js/experience.js'
import emitter from '@/js/utils/event-bus.js'
import * as THREE from 'three'

export default class YourComponent {
  constructor(options = {}) {
    // 1. 获取 Experience 单例
    this.experience = new Experience()

    // 2. 按需提取依赖（仅取所需，避免冗余）
    this.scene = this.experience.scene
    this.resources = this.experience.resources
    this.debug = this.experience.debug

    // 3. 组件参数
    this.params = {
      enabled: options.enabled ?? true,
      // ... 其他参数
    }

    // 4. 组件状态
    this.mesh = null

    // 5. 初始化
    this._init()

    // 6. 调试面板（必须在 debug.active 条件下调用）
    if (this.debug.active) {
      this.debugInit()
    }
  }

  _init() {
    // 创建 3D 对象并添加到场景
    this.mesh = new THREE.Mesh(/* ... */)
    this.scene.add(this.mesh)
  }

  debugInit() {
    // 调试面板 - 详见 vtj-debug-panel skill
  }

  update() {
    // 每帧更新逻辑
    // 时间通过 this.experience.time 访问，不通过参数传递
  }

  resize() {
    // 窗口尺寸变化时调用
  }

  destroy() {
    // 清理资源 - 涉及 Object3D 的组件必须实现
    if (this.mesh) {
      this.scene.remove(this.mesh)
      this.mesh.geometry?.dispose()
      this.mesh.material?.dispose()
      this.mesh = null
    }
  }
}

Dependency Extraction Rules

只提取组件实际需要的依赖：

组件类型	典型依赖
渲染对象	scene, resources
交互组件	scene, camera.instance, iMouse
动画组件	scene, time
调试组件	debug
UI 相关	sizes, canvas