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

skinview3d API 参考手册SkinViewer 核心属性与方法逐一详解【免费下载链接】skinview3dThree.js powered Minecraft skin viewer.项目地址: https://gitcode.com/gh_mirrors/sk/skinview3dskinview3d 是一个基于 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 / pixelRatiowidth/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 / controlsviewer.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 / cameraLightbackground支持纯色如0x5a76f3或Texture纹理设为null则透明背景src/viewer.ts。场景内置两盏灯globalLight环境光默认强度3与cameraLight相机点光源默认0.6直接改intensity即可调节明暗src/viewer.ts。动画与名牌animation / nameTaganimation当前播放的动画对象赋null会停止动画并复位姿势。切换动画时会自动重置角色关节src/viewer.ts。nameTag角色头顶的 Minecraft 名牌。直接赋字符串会创建默认NameTagObject也支持传入自定义对象src/viewer.ts。生命周期控制renderPaused / disposedrenderPaused暂停渲染与动画循环设为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为standalone14×7 独立耳朵贴图或skin从皮肤贴图中取耳朵部分src/viewer.ts。loadPanorama(source)加载全景背景等效于带EquirectangularReflectionMapping的loadBackgroundsrc/viewer.ts。loadBackground(source, mapping)加载普通图片背景可自定义纹理映射src/viewer.ts。尺寸调整与资源释放setSize() / render() / dispose()viewer.setSize(600, 800); // 批量设置宽高比分别赋值更高效 viewer.render(); // 手动渲染一帧不推进动画进度 viewer.dispose(); // 释放渲染器、控制器与所有纹理页面卸载前务必调用动画系统 API8 种内置动画一次看懂所有动画都继承自PlayerAnimation抽象类src/animation.ts三个通用属性让控制动画变得非常简单属性说明speed播放速度倍率默认1.0paused暂停/继续动画progress当前播放进度内置动画一览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.tsskinSkinObject内含head、body、leftArm、rightArm、leftLeg、rightLeg六个BodyPart每个部件又分innerLayer内层与outerLayer外层这就是 1.8 双层皮肤。cape/elytra披风与鞘翅加载同一张贴图可通过backEquipment切换。ears耳朵对象挂在skin.head上。你可以这样精细控制角色比如只隐藏手臂外层viewer.playerObject.skin.rightArm.outerLayer.visible false;写在最后快速上手建议从new SkinViewer()开始先配好canvas、width、height、skin四个参数几十秒就能看到角色。背景用loadPanorama()配合仓库里的全景图examples/public/img/panorama.png效果立竿见影。动画用内置类8 种动画覆盖绝大多数展示场景不够再上addAnimation()自定义。别忘了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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考