1

public/docs/camera-light.md

@@ -0,0 +1,43 @@
+# 相机与灯光/环境
+
+## 相机控制
+```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,
+})
+```

public/docs/config-template.md

@@ -0,0 +1,30 @@
+# 配置示例与事件清单
+
+## 推荐的配置结构
+```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) // 移除监听
+```

public/docs/hotspot-events.md

@@ -0,0 +1,40 @@
+# 热点与事件
+
+## 渲染热点
+```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)
+```
+
+## 订阅事件
+```ts
+sdk.hotspot.on('click', ({ id, payload }) => {
+  // 根据 id/payload 触发业务逻辑
+})
+
+sdk.hotspot.on('hover', ({ id, hovering }) => {
+  // hover 高亮或提示
+})
+```
+
+## 事件命名建议
+- `hotspot:click`、`hotspot:hover`、`hotspot:focus`
+- `hotspot:rendered`（所有热点就绪）

public/docs/import-guide.md

@@ -0,0 +1,46 @@
+# 引入方式与事件监听
+
+介绍两种集成方式（全局挂载 / 模块化 ESM），以及统一的事件监听方法。
+
+## 全局挂载（非模块化）
+1. 引入全局构建产物（替换为你的实际部署地址）：
+   ```html
+   <script src="https://sdk.zguiy.com/zt/assets/index.js"></script>
+   ```
+2. 获取实例并初始化：
+   ```js
+   const kernel = window.faceSDK?.kernel
+   if (!kernel) {
+     console.error('SDK 未加载')
+   } else {
+     kernel.init({
+       container: 'renderDom',           // 容器 ID（canvas）
+       modelUrlList: ['./model.glb'],    // 模型列表
+       env: { hdrPath: '/hdr/my.env' },  // 环境贴图等参数
+     })
+   }
+   ```
+
+## 模块化（ESM）
+1. 在 `<script type="module">` 中导入：
+   ```js
+   import { kernel } from 'https://sdk.zguiy.com/zt/assets/index.js' // 构建后路径自行替换
+   ```
+2. 初始化（与全局方式一致）：
+   ```js
+   kernel.init({
+     container: 'renderDom',
+     modelUrlList: ['./model.glb'],
+     env: { envPath: '/hdr/my.env' },
+   })
+   ```
+
+## 事件监听（两种方式通用）
+```js
+kernel.on('model:load:progress', (data) => console.log('模型加载进度', data))
+kernel.on('model:loaded', (data) => console.log('模型加载完成', data))
+kernel.on('model:click', (data) => console.log('模型点击', data))
+
+// 需要时可移除
+// kernel.off('model:loaded', handler)
+```

public/docs/model-material.md

@@ -0,0 +1,38 @@
+# 模型热更新与材质切换
+
+## 模型热加载 / 销毁 / 替换
+```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' })
+```
+
+监听状态：
+```ts
+sdk.model.on('loaded', handler)
+sdk.model.on('replaced', handler)
+sdk.model.on('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')
+```

public/docs/quickstart.md

@@ -0,0 +1,35 @@
+# 快速开始
+
+面向 Web 场景的三维展示与互动 SDK，提供相机、灯光、环境贴图、热点、模型热更新与材质切换等能力。
+
+## 安装
+```bash
+npm install your-web3d-sdk
+```
+
+## 初始化 Viewer
+```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
+
+## 调试建议
+- 启用 `sdk.debug(true)` 查看加载、事件、帧率等日志。
+- 逐步应用配置：先确认相机与灯光，再添加环境贴图与热点，最后再做材质/模型热更新。
+- 热更新前后记录 ID/实例，避免重复销毁或遗漏解绑事件。