vtj-scene-management

name	vtj-scene-management
description	Orchestrates World lifecycle and component initialization. Use when managing initialization order, update sequences, or implementing proper disposal chains.

vite-threejs Scene Management

Overview

World 类作为场景 orchestrator，管理所有 3D 组件的生命周期。核心原则：等待资源、顺序注册、顺序更新、逆序清理。

When to Use

• 创建新的 World 或主场景管理器
• 添加新的 3D 组件到场景
• 管理组件初始化顺序
• 确保资源正确清理

Core Patterns

1. 等待资源 (Wait for Resources)

所有依赖资源的组件在 core:ready 后初始化：

constructor() {
  this.experience = new Experience()

  emitter.on('core:ready', () => {
    // 资源已加载完成，开始初始化
    this.initComponents()
  })
}

2. 顺序注册 (Registration Order)

示例: 按依赖关系顺序创建组件：

initComponents() {
  // 1. 先初始化地形（玩家需要地形数据）
  this.chunkManager = new ChunkManager()

  // 2. 再初始化玩家（需要地形做碰撞检测）
  this.player = new Player()

  // 3. 相机跟随玩家
  this.cameraRig = new CameraRig()
  this.cameraRig.attachPlayer(this.player)

  // 4. 环境效果
  this.environment = new Environment()

  // 5. 交互系统（依赖地形和玩家）
  this.blockRaycaster = new BlockRaycaster({
    chunkManager: this.chunkManager
  })
}

3. 顺序更新 (Update Order)

update() 中按依赖顺序调用：

update() {
  // 1. 先更新地形流式加载
  this.chunkManager?.updateStreaming()
  this.chunkManager?.update()

  // 2. 玩家依赖地形数据
  this.player?.update()

  // 3. 环境效果
  this.environment?.update()

  // 4. 交互系统
  this.blockRaycaster?.update()
}

4. 逆序清理 (Reverse Disposal)

destroy() 中按相反顺序清理：

destroy() {
  // 与注册顺序相反：后创建的先销毁
  this.blockRaycaster?.destroy()      // 5
  this.environment?.destroy()         // 4
  this.cameraRig?.destroy()           // 3
  this.player?.destroy()              // 2
  this.chunkManager?.destroy()        // 1
}

Quick Reference

阶段	原则	代码位置
初始化	等待 core:ready	emitter.on('core:ready', ...)
注册	依赖先行	constructor 或 init 方法
更新	数据流顺序	update() 方法
清理	逆序销毁	destroy() 方法

Common Mistakes

❌ 在 core:ready 之前访问资源

// BAD
constructor() {
  this.model = this.resources.items['playerModel']  // undefined!
}

// GOOD
emitter.on('core:ready', () => {
  this.model = this.resources.items['playerModel']
})

❌ 忘记更新子组件

// BAD
update() {
  // 没有调用 chunkManager.update()
  this.player.update()
}

// GOOD
update() {
  this.chunkManager?.update()
  this.player?.update()
}

❌ 清理顺序错误

// BAD: 先销毁 chunkManager，但 player 还在引用它
destroy() {
  this.chunkManager?.destroy()
  this.player?.destroy()  // 可能崩溃
}

// GOOD: 先销毁依赖者
destroy() {
  this.player?.destroy()
  this.chunkManager?.destroy()
}