zhengte.doc/cursor.md

Web3D 场景 SDK 使用说明

本 SDK 用于在 Web 场景中快速完成三维展示与交互，核心能力包括：相机修改、灯光调参、环境贴图切换、按配置渲染热点、热点驱动抛出事件、模型热加载/热销毁/热替换，以及按部件切换材质。

---

功能概览

• 相机控制：支持位置/目标点/FOV/远近裁剪的即时更新，带缓动动画。
• 灯光调参：主光、辅光、环境光强度、颜色、方向、阴影开关与软硬度。
• 环境贴图：HDRI 切换、曝光度、旋转（偏航/俯仰）、模糊度。
• 热点系统：基于配置渲染热点 UI，可按 click/hover/focus 抛出事件。
• 模型热更新：按 ID 进行加载、销毁、替换，支持队列并行与完成回调。
• 材质切换：按部件或分组应用/还原材质，支持预设表与回滚。
• 事件总线：统一事件接口，便于业务侧订阅热点/相机/模型状态。

---

快速开始

npm install your-web3d-sdk

import { createViewer } from 'your-web3d-sdk'

const sdk = await createViewer({
  container: '#viewer',
  assetsBase: '/assets',
  background: '#0f172a',
})

// 加载初始场景或模型
await sdk.model.load({ id: 'scene', url: '/models/showroom.glb' })

基础生命周期

1. 初始化 viewer：createViewer({ container })
2. 加载模型或场景：sdk.model.load(...)
3. 设置环境贴图/灯光：sdk.environment.setHDRI(...)、sdk.lights.update(...)
4. 渲染热点：sdk.hotspot.render(config.hotspots)
5. 订阅事件：sdk.on('hotspot:click', handler)
6. 在业务侧按需调用相机/材质/模型热更新 API

---

相机控制

// 直接设置视角
sdk.camera.set({
  position: [2.5, 1.6, 3.2],
  target: [0, 0.8, 0],
  fov: 45,
  near: 0.1,
  far: 200,
})

// 平滑过渡到指定视角
sdk.camera.animateTo(
  { position: [1.2, 1, 2.4], target: [0, 0.8, 0], fov: 50 },
  { duration: 0.8, easing: 'easeOutCubic' }
)

---

灯光调参

// 更新主方向光
sdk.lights.update('key', {
  intensity: 1.5,
  color: '#ffffff',
  direction: [0.3, -1, 0.25],
  castShadow: true,
})

// 环境光/辅光
sdk.lights.update('fill', { intensity: 0.6, color: '#dfe8ff' })
sdk.lights.update('ambient', { intensity: 0.25 })

---

环境贴图

await sdk.environment.setHDRI('/envs/showroom_2k.hdr', {
  exposure: 1.1,
  rotation: [0, 45, 0], // yaw/pitch/roll
  blur: 0.2,
})

---

热点渲染与事件

const hotspots = [
  {
    id: 'engine',
    position: [0.8, 0.6, -0.2],
    icon: 'info',
    label: '发动机舱',
    event: 'show-engine',
    payload: { part: 'engine' },
  },
  {
    id: 'door',
    position: [1.1, 0.9, 0.4],
    icon: 'action',
    label: '开启车门',
    event: 'toggle-door',
    payload: { side: 'left' },
  },
]

sdk.hotspot.render(hotspots)

sdk.hotspot.on('click', ({ id, payload }) => {
  // 业务侧根据 id/payload 触发操作
})

sdk.hotspot.on('hover', ({ id, hovering }) => {
  // hover 高亮或提示
})

事件命名建议（可按需扩展）：

• hotspot:click、hotspot:hover、hotspot:focus
• hotspot:rendered（所有热点就绪）

---

模型热加载 / 热销毁 / 热替换

// 加载
await sdk.model.load({ id: 'car', url: '/models/car.glb', draco: true })

// 销毁
await sdk.model.destroy('car')

// 替换（内部自动销毁旧实例并加载新实例）
await sdk.model.replace('car', { url: '/models/car-white.glb' })

可以通过 sdk.model.on('loaded' | 'replaced' | 'destroyed', handler) 监听模型状态。

---

材质切换

// 应用材质预设
sdk.material.apply({
  target: 'body',           // 部件或分组名称
  material: 'paint/blue',   // 预设 Key
})

// 批量切换
sdk.material.batch([
  { target: 'wheel', material: 'rim/chrome' },
  { target: 'glass', material: 'glass/clear' },
])

// 还原默认材质
sdk.material.reset('body')

---

推荐的配置结构

{
  "camera": { "position": [2.5, 1.6, 3.2], "target": [0, 0.8, 0], "fov": 45 },
  "environment": { "hdr": "/envs/showroom_2k.hdr", "exposure": 1.1, "rotation": [0, 45, 0] },
  "lights": {
    "key": { "intensity": 1.5, "color": "#ffffff", "direction": [0.3, -1, 0.25] },
    "fill": { "intensity": 0.6, "color": "#dfe8ff" },
    "ambient": { "intensity": 0.25 }
  },
  "hotspots": [
    { "id": "engine", "position": [0.8, 0.6, -0.2], "icon": "info", "label": "发动机舱", "event": "show-engine" },
    { "id": "door", "position": [1.1, 0.9, 0.4], "icon": "action", "label": "开启车门", "event": "toggle-door" }
  ]
}

---

事件清单（示例）

• 相机：camera:changed
• 热点：hotspot:click、hotspot:hover、hotspot:rendered
• 模型：model:loaded、model:replaced、model:destroyed
• 材质：material:applied、material:reset

订阅方式：

sdk.on('hotspot:click', (evt) => console.log(evt))
sdk.off('hotspot:click', handler) // 移除监听

---

调试建议

• 启用 sdk.debug(true) 查看加载、事件、帧率等日志。
• 逐步应用配置：先确认相机与灯光，再添加环境贴图与热点，最后再做材质/模型热更新。
• 热更新前后记录 ID/实例，避免重复销毁或遗漏解绑事件。