skinview3d API 参考手册：SkinViewer 核心属性与方法逐一详解

skinview3d API 参考手册：SkinViewer 核心属性与方法逐一详解

【免费下载链接】skinview3dThree.js powered Minecraft skin viewer.项目地址: https://gitcode.com/gh_mirrors/sk/skinview3d

skinview3d 是一个基于 Three.js 的Minecraft 皮肤查看器（skin viewer），只需几行代码，就能在网页中渲染出带披风、耳朵、鞘翅甚至动画的完整角色模型。作为一款面向 Web 开发者与 Minecraft 模组爱好者的开源库，skinview3d 把复杂的 3D 渲染封装成了极其简洁的skinview3d API。本篇文章就是一份通俗易懂的SkinViewer 参考手册，我们会围绕核心类SkinViewer，把它的构造参数、核心属性、常用方法逐一拆解，并附上源码位置，帮你快速定位、即学即用。

这张 4320×2160 的 Minecraft 全景图正是 skinview3d 示例中使用的全景背景（panorama），加载后角色会置身于真实的游戏世界中。

一分钟上手：SkinViewer 构造参数速查

所有能力都从一个new SkinViewer(options)开始，构造函数接收一个配置对象，下面是最常用的参数：

const viewer = new skinview3d.SkinViewer({ canvas: document.getElementById("skin_container"), // 渲染画布，不传会自动创建 width: 300, // 画布宽度（CSS 像素） height: 400, // 画布高度 skin: "img/skin.png", // 皮肤贴图 model: "auto-detect", // 模型类型："default" / "slim" / "auto-detect" cape: "img/cape.png", // 披风贴图 animation: new skinview3d.WalkingAnimation(), // 内置动画 background: 0x5a76f3, // 背景色 fov: 50, // 相机视野（度） zoom: 0.9, // 缩放比例 enableControls: true // 是否启用鼠标拖拽旋转 });

完整参数定义见 src/viewer.ts，其中pixelRatio、preserveDrawingBuffer、renderPaused、panorama、ears、nameTag等进阶参数后面会单独讲解。

核心属性详解：从渲染到角色控制

画布与渲染尺寸：width / height / pixelRatio

• width/height：读写画布的 CSS 尺寸，修改后会自动同步相机宽高比并重绘。它们本质上是setSize()的便捷封装（src/viewer.ts）。
• pixelRatio：像素比，默认"match-device"会自动跟随设备像素比（高分屏更清晰），也可以手动设为1或2等固定值（src/viewer.ts）。

相机与视角控制：fov / zoom / adjustCameraDistance()

• fov：相机垂直视野角（单位：度），默认50，值越大角色看起来越小。
• zoom：缩放比例，默认0.9，当值为1.0时角色头顶刚好贴合画布上边缘。
• adjustCameraDistance()：根据fov与zoom自动计算相机距离（限制在 10~256），修改fov/zoom时会被自动调用（src/viewer.ts）。
• resetCameraPose()：一键把相机复位到正面标准视角（src/viewer.ts）。

自动旋转与交互：autoRotate / autoRotateSpeed / controls

viewer.autoRotate = true; // 开启角色自动旋转 viewer.autoRotateSpeed = 1.0; // 角速度，单位 rad/s（默认 1.0） viewer.controls.enableRotate = true; // 允许鼠标拖拽旋转 viewer.controls.enableZoom = true; // 允许滚轮缩放 viewer.controls.enablePan = false; // 默认禁用平移

controls是 three.js 的OrbitControls实例，用户拖拽时自动旋转会暂停，松开后继续（src/viewer.ts）。

背景与灯光：background / globalLight / cameraLight

• background：支持纯色（如0x5a76f3）或Texture纹理，设为null则透明背景（src/viewer.ts）。
• 场景内置两盏灯：globalLight（环境光，默认强度3）与cameraLight（相机点光源，默认0.6），直接改intensity即可调节明暗（src/viewer.ts）。

动画与名牌：animation / nameTag

• animation：当前播放的动画对象，赋null会停止动画并复位姿势。切换动画时会自动重置角色关节（src/viewer.ts）。
• nameTag：角色头顶的 Minecraft 名牌。直接赋字符串会创建默认NameTagObject，也支持传入自定义对象（src/viewer.ts）。

生命周期控制：renderPaused / disposed

• renderPaused：暂停渲染与动画循环，设为false恢复（src/viewer.ts）。
• disposed：只读布尔值，调用dispose()释放资源后为true。

核心方法详解：让角色真正“活”起来

加载与清除皮肤：loadSkin() / resetSkin()

loadSkin(source, options)支持三种输入：URL 字符串、HTMLImageElement/Canvas等纹理源、或null（清除皮肤）。传入 URL 时返回 Promise，可链式.then()（src/viewer.ts）。

viewer.loadSkin("img/skin2.png", { model: "slim" }); // 指定纤细手臂模型 viewer.loadSkin("img/deadmau5.png", { ears: true }); // 同时加载皮肤上的耳朵 viewer.loadSkin(null); // 隐藏皮肤

resetSkin()会隐藏皮肤并释放 GPU 纹理，避免内存泄漏。

披风与鞘翅：loadCape() / resetCape()

viewer.loadCape("img/cape.png"); // 显示披风 viewer.loadCape("img/cape.png", { backEquipment: "elytra" }); // 同一张贴图显示鞘翅 viewer.loadCape(null); // 卸载

backEquipment取值"cape"或"elytra"，也可以在加载后通过viewer.playerObject.backEquipment动态切换（src/model.ts）。

耳朵与全景背景：loadEars() / loadPanorama() / loadBackground()

• loadEars(source, { textureType })：textureType为"standalone"（14×7 独立耳朵贴图）或"skin"（从皮肤贴图中取耳朵部分）（src/viewer.ts）。
• loadPanorama(source)：加载全景背景，等效于带EquirectangularReflectionMapping的loadBackground（src/viewer.ts）。
• loadBackground(source, mapping)：加载普通图片背景，可自定义纹理映射（src/viewer.ts）。

尺寸调整与资源释放：setSize() / render() / dispose()

viewer.setSize(600, 800); // 批量设置宽高，比分别赋值更高效 viewer.render(); // 手动渲染一帧（不推进动画进度） viewer.dispose(); // 释放渲染器、控制器与所有纹理，页面卸载前务必调用

动画系统 API：8 种内置动画一次看懂

所有动画都继承自PlayerAnimation抽象类（src/animation.ts），三个通用属性让控制动画变得非常简单：

内置动画一览：IdleAnimation（待机）、WalkingAnimation（行走）、RunningAnimation（奔跑）、FlyingAnimation（飞行+鞘翅展开）、WaveAnimation（挥手）、CrouchAnimation（潜行）、HitAnimation（受击）、SwimAnimation（游泳）。

进阶玩法是通过addAnimation()叠加自定义逻辑，比如在待机动画基础上让角色持续旋转：

viewer.animation = new skinview3d.IdleAnimation(); viewer.animation.addAnimation((player, progress) => { player.rotation.y = progress; // 用 progress 驱动旋转 });

addAnimation会返回一个 id，可用removeAnimation(id)移除（src/animation.ts）。

角色模型结构：playerObject 到底是什么

viewer.playerObject是PlayerObject实例，它把角色拆成了四个子对象（src/model.ts）：

• skin：SkinObject，内含head、body、leftArm、rightArm、leftLeg、rightLeg六个BodyPart，每个部件又分innerLayer（内层）与outerLayer（外层），这就是 1.8 双层皮肤。
• cape/elytra：披风与鞘翅，加载同一张贴图可通过backEquipment切换。
• ears：耳朵对象，挂在skin.head上。

你可以这样精细控制角色，比如只隐藏手臂外层：

viewer.playerObject.skin.rightArm.outerLayer.visible = false;

写在最后：快速上手建议

1. 从new SkinViewer()开始，先配好canvas、width、height、skin四个参数，几十秒就能看到角色。
2. 背景用loadPanorama()，配合仓库里的全景图（examples/public/img/panorama.png）效果立竿见影。
3. 动画用内置类，8 种动画覆盖绝大多数展示场景，不够再上addAnimation()自定义。
4. 别忘了dispose()，在组件卸载、页面关闭时释放 WebGL 资源，避免卡顿与内存泄漏。

如果还想深入了解每个类的细节，推荐直接阅读这几个源码文件：src/viewer.ts（核心类）、src/model.ts（模型结构）、src/animation.ts（动画系统）、src/nametag.ts（名牌实现），对照本手册阅读效率最高。希望这份 skinview3d API 参考手册能帮你顺利搭建出酷炫的 Minecraft 皮肤展示页面！

【免费下载链接】skinview3dThree.js powered Minecraft skin viewer.项目地址: https://gitcode.com/gh_mirrors/sk/skinview3d