yes

public/docs/api-reference.md

@@ -0,0 +1,105 @@
+# SDK API 参考
+
+下列 API 均可在全局挂载或 ESM 模式下使用。示例统一使用 `kernel` 作为实例，若为全局构建请替换为 `window.faceSDK.kernel`。
+
+## 相机 Camera
+```ts
+// 设置视角
+kernel.camera.set({
+  position: [2.5, 1.6, 3.2],
+  target: [0, 0.8, 0],
+  fov: 45,
+  near: 0.1,
+  far: 200,
+})
+
+// 平滑过渡
+kernel.camera.animateTo(
+  { position: [1.2, 1, 2.4], target: [0, 0.8, 0], fov: 50 },
+  { duration: 0.8, easing: 'easeOutCubic', onFinish: () => console.log('camera done') }
+)
+```
+
+## 灯光 Lights
+```ts
+// 主方向光
+kernel.lights.update('key', {
+  intensity: 1.5,
+  color: '#ffffff',
+  direction: [0.3, -1, 0.25],
+  castShadow: true,
+})
+
+// 环境光 / 辅光
+kernel.lights.update('fill', { intensity: 0.6, color: '#dfe8ff' })
+kernel.lights.update('ambient', { intensity: 0.25 })
+```
+
+## 环境贴图 Environment
+```ts
+await kernel.environment.setHDRI('/envs/showroom_2k.hdr', {
+  exposure: 1.1,
+  rotation: [0, 45, 0], // yaw/pitch/roll
+  blur: 0.2,
+})
+```
+
+## 热点 Hotspot
+```ts
+const 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' },
+]
+
+kernel.hotspot.render(hotspots)
+
+kernel.hotspot.on('click', ({ id, payload }) => {
+  console.log('hotspot click', id, payload)
+})
+
+kernel.hotspot.on('hover', ({ id, hovering }) => {
+  console.log('hotspot hover', id, hovering)
+})
+```
+
+## 模型 Model
+```ts
+// 加载
+await kernel.model.load({ id: 'car', url: '/models/car.glb', draco: true })
+
+// 销毁
+await kernel.model.destroy('car')
+
+// 替换
+await kernel.model.replace('car', { url: '/models/car-white.glb' })
+
+// 事件
+kernel.model.on('loaded', (data) => console.log('loaded', data))
+kernel.model.on('replaced', (data) => console.log('replaced', data))
+kernel.model.on('destroyed', (data) => console.log('destroyed', data))
+```
+
+## 材质 Material
+```ts
+// 应用预设
+kernel.material.apply({ target: 'body', material: 'paint/blue' })
+
+// 批量切换
+kernel.material.batch([
+  { target: 'wheel', material: 'rim/chrome' },
+  { target: 'glass', material: 'glass/clear' },
+])
+
+// 还原
+kernel.material.reset('body')
+```
+
+## 事件总线与调试
+```ts
+// 订阅/取消
+kernel.on('hotspot:click', (evt) => console.log(evt))
+kernel.off('hotspot:click', handler)
+
+// 开启调试日志
+kernel.debug(true)
+```