205 lines
5.2 KiB
Markdown
205 lines
5.2 KiB
Markdown
# Web3D 场景 SDK 使用说明
|
||
|
||
本 SDK 用于在 Web 场景中快速完成三维展示与交互，核心能力包括：相机修改、灯光调参、环境贴图切换、按配置渲染热点、热点驱动抛出事件、模型热加载/热销毁/热替换，以及按部件切换材质。
|
||
|
||
---
|
||
|
||
## 功能概览
|
||
- 相机控制：支持位置/目标点/FOV/远近裁剪的即时更新，带缓动动画。
|
||
- 灯光调参：主光、辅光、环境光强度、颜色、方向、阴影开关与软硬度。
|
||
- 环境贴图：HDRI 切换、曝光度、旋转（偏航/俯仰）、模糊度。
|
||
- 热点系统：基于配置渲染热点 UI，可按 click/hover/focus 抛出事件。
|
||
- 模型热更新：按 ID 进行加载、销毁、替换，支持队列并行与完成回调。
|
||
- 材质切换：按部件或分组应用/还原材质，支持预设表与回滚。
|
||
- 事件总线：统一事件接口，便于业务侧订阅热点/相机/模型状态。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
```bash
|
||
npm install your-web3d-sdk
|
||
```
|
||
|
||
```ts
|
||
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
|
||
|
||
---
|
||
|
||
## 相机控制
|
||
```ts
|
||
// 直接设置视角
|
||
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' }
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 灯光调参
|
||
```ts
|
||
// 更新主方向光
|
||
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 })
|
||
```
|
||
|
||
---
|
||
|
||
## 环境贴图
|
||
```ts
|
||
await sdk.environment.setHDRI('/envs/showroom_2k.hdr', {
|
||
exposure: 1.1,
|
||
rotation: [0, 45, 0], // yaw/pitch/roll
|
||
blur: 0.2,
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 热点渲染与事件
|
||
```ts
|
||
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`（所有热点就绪）
|
||
|
||
---
|
||
|
||
## 模型热加载 / 热销毁 / 热替换
|
||
```ts
|
||
// 加载
|
||
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)` 监听模型状态。
|
||
|
||
---
|
||
|
||
## 材质切换
|
||
```ts
|
||
// 应用材质预设
|
||
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')
|
||
```
|
||
|
||
---
|
||
|
||
## 推荐的配置结构
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
订阅方式：
|
||
```ts
|
||
sdk.on('hotspot:click', (evt) => console.log(evt))
|
||
sdk.off('hotspot:click', handler) // 移除监听
|
||
```
|
||
|
||
---
|
||
|
||
## 调试建议
|
||
- 启用 `sdk.debug(true)` 查看加载、事件、帧率等日志。
|
||
- 逐步应用配置：先确认相机与灯光，再添加环境贴图与热点，最后再做材质/模型热更新。
|
||
- 热更新前后记录 ID/实例，避免重复销毁或遗漏解绑事件。
|