carrotskin/docs/skinview3d-usage.md

# skinview3d 使用指南

skinview3d 是一个基于 Three.js 的 Minecraft 皮肤查看器，支持 3D 皮肤预览、动画效果、披风显示等功能。

## 安装

```bash
npm install skinview3d
```

## 基本用法

### 快速开始

```javascript
import { SkinViewer } from 'skinview3d';

// 创建皮肤查看器
const skinViewer = new SkinViewer({
    canvas: document.getElementById('skin_container'),
    width: 300,
    height: 400,
    skin: 'path/to/skin.png'
});
```

### React 组件封装

项目中已经封装了 React 组件 `SkinViewer`：

```tsx
import SkinViewer from '@/components/SkinViewer';

<SkinViewer
    skinUrl="https://example.com/skin.png"
    capeUrl="https://example.com/cape.png"  // 可选
    isSlim={false}                           // 是否为细臂模型
    width={300}
    height={300}
    autoRotate={true}                        // 自动旋转
    walking={false}                          // 步行动画
    running={false}                          // 跑步动画
    jumping={false}                          // 跳跃动画
    rotation={true}                          // 允许手动旋转
/>
```

## 配置选项

### 基本配置

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `canvas` | HTMLCanvasElement | 必填 | 画布元素 |
| `width` | number | 300 | 画布宽度 |
| `height` | number | 400 | 画布高度 |
| `skin` | string | null | 皮肤图片URL |
| `cape` | string | null | 披风图片URL |
| `model` | string | 'default' | 模型类型：'default' 或 'slim' |
| `zoom` | number | 1.0 | 缩放比例 |

### 背景设置

```javascript
// 设置背景颜色
skinViewer.background = 0x5a76f3;

// 设置背景图片
skinViewer.loadBackground('path/to/background.png');

// 设置全景背景
skinViewer.loadPanorama('path/to/panorama.png');

// 透明背景
skinViewer.background = null;
```

### 相机设置

```javascript
// 设置视野角度
skinViewer.fov = 70;

// 设置缩放
skinViewer.zoom = 0.5;
```

## 动画控制

### 内置动画类型

```javascript
import { 
    WalkingAnimation, 
    RunningAnimation, 
    FlyingAnimation, 
    IdleAnimation 
} from 'skinview3d';

// 步行动画
skinViewer.animation = new WalkingAnimation();

// 跑步动画
skinViewer.animation = new RunningAnimation();

// 飞行动画（可用于游泳）
skinViewer.animation = new FlyingAnimation();

// 静止动画
skinViewer.animation = new IdleAnimation();
```

### 动画控制

```javascript
// 设置动画速度
skinViewer.animation.speed = 3;

// 暂停动画
skinViewer.animation.paused = true;

// 移除动画
skinViewer.animation = null;
```

### 自动旋转

```javascript
// 启用自动旋转
skinViewer.autoRotate = true;

// 禁用自动旋转
skinViewer.autoRotate = false;
```

## 交互控制

### 鼠标控制

```javascript
// 启用旋转控制
skinViewer.controls.enableRotate = true;

// 启用缩放控制
skinViewer.controls.enableZoom = true;

// 启用平移控制
skinViewer.controls.enablePan = true;
```

## 光照设置

```javascript
// 设置相机光源强度
skinViewer.cameraLight.intensity = 0.9;

// 设置全局光源强度
skinViewer.globalLight.intensity = 0.1;

// 完全禁用阴影
globalLight.intensity = 1.0;
cameraLight.intensity = 0.0;
```

## 高级功能

### 耳朵支持

skinview3d 支持两种耳朵纹理类型：

1. **独立耳朵纹理**：14×7 像素的耳朵图片
2. **皮肤内置耳朵**：皮肤纹理中包含耳朵（如 deadmau5 皮肤）

```javascript
// 使用独立耳朵纹理
skinViewer.loadEars('path/to/ears.png', { 
    textureType: 'standalone' 
});

// 使用皮肤内置耳朵
skinViewer.loadEars('path/to/skin.png', { 
    textureType: 'skin' 
});
```

### 名称标签

```javascript
import { NameTagObject } from 'skinview3d';

// 简单名称标签
skinViewer.nameTag = "PlayerName";

// 自定义样式名称标签
skinViewer.nameTag = new NameTagObject("PlayerName", { 
    textStyle: "yellow" 
});

// 移除名称标签
skinViewer.nameTag = null;
```

**注意**：要正确显示名称标签，需要加载 Minecraft 字体：

```css
@font-face {
    font-family: 'Minecraft';
    src: url('/path/to/minecraft.woff2') format('woff2');
}
```

## 方法参考

### 皮肤管理

```javascript
// 加载皮肤
skinViewer.loadSkin('path/to/skin.png');

// 加载皮肤并指定模型
skinViewer.loadSkin('path/to/skin.png', { 
    model: 'slim' 
});

// 重置皮肤
skinViewer.resetSkin();
```

### 披风管理

```javascript
// 加载披风
skinViewer.loadCape('path/to/cape.png');

// 加载鞘翅（使用披风纹理）
skinViewer.loadCape('path/to/cape.png', { 
    backEquipment: 'elytra' 
});

// 移除披风
skinViewer.loadCape(null);
```

### 尺寸调整

```javascript
// 调整查看器尺寸
skinViewer.setSize(600, 800);

// 调整宽度
skinViewer.width = 600;

// 调整高度
skinViewer.height = 800;
```

## 错误处理

项目中封装的 SkinViewer 组件包含了完整的错误处理：

```typescript
// 图片加载失败处理
const img = new Image();
img.crossOrigin = 'anonymous';

img.onload = () => {
    // 图片加载成功，初始化3D查看器
    setImageLoaded(true);
};

img.onerror = (error) => {
    // 图片加载失败，显示错误状态
    setHasError(true);
};
```

## 最佳实践

### 1. 预加载图片
在初始化3D查看器之前，先预加载皮肤图片以确保可访问性。

### 2. 性能优化
- 及时清理不再使用的查看器实例
- 避免同时运行多个动画
- 合理设置画布尺寸

### 3. 用户体验
- 提供加载状态指示
- 显示错误信息和重试选项
- 支持键盘快捷键控制

### 4. 响应式设计
监听容器尺寸变化，动态调整查看器大小：

```javascript
useEffect(() => {
    if (viewerRef.current && canvasRef.current) {
        const rect = canvasRef.current.getBoundingClientRect();
        viewerRef.current.setSize(rect.width, rect.height);
    }
}, [imageLoaded]);
```

## 项目中的使用示例

查看 `[src/components/SkinDetailModal.tsx](src/components/SkinDetailModal.tsx)` 了解完整的皮肤预览实现，包括：

- 动画控制面板
- 键盘快捷键支持
- 最小化/最大化功能
- 响应式布局
- 错误处理和加载状态

## 相关资源

- [skinview3d GitHub 仓库](https://github.com/bs-community/skinview3d)
- [skinview3d 在线演示](https://skinview3d-demo.vercel.app)
- [Three.js 官方文档](https://threejs.org/docs/)