mc-asset — Minecraft Pixel Asset Engine

mc-asset

English | 繁體中文 | 简体中文

mc-asset 是一款面向 Minecraft Java Edition 资源包的纹理和模型工具，既适用于创作者，也适用于通过命令行（CLI）或 MCP 操作的 AI Agent。

大模型无法凭视觉逐像素绘制，因此 mc-asset 将纹理制作转化为文本和命令：以字符网格绘制精灵图，将参考图像素化，生成可平铺纹理，打包动画图集，预览长方体模型，并验证整个资源包；既可从 shell 操作，也可通过 MCP 使用。相同的输入和种子始终会生成相同的文件。

六个 16×16 物品，每个都以文本网格编写，并由 mc-asset render 绘制（图中放大 ×6），遵循 minecraft-pixel-art 技能中的原版风格规则。网格文件位于 docs/assets/showcase/items/。

---

目录

• 功能介绍
• 亮点
• 展示
• 安装
• 面向 AI Agent
• 快速开始
• 实用配方
• MCP 服务
• 命令参考
• 批量操作（--operations）
• 架构与可靠性保证
• 开发
• 许可证

---

功能介绍

• 从文本字符网格绘制纹理（render）
• 将参考图像降采样为像素画（pixelize）并减少颜色数量（quantize）
• 将一个精灵图扩展为多个材质变体（variant）
• 生成并检查可平铺纹理的接缝（generate、tile）
• 打包动画精灵图集并写入 .mcmeta 文件（animate、mcmeta）
• 使用九宫格边框缩放 GUI 精灵图（gui-scale）
• 逐像素比较两个 PNG 文件（compare）
• 验证单张纹理或整个资源包（validate、validate-pack）
• 无损压缩 PNG 文件（optimize）
• 创建、验证并预览 Java 方块模型（model）
• 通过声明式配方制作完整资源包、审查风格、编目原版资源，并导出可复现的 zip 文件（pack、style）
• 通过 MCP 服务向 AI Agent 提供所有功能（mcp）

---

亮点

• 输入文本，输出纹理。 精灵图可以是字符网格（.grid），也可以是可编辑的多图层源文件（.mcpx），并可构建为 PNG。请参阅 docs/mcpx-format.md。
• 输出一致。 不使用未设种子的随机数，且颜色混合仅使用整数，因此 PNG 和 .mcpx 输出在不同运行之间以及 Bun 与 Node 之间都完全一致。
• 一个引擎，两个前端。 CLI 和 stdio MCP 服务调用相同的核心，因此 Agent 获得的结果与 shell 脚本完全相同。
• 统一的 JSON 输出。 --json 始终返回 { success, result, error } 和稳定的错误代码，日志不会混入 stdout 数据。
• 不会意外写入。 每个输出路径都必须明确指定，覆盖已有文件需要使用 --force，并且每个文件都会先写入临时文件，再重命名到目标位置。

---

展示

下方的每张图片都由 mc-asset 自身生成，生成纹理使用固定种子，因此整套内容都可复现。相关命令位于 docs/assets/showcase/README.md。

像素化	量化
→	→
一张细节丰富的参考图（128px，按 ×2 显示）缩小至 16px（按 ×16 显示）：颗粒变粗，形状也贴合整齐的像素网格。	一个包含 64 种颜色的渐变缩减为 8 种颜色（均按 ×4 显示）：颜色数量减少，最终呈现出清晰的色阶。

材质变体 — 页面顶部的剑扩展为全部九种内置材质（copper、crystal、diamond、gold、iron、netherite、oxidized_copper、stone、wood，按 ×5 显示）。它的调色板为每种颜色分配了用途，因此刀刃和护手采用了新的色阶，而最暗的轮廓、白色高光、木质握柄和护手上的宝石则保留原色：

生成的图案 — 使用固定种子生成的每种 generate 图案，均以 16px 色块呈现（按 ×4 显示）：

noise	clustered-noise	stripes	checker	gradient
brick	spots	veins	cracks	grain
无缝平铺 — 16px 砖块表面（左，×8）及其组成的 4×4 墙面（右，×4）；砂浆线会在每条边缘处连续衔接：

方块纹理 — 石头、泥土和橡木木板的 16×16 纹理（左，×8），沿四条边缘均可整齐平铺。右侧是木板纹理组成的 4×4 墙面（×4）：

动画图集 — 四帧发光矿石方块打包在一条竖直条带中（×4），这是 Minecraft 通过 .mcmeta 动画文件读取的布局：

药水变体与对比 — 将药水重新着色为 crystal、gold 和 iron（×5），同时保留玻璃瓶、木塞和白色闪光的原有颜色；对铁色和金色变体执行 compare，发现液体有 72 个像素发生变化，并在诊断图中用洋红色标出（×8）：

按钮九切片 — 将 16px 按钮边框（左，×4）缩放到 48×16，分别使用九切片（中，×4）和平铺拉伸（右，×4）；九切片能让边角和斜面保持清晰，而拉伸会使它们变模糊：

Java 模型三视图预览 — 一个由五个长方体组成的阶梯神龛模型 (model-shrine.json)，使用上文展示的砖块、木板、石头和发光矿石纹理。model preview --size 128 从三个方向查看该模型：正面（北，front）、侧面（东，right）和上方（top）：

---

安装

通过 npm（推荐）

直接从注册表运行服务，无需本地安装：

npx -y mc-asset mcp

全局安装 CLI，即可在 PATH 中使用 mc-asset 命令：

npm install -g mc-asset
mc-asset --version

通过 Homebrew（macOS / Linux）

brew tap smile-minecraft/tap
brew install smile-minecraft/tap/mc-asset
mc-asset --version

通过 Bun 或 Node.js（从源代码安装）

git clone https://github.com/smile-minecraft/mc-asset.git
cd mc-asset
bun install --frozen-lockfile
bun run build
./bin/mc-asset.js --version

前置条件：已使用 Node.js 22 和 Bun 1.3 进行测试。bun run build 需要 Bun，./bin/mc-asset.js 需要 Node.js；如果只使用 Bun，请运行 bun ./bin/mc-asset.js。

---

面向 AI Agent

• llms.txt — 为 Agent 提供的精简仓库索引。
• llms-full.txt — 相同内容的单文件版本：安装、25 个 MCP 工具、批量操作、错误模型和限制。
• docs/cli-surface.md — 冻结的 CLI 命令、批量操作规范和退出码注册表。
• docs/mcpx-format.md — 可编辑的多层 .mcpx 和 .grid 语法与规范。
• docs/mcp-guide.md — 注册、每个 MCP 工具的一份原样记录，以及错误模型。
• docs/mcp-surface.md — 冻结的 MCP 接口：工具名称、输入和读写约定。
• AGENTS.md — 修改此仓库时必须遵守的规则。

Agent 技能

仓库内置两个 Agent 技能，位于 skills/，可通过 skills CLI 安装：

npx skills add smile-minecraft/mc-asset

• mc-asset — 使用此工具进行绘制 → 渲染 → 预览 → 测量 → 验证的循环、CLI/MCP 命令映射，以及调色板角色如何驱动重新着色。
• minecraft-pixel-art — 适用于物品、方块、GUI 精灵和动画的原版风格规则：调色板和色相偏移色阶、材质轮廓、左上方光源、平铺，以及反模式审查清单。

添加 --skill mc-asset 或 --skill minecraft-pixel-art，即可只安装其中一项。

---

快速入门

从文本网格到经过验证的纹理

用字符网格绘制一个 16×16 宝石，每个像素对应一个字符：

mkdir -p /tmp/mc-asset-demo
cat << 'EOF' > /tmp/mc-asset-demo/gem.grid
[palette]
. = transparent
o = #0E1846FF
s = #1E3A8CFF
D = #2448A8FF
m = #3569D0FF
l = #5A92EEFF
t = #7FB2F6FF
T = #A9D2FFFF
W = #FFFFFFFF

[grid]
................
................
......sssss.....
.....sTTTTTo....
....sTTWWTTto...
...sTTWWTTttto..
..slllTTTtttmmo.
..slllllmmmmmDo.
..slllllmmmmmDo.
..slllllmmmmDDo.
...olllmmmmDDo..
....ollmmmDDo...
.....olmmmDo....
......ommDo.....
.......ooo......
................
EOF

将网格渲染为 PNG 纹理，并保存可编辑的 .mcpx 源文件：

mc-asset render /tmp/mc-asset-demo/gem.grid \
  --output /tmp/mc-asset-demo/gem.png \
  --source /tmp/mc-asset-demo/gem.mcpx
# ok render profile=generic applied=0 output=/tmp/mc-asset-demo/gem.png source=/tmp/mc-asset-demo/gem.mcpx

渲染后的 gem.png，放大 ×8：

检查其颜色和 alpha：

mc-asset analyze /tmp/mc-asset-demo/gem.png
# dimensions: 16x16
# colors: 9
# alpha: predicted cutout (opaque=119 transparent=137 partial=0)
# dominant: #00000000 x137 (0.5352), #3569D0FF x28 (0.1094), #5A92EEFF x24 (0.0938), #0E1846FF x18 (0.0703), #A9D2FFFF x16 (0.0625), #1E3A8CFF x12 (0.0469), #2448A8FF x10 (0.0391), #7FB2F6FF x7 (0.0273)
# profile: predicted profile generic has no Minecraft-specific restrictions.
# palette: colorCount=9 alphaLevels=2 transparent=137 partial=0
# pixel-art: 16x16 aspect=1:1 isolated=0 semiTransparent=0 tileFriendly=true
# recommended: quantize.colors=16 cleanup=none resize=nearest

将其验证为 Minecraft 物品纹理：

mc-asset validate /tmp/mc-asset-demo/gem.png --profile minecraft:item
# verdict: pass
# dimensions: 16x16
# colors: 9
# alpha: predicted cutout (opaque=119 transparent=137 partial=0)
# profile: predicted profile minecraft:item prefers the items atlas without mipmaps.

---

实用方案

方案 1：参考图降采样（pixelize）

将高分辨率参考图转换为 16×16 物品纹理。相同的图像和预设始终会生成相同的像素：

mc-asset pixelize reference.png \
  --size 16 \
  --preset item \
  --profile minecraft:item \
  --output item_texture.png

• --preset item 设置 16 色预算，并启用裁剪、背景、主体、边缘和色块阶段。
• 其他预设包括 block、gui、particle 和 generic。

方案 2：程序化纹理与无缝平铺（generate 和 tile）

使用固定种子生成石材纹理，然后检查能否平铺：

mc-asset generate noise \
  --size 16 \
  --palette stone \
  --seed 42 \
  --output stone.png

# Seam scores: horizontal, vertical, corner (lower is smoother)
mc-asset tile stone.png
# ok tile profile=generic seam=h:0.065196 v:0.096051 c:0.003604 repeat=0.908038

# Match the opposite edges and preview a 4x4 repeat
mc-asset tile stone.png \
  --edge-match both \
  --preview 4x4 \
  --output stone_preview.png

方案 3：调色板量化与瑕疵清理（quantize 和 cleanup）

将精灵缩减到 8 种颜色，然后移除遗留的杂散像素：

mc-asset quantize sprite.png --colors 8 --output quantized.png

mc-asset cleanup quantized.png \
  --fix isolated,noise \
  --allow-render-pass-change \
  --output clean.png

这些修复类别可能会改变 alpha，从而改变纹理所需的渲染通道，因此 cleanup 在未指定 --allow-render-pass-change 时会拒绝执行。

方案 4：材质变体（variant 和 recolor）

将一个源文件扩展为多个材质等级，或将其重新着色为单一材质。源文件可以是可编辑的 .mcpx，也可以是扁平 PNG（PNG 不包含调色板角色，因此会按整数亮度区间映射其像素，不会臆造图层角色）：

mc-asset variant sword.mcpx \
  --materials iron,copper,gold \
  --output-dir ./dist_variants \
  --mkdir
# Writes sword_iron.png, sword_iron.mcpx, sword_copper.png, etc.

mc-asset recolor sword.mcpx --material gold --output sword_gold.png

方案 5：动画精灵表（animate）

将文件夹中的帧打包成垂直精灵表，然后根据其 .mcmeta 进行检查：

mc-asset animate pack \
  --frames-dir ./textures/fire_frames \
  --layout vertical \
  --output ./textures/fire.png

mc-asset validate ./textures/fire.png --mcmeta ./textures/fire.png.mcmeta

配方 6：完整资源包验证（validate-pack）

扫描整个资源包，查找缺失的纹理、错误的命名空间、孤立纹理、损坏的模型引用和引用循环。--minecraft-version 用于选择要对照检查的资源包格式：

mc-asset validate-pack ./MyResourcePack \
  --minecraft-version 26.3 \
  --json

配方 7：批量编辑并提供视觉反馈（build 与 apply_asset_operations）

一次批量编辑 Quickstart 宝石：用 6×6 的黑色边框围住 4×4 的金色方块。CLI 会应用这批操作并写入 PNG：

cat << 'EOF' > /tmp/mc-asset-demo/ops.json
[
  { "type": "fillRect", "rect": { "x": 6, "y": 6, "width": 4, "height": 4 }, "color": "#FFD700FF" },
  { "type": "drawRect", "rect": { "x": 5, "y": 5, "width": 6, "height": 6 }, "color": "#000000FF" }
]
EOF

mc-asset build /tmp/mc-asset-demo/gem.mcpx \
  --operations /tmp/mc-asset-demo/ops.json \
  --output /tmp/mc-asset-demo/gem_modified.png
# ok build profile=generic applied=2 output=/tmp/mc-asset-demo/gem_modified.png

批量编辑前后（均为 ×8）：

→

通过 MCP，apply_asset_operations 会运行相同的批量操作，并可返回一张展示更改内容的图片：

{
  "sourcePath": "/tmp/mc-asset-demo/gem.mcpx",
  "operations": [
    { "type": "fillRect", "rect": { "x": 6, "y": 6, "width": 4, "height": 4 }, "color": "#FFD700FF" },
    { "type": "drawRect", "rect": { "x": 5, "y": 5, "width": 6, "height": 6 }, "color": "#000000FF" }
  ],
  "outputPngPath": "/tmp/mc-asset-demo/gem_feedback.png",
  "feedback": { "image": "changed", "scale": 8, "diff": "summary" }
}

启用 feedback 后，结果会保留常规字段，并添加一个裁剪至更改区域且按 scale（1–16）放大的 PNG 图片块，以及一份 diff 摘要（raw、composited、structural、outsideSelectionUnchanged）。没有可见变化的编辑会返回 noVisibleChange，而不是图片。Agent 无需获取整个画布，就能看到自己的编辑结果。由于 MCP 工具不会覆盖现有文件，输出路径会与 CLI 运行时不同。

配方 8：九宫格 GUI 缩放（gui-scale）

调整 GUI 边框的大小，同时避免边框模糊。使用 nine_slice 时，角落会按 1:1 复制，边缘和中心则会平铺（或在 stretch_inner: true 时拉伸）。16×16 的 dialog.png 在 dialog.png.mcmeta 中声明了 4px 的边框：

{ "gui": { "scaling": { "type": "nine_slice", "width": 16, "height": 16, "border": 4 } } }

mc-asset gui-scale ./textures/gui/dialog.png \
  --mcmeta ./textures/gui/dialog.png.mcmeta \
  --size 48x32 \
  --output ./textures/gui/dialog_large.png
# ok gui-scale profile=generic size=48x32 scaling=nine_slice output=./textures/gui/dialog_large.png

gui-scale 不会自动读取同目录下的 .mcmeta；如果不指定 --mcmeta，它就会拉伸整个精灵图。

源图，16×16	nine_slice，48×32	不使用 --mcmeta（拉伸），48×32

三张图均以 ×4 显示。使用 mcmeta 时，裁切后的角落和 2px 斜面会按 1:1 复制并保持原有宽度；直接拉伸则会使斜面不均匀地变粗，并模糊角落。

配方 9：无损 PNG 优化与 Java 模型（optimize 与 model）

optimize 会将 PNG 重新编码为能精确保留相同像素的最小编码；如果无法减小文件，则保留源文件。它接受显式 PNG 路径（最多 256 个文件）或整个目录（--input-dir，最多 4096 个 PNG，可选 --recursive，并保留相对路径）。它绝不会重写输入文件；请指定 --output、--output-dir、--stdout 或 --dry-run。

mc-asset optimize ./gem.png --dry-run
# ok optimize input=./gem.png output=- status=optimized source=184 result=102 mode=rgba
mc-asset optimize ./gem.png ./sword.png --output-dir ./optimized --mkdir
mc-asset optimize --input-dir ./textures --recursive --output-dir ./optimized --mkdir

model 用于处理 Java 方块／物品模型 JSON（仅支持长方体 elements）。创建模型后，可通过类型化操作进行编辑，并针对资源包进行验证：

mc-asset model create --spec ./docs/assets/showcase/model-shrine.json \
  --output ./pack/assets/mypack/models/block/shrine.json --mkdir --resource-pack-version 75
mc-asset model validate ./pack/assets/mypack/models/block/shrine.json \
  --pack ./pack --resource-pack-version 75
mc-asset validate-pack ./pack --resource-pack-version 75

model apply 接受 --operations，并会全部应用或完全不应用；model export 会放置模型，并在使用 --binding 时，在其旁边写入物品定义和方块状态文件。检查涵盖结构和引用有效性。不会由 Minecraft 客户端渲染结果，因此无法验证外观和游戏内行为。

model preview 根据长方体 elements 渲染固定的诊断图像：三个方形面板并排排列（front = 北面，right = 东面，top = 上表面，北面朝上），每个面板为 --size 像素（64、128 或 256；默认值为 64）：

mc-asset model preview ./pack/assets/mypack/models/block/shrine.json \
  --pack ./pack --size 128 --output ./shrine-preview.png --resource-pack-version 75

必须且只能指定 --output 或 --stdout 其中之一。报告包含面板名称和坐标、输入范围、coverage 和 warnings。缺失的纹理会以固定的棋盘格渲染，并附带警告；元素旋转、非 1/256 的坐标、半透明面以及无法解析的纹理会列为 partial 覆盖范围。不会应用 display 变换和游戏光照：这是诊断视图，而非游戏渲染器。

---

MCP 服务

mc-asset mcp 会启动一个基于与 CLI 相同核心的 stdio MCP 服务，因此工具调用和对应命令会返回相同结果。它公开 27 个工具。

公开的 MCP 工具

工具	功能
analyze_asset	只读检查：尺寸、调色板分布、Alpha 分类和像素艺术启发式分析。
pixelize_asset	将栅格输入（PNG、JPEG、WebP）转换为像素艺术；返回 PNG 字节或 .mcpx 源文件。
render_pixel_asset	编译内联 ASCII 网格字符串或 .grid 文件，并支持可选的批量操作。
apply_asset_operations	对 .mcpx 文本应用原子批量像素／图层／区域变更。
recolor_asset	将纹理调色板映射到内置材质色阶（iron、gold、stone 等）。
create_variants	将源资源扩展为输出目录中的多个材质变体。
validate_asset	检查单张纹理和 .mcmeta 是否符合 Minecraft 要求。
import_asset	将栅格输入（PNG、JPEG、WebP）解码到像素画布，并支持可选的批量操作。
build_asset	将 .mcpx 源文件构建为 PNG 字节或重新序列化的源文件，并支持可选的批量操作。
transform_asset	对栅格或 .mcpx 输入应用一种几何操作（翻转、旋转、裁剪、填充、缩放、平移）。
scale_gui_asset	使用 mcmeta 拉伸／平铺／九宫格映射缩放 GUI 精灵图；仅支持 PNG。
quantize_asset	将不同颜色的数量减少到目标数量或指定调色板，同时保留选定的 RGBA 颜色。
cleanup_asset	检测或修复像素缺陷（isolated、noise、cluster、fringe、outlier、hole、aa）。
palette_asset	只读调色板 extract／inspect 报告（唯一颜色、分布、角色、对比度）。
material_asset	对内置材质集生成只读 list／show 报告。
tile_asset	分析接缝、边缘重复和亮度，并可选生成平铺预览 PNG。
generate_asset	确定性程序化纹理生成（图案、尺寸、调色板、种子）。
preview_asset	提供 ascii／palette-map 报告，以及 scale 和 nine-slice 指引 PNG。
mcmeta_asset	根据 PNG 生成动画或 GUI 缩放元数据。
animate_asset	对帧集执行动画 pack／unpack／reorder／resize／validate／preview 操作。
validate_pack_asset	只读扫描整个资源包：命名空间、模型、纹理、图集、版本目标。
inspect_asset	只读 structure（图层、区域、颜色用法、重叠）或 view（合成 PNG 图像块及元数据）；接收 inputPath。
optimize_asset	将 PNG 无损重新编码为体积最小且内容完全一致的编码（或保留源文件）；提供逐文件报告、dryRun、显式 outputPath／outputDir，或扫描整个目录（inputDir、recursive，最多 4096 个 PNG）。
model_asset	Java 方块／物品模型 JSON：inspect、validate、create、apply、export（包含物品定义和方块状态绑定）以及 preview（通过 size／outputPngPath 生成固定的诊断三视图 PNG）。报告结构和引用，不报告渲染外观。
compare_assets	比较尺寸相同的 PNG；报告原始 RGBA 和可见差异、边界框，以及可选的诊断差异图像。
style_asset	风格预设、自定义风格创作、调色板导出、代码检查和纹理系列审计。
pack_asset	资源包项目：搭建脚手架（init）、配方批量构建（build）、纹理编目（catalog）、资源提取（extract）、含优先级修复建议的全包检查（check），以及可复现的 zip 打包（package）。
inspect_asset 有两种模式：structure 会报告图层、区域、颜色用量和重叠情况；view 会以 PNG 图像块的形式返回合成画布，并可选择使用 crop 和 scale（1–16）。如果视图宽度超过 1024px，则会拒绝请求并提示裁剪，而不是缩小图像。apply_asset_operations 接受可选的 feedback 对象（Recipe 7）；不提供时，结果不会改变。docs/mcp-guide.md 为每个工具提供了一次已记录的调用示例。

配置

每个客户端都运行相同的 stdio 命令：npx -y mc-asset mcp。配置文件位置会因客户端版本而异；如果下方列出的位置已变更，请查阅相应客户端的文档。

Claude Code

claude mcp add mc-asset -- npx -y mc-asset mcp

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mc-asset": {
      "command": "npx",
      "args": ["-y", "mc-asset", "mcp"]
    }
  }
}

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "mc-asset": {
      "command": "npx",
      "args": ["-y", "mc-asset", "mcp"]
    }
  }
}

OpenCode

添加到 opencode.json 或 opencode.jsonc：

{
  "mcp": {
    "mc-asset": {
      "type": "local",
      "command": ["npx", "-y", "mc-asset", "mcp"],
      "enabled": true
    }
  }
}

---

命令参考

类别	命令	说明
导入与构建	import <image>	将 PNG、JPEG 或 WebP 解码为 PNG 和／或 .mcpx。
	render <grid>	将 ASCII 网格（.grid）编译为 PNG 和／或 .mcpx。
	build [source]	将 .mcpx 源文件或标准输入（--stdin）构建为 PNG。
变换与几何	transform <input>	空间操作：--flip、--rotate、--crop、--pad、--resize、--translate。
颜色与清理	quantize <input>	将颜色减少到指定数量（--colors <N>）或显式调色板（--palette），并支持 --keep-color。
	cleanup <input>	移除瑕疵（--fix isolated,noise,outlier）。
	palette extract	从图像中提取调色板。
	palette inspect	详细分析调色板并映射颜色角色。
	material list	列出内置的 Minecraft 材质。
	material show	显示材质的颜色渐变。
	recolor <source>	使用材质渐变重新映射 .mcpx 颜色。
	variant <source>	生成多个材质变体到 --output-dir。
生成与平铺	generate <pattern>	确定性地生成程序纹理（--seed <int>）。
	tile <input>	测量接缝并自动修正平铺。
	preview <input>	可视化预览：--ascii、--palette-map、--scale <N>、--nine-slice。
	gui-scale <input>	使用 mcmeta 的拉伸／平铺／九宫格映射，将 GUI 精灵缩放到 --size <N|WxH>。
动画	animate pack	将帧目录打包为精灵图集。
	animate unpack	将精灵图集解包到帧目录。
	animate reorder	重新排列动画帧的顺序。
	animate resize	重新缩放动画帧。
	animate validate	根据 .mcmeta 验证帧数和布局。
	animate preview	以 ASCII 或诊断视图预览动画序列。
	mcmeta animation|gui	根据 PNG 尺寸生成 .mcmeta 动画或 GUI 缩放文档（--output、--stdout）。
验证	analyze <image>	只读指标分析（颜色、Alpha、尺寸）。
	inspect <input>	只读结构报告或合成视图（--mode structure|view、--crop、--scale）。
	validate <asset>	验证单个资源纹理及可选的 .mcmeta。
	validate-pack <path>	验证整个资源包根目录。
	compare <before> <after>	比较两个尺寸相同的 PNG；报告原始 RGBA 和可见差异，并可选生成诊断 PNG（--output、--stdout、--scale）。
优化与模型	optimize <input...> 或 --input-dir <dir>	无损地将 PNG 重新编码为最小的精确编码，或保留源字节（--output、--output-dir、--stdout、--dry-run、--mode、--ancillary、--recursive）。
	model inspect|validate <file>	只读报告 Java 方块／物品模型 JSON（结构、UV、旋转、显示、引用）。
	model create|apply|export	构建、编辑或放置 Java 模型（长方体 elements）及其物品定义和方块状态。
	model preview <file>	生成固定的诊断三视图 PNG（front、right、top 面板，--size 64|128|256、--output 或 --stdout）；对不支持的内容仅提供部分覆盖，且绝非游戏渲染图。
Agent 接口	mcp	启动 stdio MCP 服务。

生成动画和 GUI 元数据（mcmeta）

mc-asset mcmeta animation sheet.png --frame-size 16 --frametime 2 --frames '[0,{"index":1,"time":4},0]' --minecraft-version 1.21.2 --output sheet.png.mcmeta
mc-asset mcmeta gui panel.png --type nine_slice --border 4 --stretch-inner --resource-pack-version 42 --stdout

• animation
  • 必需：--frame-size <N|WxH>（PNG 中由相同帧组成的单行或单列；不支持网格）。
  • 可选：--frametime <int>（默认值为 1）、--frames <json>（帧索引或 {index,time} 对象，时间必须为正整数）、--interpolate。
• gui
  • 必需：--type <stretch|tile|nine_slice>；nine_slice 还需要 --border <N|json>，其中 left、top、right、bottom 必须为非负数，且中心必须为正数。
  • 可选：--stretch-inner（仅适用于 nine_slice）。GUI 缩放要求包格式为 16.0（stretch_inner 要求 42.0）；有关版本限制和输出选项，请参阅 docs/cli-surface.md。

比较 PNG 变更（compare）

mc-asset compare before.png after.png --json
mc-asset compare before.png after.png --output diff.png --scale 4
mc-asset compare before.png after.png --stdout --json > diff.png

比较两张尺寸相同的 PNG，并报告 rawChangedPixels、visibleChangedPixels、rawBounds 和 visibleBounds。使用 --output 或 --stdout（--scale 1..16，最长边不超过 1024px）时，会写入诊断标记 PNG：可见变更标为洋红色（255,0,255,255），仅原始数据发生变化的透明像素 RGB 变更标为青色（0,255,255,255），未变更像素则为透明。

---

批量操作（--operations）

import、render 和 build 命令支持通过 --operations <path> 或 --operations -（标准输入）进行批量像素编辑。

[
  { "type": "setPixel", "x": 0, "y": 0, "color": "#FF0000FF" },
  { "type": "drawLine", "from": [0, 0], "to": [15, 15], "color": "#00FF00FF" },
  { "type": "fillRect", "rect": { "x": 2, "y": 2, "width": 4, "height": 4 }, "color": "#FFFF00FF" },
  { "type": "floodFill", "x": 5, "y": 5, "color": "#0000FFFF" },
  { "type": "clearPixel", "x": 0, "y": 0 }
]

• 原子性：执行要么全部成功，要么全部失败。如果某项操作失败（例如超出边界），批次中此前的所有操作都会回滚。
• 颜色值：接受 transparent、#RRGGBB 或 #RRGGBBAA。
• 操作类型：共 25 种带类型的变体，包括 9 种像素操作（setPixel、clearPixel、drawLine、drawRect、fillRect、floodFill、ellipse、polygonFill、strokeMask），以及图层、区域、stampRect 和 regionFromSelection 操作。各类型的完整表格见 docs/cli-surface.md。
• 形状：ellipse 在 rect 内填充椭圆或绘制其轮廓；polygonFill 接受最多 4096 个整数 [x, y] 点（超过上限会报错 RESOURCE_LIMIT_EXCEEDED；自相交环会报错 SELF_INTERSECTING_POLYGON；不支持孔洞）；strokeMask 在一个图层上描绘 source 选区的轮廓。
• 选区：像素操作可接受可选的 selection 表达式；若匹配结果为空，则拒绝写入并报错 EMPTY_SELECTION，同时回滚整个批次。

---

架构与可靠性保证

                  ┌─────────────────────────────────┐
                  │          mc-asset Core          │
                  │  PixelCanvas • IO • Algorithms  │
                  └───────────────┬─────────────────┘
                                  │
                 ┌────────────────┴────────────────┐
                 │                                 │
     ┌───────────▼───────────┐         ┌───────────▼───────────┐
     │     CLI Interface     │         │   Native MCP Server   │
     │  (Terminal & Scripts) │         │  (Stdio Agent Bridge) │
     └───────────────────────┘         └───────────────────────┘

确定性模型

1. 字节完全一致的 PNG 编码：使用固定的 deflate 压缩级别和过滤策略（src/io/png.ts），并以纯整数进行颜色混合。输出文件不嵌入时间戳或主机元数据。
2. 由种子驱动的 PRNG：程序化生成完全依赖通过 --seed 初始化的整数 xorshift32 PRNG。
3. 跨运行时一致性：对于 scripts/compare-runtime.mjs 测试矩阵涵盖的命令，Bun 生成的输出字节与 Node.js 生成的字节完全一致。

文件与通道安全

• 原子写入：每个输出文件都会写入目标目录中的唯一临时文件（.tmp-<pid>-<counter>-<randomhex>-<original name>），并通过原子重命名提交。
• 冲突防护：路径会转换为绝对规范化路径，并进行 Unicode NFC 规范化和大小写折叠。未指定 --in-place 却将输入路径用作输出路径，或定义重复的输出目标时，会在任何字节写入磁盘前失败。
• 通道隔离：
  • 未指定 --stdout 时：面向用户的日志输出到 stdout。指定 --json 时，结构化 { success, result, error } 信封输出到 stdout，日志输出到 stderr。
  • 指定 --stdout 时：stdout 仅用于输出原始工件字节。信封和日志输出到 stderr。

标准化退出码

退出码	类别	含义
0	成功	操作成功完成。
1	内部错误	引擎发生未处理的故障（INTERNAL_ERROR）。
2	调用无效	语法错误、选项冲突或缺少参数（INVALID_ARGUMENT）。
3	验证失败	引擎执行成功，但资源或包未通过验证（VALIDATION_FAILED）。
4	文件系统错误	输出已存在但未使用 --force、目录不存在但未使用 --mkdir，或输入无法读取。
5	不支持 / 超出限制	文件类型不受支持，或超出大小或资源限制。

---

开发

# Run test suite
bun test

# Run TypeScript type check
bun run test:typecheck

# Run linter
bun run lint

# Build standalone distribution bundles
bun run build

# Verify cross-runtime byte parity (Bun vs Node)
node scripts/compare-runtime.mjs

# Check doc links, anchors, and stray release versions
bun run check:docs

---

许可证

MIT © 2026 Smile Minecraft Project