1

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/实例，避免重复销毁或遗漏解绑事件。