MinecraftSkinHelper 1.0.0

<div align="center">

🎮 MinecraftSkinHelper

全本地 · 跨平台 · 高性能的 Minecraft 皮肤处理库

无需网络、无需 API Key，完全本地处理 Minecraft 皮肤文件。
基于 Google SkiaSharp 图形引擎，支持头像裁切、全身渲染、部位提取等全套功能。

</div>

✨ 功能特性

📦 安装

NuGet 包管理器

dotnet add package MinecraftSkinHelper

.csproj 手动引用

<PackageReference Include="MinecraftSkinHelper" Version="1.0.0" />

跨平台原生依赖（SkiaSharp 会自动按平台选择，通常无需手动添加）：

<PackageReference Include="SkiaSharp.NativeAssets.Linux" Version="2.88.7" />
<PackageReference Include="SkiaSharp.NativeAssets.macOS" Version="2.88.7" />
<PackageReference Include="SkiaSharp.NativeAssets.Win32" Version="2.88.7" />

🚀 快速开始

基础用法

using MinecraftSkinHelper;

// 支持文件路径 / byte[] / Stream 三种加载方式
using var helper = new SkinHelper("steve.png");

// 检测模型类型
Console.WriteLine(helper.ModelType); // Classic 或 Slim

// 获取头部头像（含帽子，128px）
using var head = helper.GetHeadAvatar(128, includeHat: true);
SkinHelper.SavePng(head, "avatar.png");

// 全身正面（scale=8 → 128×256 px）
using var front = helper.GetFullBody(RenderFace.Front, scale: 8);
SkinHelper.SavePng(front, "front.png");

// 全身背面
using var back = helper.GetFullBody(RenderFace.Back, scale: 8);
SkinHelper.SavePng(back, "back.png");

// 正背对比拼图
using var compare = helper.GetFrontBackComparison(scale: 8);
SkinHelper.SavePng(compare, "compare.png");

// 输出为字节数组（HTTP 响应 / 数据库存储）
byte[] pngBytes = SkinHelper.ToPngBytes(head);

高级渲染

using MinecraftSkinHelper;
using SkiaSharp;

using var helper = new SkinHelper("alex.png");

// 圆形头像（SNS / 论坛）
using var circle = SkinRenderer.GetRoundAvatar(helper, size: 128);

// 圆角头像（radius 越大越圆）
using var rounded = SkinRenderer.GetRoundedAvatar(helper, size: 128, cornerRadius: 24f);

// 带背景色头像
using var withBg = SkinRenderer.GetAvatarWithBackground(
    helper,
    background: new SKColor(88, 101, 242), // Discord 紫
    size: 128,
    padding: 12
);

// 皮肤所有部位网格预览
using var atlas = SkinRenderer.GetSkinAtlas(helper, scale: 6);
SkinHelper.SavePng(atlas, "atlas.png");

// 像素放大（最近邻，保持像素风格）
using var raw = helper.GetPartRaw(SkinPart.HeadFront);
using var big = SkinRenderer.PixelScale(raw, scale: 16);
SkinHelper.SavePng(big, "head_x16.png");

提取单个部位

using var helper = new SkinHelper("skin.png");

// 提取左臂正面贴图（自动适配 Classic/Slim 宽度）
using var leftArm = helper.GetPartRaw(SkinPart.LeftArmFront);

// 提取头顶
using var headTop = helper.GetPartRaw(SkinPart.HeadTop);

从 Stream / byte[] 加载（适合 Web 场景）

// 从 HTTP 请求体加载
using var helper = new SkinHelper(Request.Body);

// 从数据库 BLOB 加载
byte[] blob = db.GetSkinBytes(userId);
using var helper2 = new SkinHelper(blob);

🖥️ CLI 工具

项目附带 MinecraftSkinHelper.CLI，可直接命令行使用：

# 构建
dotnet build

# 运行（输出到 ./output 目录）
dotnet run --project MinecraftSkinHelper.CLI -- steve.png ./output

输出文件：

output/
├── head_avatar.png        # 64px 头像
├── head_avatar_128.png    # 128px 头像
├── full_front.png         # 全身正面
├── full_back.png          # 全身背面
├── comparison.png         # 正背对比
├── part_HeadFront.png
├── part_HeadBack.png
├── part_HeadLeft.png
├── part_HeadRight.png
├── part_BodyFront.png
├── part_BodyBack.png
├── part_LeftArmFront.png
├── part_RightArmFront.png
├── part_LeftLegFront.png
└── part_RightLegFront.png

📐 皮肤 UV 坐标说明

MinecraftSkinHelper 遵循 Minecraft 标准 64×64 皮肤 UV 布局：

 0        8       16       24       32       40       48       56      64
 ┌────────┬────────┬────────┬────────┬────────┬────────┬────────┬────────┐
0│ HeadTop│HeadBtm │        │        │ HatTop │ HatBtm │        │        │
 ├────────┼────────┼────────┼────────┼────────┼────────┼────────┼────────┤
8│ HeadL  │ HeadFr │ HeadR  │ HeadBk │ HatL   │ HatFr  │ HatR   │ HatBk  │
 ├──┬─────┴──┬─────┴──┬─────┴──┬─────┴──┬─────┴──┬─────┴──┬─────┴──┬────┤
16│  │        │        │        │        │        │  LArmC │        │    │
  │LLeg Body  Body    Body     Body     Body    ─────────────────────────│
32│  │  Outer  Outer   Outer    Outer    Outer  │LArmOuter│             │
 ├──┴─────────┴────────┴─────────┴────────┴────────┴─────────────────────┤
48│  LLeg Outer        │         │ LArmOuter  │                          │
 ├──────────────────────┼─────────┼────────────┼──────────────────────────┤
52│  RLeg (Front/Back/L/R + Outer)│ RArm (Front/Back/L/R + Outer)        │
 └──────────────────────┴─────────┴────────────┴──────────────────────────┘

🗂️ 项目结构

MinecraftSkinHelper.sln（或 .slnx）
├── MinecraftSkinHelper/                 ← 类库（Class Library）
│   ├── SkinHelper.cs                    # 核心：加载、检测、裁切、渲染
│   ├── SkinRenderer.cs                  # 高级：圆角/圆形/图集/像素放大
│   └── MinecraftSkinHelper.csproj
│
└── MinecraftSkinHelper.CLI/             ← 命令行工具（Console App）
    ├── Program.cs
    └── MinecraftSkinHelper.CLI.csproj

📖 API 参考

SkinHelper

SkinRenderer（静态）

SkinPart 枚举

HeadFront  HeadBack  HeadLeft  HeadRight  HeadTop  HeadBottom
HatFront   HatBack
BodyFront  BodyBack  BodyLeft  BodyRight
LeftArmFront  LeftArmBack  RightArmFront  RightArmBack
LeftLegFront  LeftLegBack  RightLegFront  RightLegBack

⚡ 性能说明

• 基于 Google Skia 原生图形引擎（SkiaSharp），无托管 GDI/WPF 依赖
• 所有操作完全内存内完成，无临时文件 I/O
• 使用 FilterQuality.None（最近邻插值），像素艺术风格锐利无模糊
• 实现 IDisposable，图像资源明确释放，无内存泄漏
• 支持多线程并发（每个 SkinHelper 实例独立，无共享状态）

🔧 环境要求

📄 License

MIT © 2026