zhengte.babylonjs-sdk/API_USAGE_EXAMPLE.md

# 模型管理 API 使用示例

## API 说明

### 1. 添加模型

```javascript
// 添加带有 rotation 控制类型的模型
kernel.model.add({
  modelId: "卷帘大",
  modelUrl: "https://sdk.zguiy.com/resurces/model/卷帘大.glb",
  modelControlType: "rotation"
});

// 添加带有 color 控制类型的模型
kernel.model.add({
  modelId: "小桌",
  modelUrl: "https://sdk.zguiy.com/resurces/model/小桌.glb",
  modelControlType: "color"
});

// 添加不带控制类型的模型
kernel.model.add({
  modelId: "框架",
  modelUrl: "https://sdk.zguiy.com/resurces/model/框架.glb"
});
```

### 2. 替换模型

```javascript
// 替换模型并指定控制类型
kernel.model.replace({
  modelId: "卷帘大",
  modelUrl: "https://sdk.zguiy.com/resurces/model/新卷帘.glb",
  modelControlType: "rotation"
});
```

### 3. 模型变换 (Transform)

```javascript
// 设置模型旋转 - 直接使用角度（默认）
kernel.transform.rotation({
  modelId: "卷帘大",
  vector3: { x: 0, y: 90, z: 0 }  // 绕Y轴旋转90度
});

// 更多角度示例
kernel.transform.rotation({
  modelId: "卷帘大",
  vector3: { x: 0, y: 180, z: 0 }  // 旋转180度
});

kernel.transform.rotation({
  modelId: "卷帘大",
  vector3: { x: 45, y: 90, z: 0 }  // X轴45度，Y轴90度
});

// 如果需要使用弧度，设置 useDegrees: false
kernel.transform.rotation({
  modelId: "卷帘大",
  vector3: { x: 0, y: Math.PI / 2, z: 0 },
  useDegrees: false
});

// 设置模型位置
kernel.transform.position({
  modelId: "小桌",
  vector3: { x: 10, y: 0, z: 5 }
});

// 设置模型缩放
kernel.transform.scale({
  modelId: "框架",
  vector3: { x: 1.5, y: 1.5, z: 1.5 }  // 放大1.5倍
});
```

### 4. 点击事件回调

```javascript
kernel.on('model:click', (data) => {
  console.log('点击的网格名称:', data.meshName);
  console.log('点击的网格对象:', data.pickedMesh);
  console.log('点击的3D坐标:', data.pickedPoint);
  console.log('材质名称:', data.materialName);
  console.log('模型控制类型:', data.modelControlType); // 'rotation' | 'color' | undefined

  // 根据控制类型执行不同操作
  if (data.modelControlType === 'rotation') {
    console.log('这是一个可旋转的模型');
    // 执行旋转相关操作 - 直接使用角度
    kernel.transform.rotation({
      modelId: "卷帘大",
      vector3: { x: 0, y: 180, z: 0 }
    });
  } else if (data.modelControlType === 'color') {
    console.log('这是一个可改变颜色的模型');
    // 执行颜色相关操作
    kernel.material.color(data.materialName, '#FF0000');
  }
});
```

## ModelControlType 说明

- `rotation`: 表示该模型支持旋转控制
- `color`: 表示该模型支持颜色控制
- `undefined`: 未指定控制类型

## 完整示例

```javascript
import { kernel } from './index.js';

const config = {
  container: document.querySelector('#renderDom'),
  modelUrlList: [],
  env: { 
    envPath: 'https://sdk.zguiy.com/resurces/hdr/hdr.env', 
    intensity: 1.2, 
    rotationY: 0.3, 
    background: true 
  },
};

kernel.init(config);

// 添加多个模型
kernel.model.add({
  modelId: "框架",
  modelUrl: "https://sdk.zguiy.com/resurces/model/框架.glb"
});

kernel.model.add({
  modelId: "卷帘大",
  modelUrl: "https://sdk.zguiy.com/resurces/model/卷帘大.glb",
  modelControlType: "rotation"
});

kernel.model.add({
  modelId: "小桌",
  modelUrl: "https://sdk.zguiy.com/resurces/model/小桌.glb",
  modelControlType: "color"
});

// 模型加载完成后设置变换
kernel.on('model:loaded', () => {
  // 设置初始位置
  kernel.transform.position({
    modelId: "小桌",
    vector3: { x: 5, y: 0, z: 0 }
  });

  // 设置初始旋转 - 直接使用角度
  kernel.transform.rotation({
    modelId: "卷帘大",
    vector3: { x: 0, y: 45, z: 0 }
  });

  // 设置缩放
  kernel.transform.scale({
    modelId: "框架",
    vector3: { x: 1.2, y: 1.2, z: 1.2 }
  });
});

// 监听点击事件
kernel.on('model:click', (data) => {
  console.log('模型点击数据:', data);
  
  if (data.modelControlType === 'rotation') {
    // 处理旋转逻辑 - 每次点击旋转45度
    kernel.transform.rotation({
      modelId: data.meshName,
      vector3: { x: 0, y: 45, z: 0 }
    });
  } else if (data.modelControlType === 'color') {
    // 处理颜色变更逻辑
    kernel.material.color(data.materialName, '#FF0000');
  }
});
```

## Transform API 详细说明

### rotation - 旋转
- 参数：`{ modelId: string, vector3: { x, y, z }, useDegrees?: boolean }`
- **默认使用角度**：直接传递 90、180 等角度值
- 如需使用弧度，设置 `useDegrees: false`
- 示例：
  ```javascript
  // 使用角度（默认，推荐）
  kernel.transform.rotation({
    modelId: "model1",
    vector3: { x: 0, y: 90, z: 0 }
  });
  
  // 使用弧度
  kernel.transform.rotation({
    modelId: "model1",
    vector3: { x: 0, y: Math.PI / 2, z: 0 },
    useDegrees: false
  });
  ```

### position - 位置
- 参数：`{ modelId: string, vector3: { x, y, z } }`
- 单位：场景单位
- 坐标系：右手坐标系（X右，Y上，Z前）

### scale - 缩放
- 参数：`{ modelId: string, vector3: { x, y, z } }`
- 单位：倍数（1.0 = 原始大小）
- 可以设置不同轴向的缩放比例