carrotskin/docs/skinview3d-usage.md

skinview3d 使用指南

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

安装

npm install skinview3d

基本用法

快速开始

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：

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	缩放比例

背景设置

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

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

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

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

相机设置

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

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

动画控制

内置动画类型

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

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

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

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

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

动画控制

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

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

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

自动旋转

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

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

交互控制

鼠标控制

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

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

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

光照设置

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

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

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

高级功能

耳朵支持

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

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

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

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

名称标签

import { NameTagObject } from 'skinview3d';

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

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

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

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

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

方法参考

皮肤管理

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

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

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

披风管理

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

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

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

尺寸调整

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

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

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

错误处理

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

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

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

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

最佳实践

1. 预加载图片

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

2. 性能优化

• 及时清理不再使用的查看器实例
• 避免同时运行多个动画
• 合理设置画布尺寸

3. 用户体验

• 提供加载状态指示
• 显示错误信息和重试选项
• 支持键盘快捷键控制

4. 响应式设计

监听容器尺寸变化，动态调整查看器大小：

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 仓库
• skinview3d 在线演示
• Three.js 官方文档