mc-asset — Minecraft Pixel Asset Engine

mc-asset

English | 繁體中文 | 简体中文

mc-asset is a texture and model tool for Minecraft Java Edition resource packs, built for both creators and AI agents over the command line (CLI) or MCP.

Language models can't place pixels by eye, so mc-asset turns texture work into text and commands: draw a sprite as a character grid, pixelize reference art, generate tiling textures, pack animation sheets, preview cuboid models, and validate a whole resource pack, from a shell or over MCP. The same input and seed always produce identical files.

Six 16×16 items, each written as a text grid and drawn by mc-asset render (shown ×6), following the vanilla style rules in the minecraft-pixel-art skill. The grids are in docs/assets/showcase/items/.

---

Contents

• What It Does
• Highlights
• Showcase
• Installation
• For AI agents
• Quickstart
• Practical Recipes
• MCP Server
• Command Reference
• Batch Operations (--operations)
• Architecture & Reliability Guarantees
• Development
• License

---

What It Does

• Draw textures from text character grids (render)
• Downsample reference art into pixel art (pixelize) and reduce colors (quantize)
• Fan one sprite out into material variants (variant)
• Generate and seam-check tiling textures (generate, tile)
• Pack animation sprite sheets and write .mcmeta files (animate, mcmeta)
• Scale GUI sprites with nine-slice borders (gui-scale)
• Compare two PNGs pixel by pixel (compare)
• Validate a single texture or a whole resource pack (validate, validate-pack)
• Losslessly compress PNGs (optimize)
• Create, validate, and preview Java block models (model)
• Author complete resource packs from declarative recipes, audit styles, catalog vanilla assets, and export reproducible zips (pack, style)
• Expose all capabilities to AI agents over an MCP server (mcp)

---

Highlights

• Text in, texture out. Sprites are character grids (.grid) or editable multi-layer sources (.mcpx) that build to PNG. See docs/mcpx-format.md.
• Identical output. No unseeded randomness and integer-only color blending, so PNG and .mcpx output is identical run to run and between Bun and Node.
• One engine, two front ends. The CLI and the stdio MCP server call the same core, so an agent gets the exact same result as a shell script.
• Uniform JSON output. --json always returns { success, result, error } with a stable error code, and logs never mix into stdout data.
• No surprise writes. Every output path is explicit, existing files need --force, and each file is written to a temp file before being renamed into place.

---

Showcase

Every image below is produced by mc-asset itself, with fixed seeds for the generated textures, so the whole set is reproducible. The commands live in docs/assets/showcase/README.md.

Material variants — the sword from the top of this page fanned out into all nine built-in materials (copper, crystal, diamond, gold, iron, netherite, oxidized_copper, stone, wood, shown ×5). Its palette gives each color a role, so the blade and guard take the new ramp while the darkest outline, the white glint, the wooden grip, and the guard's gem keep their colors:

Generated patterns — every generate pattern as a 16px swatch from a fixed seed (shown ×4):

| noise | clustered-noise | stripes | checker | gradient | |:-:|:-:|:-:|:-:|:-:| | | | | | | | brick | spots | veins | cracks | grain | | | | | | |

Seamless tiling — a 16px brick block face (left, ×8) and a 4×4 wall of it (right, ×4); the mortar lines continue across every edge:

Block textures — stone, dirt, and oak planks as 16×16 textures (left, ×8) that tile cleanly across all four edges. On the right is a 4×4 wall of the planks texture (×4):

Animation sheet — four frames of a glowing ore block packed into one vertical strip (×4), the layout Minecraft reads with an .mcmeta animation:

Potion variants and compare — the potion recolored into crystal, gold, and iron (×5) while the glass bottle, wooden cork, and white glint keep their colors; compare of the iron and gold variants finds 72 changed liquid pixels, marked in magenta on the diagnostic (×8):

Button nine-slice — a 16px button frame (left, ×4) scaled to 48×16 with nine-slice (middle, ×4) and with plain stretch (right, ×4); the nine-slice keeps the corners and bevels crisp while the stretch smears them:

Java model three-view preview — a five-cuboid stepped shrine model (model-shrine.json) using the brick, planks, stone, and glowing ore textures shown above. model preview --size 128 looks at it three times: from the front (north, front), from the side (east, right), and from above (top):

---

Installation

Via npm (recommended)

Run the server straight from the registry — no local install needed:

npx -y mc-asset mcp

Install the CLI globally to get the mc-asset command on your PATH:

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

Via Homebrew (macOS / Linux)

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

Via Bun or Node.js (From Source)

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

Prerequisites: tested with Node.js 22 and Bun 1.3. bun run build needs Bun and ./bin/mc-asset.js needs Node.js; with Bun alone, run bun ./bin/mc-asset.js.

---

For AI agents

• llms.txt — a compact index of the repository for agents.
• llms-full.txt — the same material as a single file: install, the twenty-five MCP tools, batch operations, the error model, and the limits.
• docs/cli-surface.md — the frozen CLI commands, the batch operations specification, and the exit-code registry.
• docs/mcpx-format.md — the editable multi-layer .mcpx and .grid grammar and specification.
• docs/mcp-guide.md — registration, one verbatim capture per MCP tool, and the error model.
• docs/mcp-surface.md — the frozen MCP surface: tool names, inputs, and the read/write contract.
• AGENTS.md — the rules for changing this repository.

Agent skills

The repository ships two Agent Skills in skills/, installable with the skills CLI:

npx skills add smile-minecraft/mc-asset

• mc-asset — the draw → render → preview → measure → validate loop with this tool, the CLI/MCP command map, and how palette roles drive recoloring.
• minecraft-pixel-art — the vanilla style rules for items, blocks, GUI sprites, and animations: palettes and hue-shifted ramps, material outlines, top-left light, tiling, and an anti-pattern review checklist.

Add --skill mc-asset or --skill minecraft-pixel-art to install only one.

---

Quickstart

From a Text Grid to a Validated Texture

Draw a 16×16 gem as a character grid, one character per pixel:

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

Render the grid into a PNG texture and save the editable .mcpx source:

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

The rendered gem.png, shown ×8:

Check its colors and 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

Validate it as a Minecraft item texture:

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.

---

Practical Recipes

Recipe 1: Downsampling Reference Art (pixelize)

Turn a high-resolution reference image into a 16×16 item texture. The same image and preset always give the same pixels:

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

• --preset item sets a 16-color budget and turns on the crop, background, subject, edge, and cluster stages.
• The other presets are block, gui, particle, and generic.

Recipe 2: Procedural Textures & Seam Tiling (generate & tile)

Generate a stone texture from a fixed seed, then check whether it tiles:

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

Recipe 3: Palette Quantization & Artifact Cleanup (quantize & cleanup)

Cut a sprite down to 8 colors, then remove the stray pixels left behind:

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

These fix classes can change alpha, and with it the render pass the texture needs, so cleanup refuses them without --allow-render-pass-change.

Recipe 4: Material Variants (variant & recolor)

Fan one source out into several material tiers, or recolor it to a single material. The source can be an editable .mcpx or a flat PNG (a PNG carries no palette roles, so its pixels map by integer luminance bands with no invented layer roles):

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

Recipe 5: Animated Sprite Sheets (animate)

Pack a folder of frames into a vertical sheet, then check it against its .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

Recipe 6: Full Resource Pack Validation (validate-pack)

Scan a whole resource pack for missing textures, bad namespaces, orphaned textures, broken model references, and reference cycles. --minecraft-version picks the pack format to check against:

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

Recipe 7: Batch Edits with Visual Feedback (build & apply_asset_operations)

Edit the Quickstart gem in one batch: a 4×4 gold square framed by a 6×6 black outline. The CLI applies the batch and writes a 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

Before and after the batch (both ×8):

→

Over MCP, apply_asset_operations runs the same batch and can send back a picture of what changed:

{
  "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" }
}

With feedback, the result keeps its usual fields and adds a PNG image block cropped to the changed area and upscaled by scale (1–16), plus a diff summary (raw, composited, structural, outsideSelectionUnchanged). An edit with no visible change returns noVisibleChange instead of an image. The agent sees its edit without pulling the whole canvas. The output path differs from the CLI run because MCP tools never overwrite an existing file.

Recipe 8: Nine-Slice GUI Scaling (gui-scale)

Resize a GUI frame without smearing its border. With nine_slice, the corners copy 1:1 and the edges and center tile (or stretch, with stretch_inner: true). The 16×16 dialog.png declares a 4px border in dialog.png.mcmeta:

{ "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 never picks up a sibling .mcmeta on its own; without --mcmeta it stretches the whole sprite.

| Source, 16×16 | nine_slice, 48×32 | No --mcmeta (stretch), 48×32 | |:-:|:-:|:-:| | | | |

All three are shown ×4. With the mcmeta the cut corners and the 2px bevels copy 1:1 and keep their width; the plain stretch thickens the bevels unevenly and smears the corners.

Recipe 9: Lossless PNG Optimization & Java Models (optimize & model)

optimize re-encodes PNGs into the smallest encoding that holds the same pixels exactly, or keeps the source when nothing is smaller. It takes explicit PNG paths (up to 256 files) or a whole directory (--input-dir, up to 4096 PNGs, optional --recursive, preserving relative paths). It never rewrites its inputs; pick --output, --output-dir, --stdout, or --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 works on Java block/item model JSON (cuboid elements only). Create a model, edit it with typed operations, and validate it against a pack:

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 takes --operations and applies all of them or none; model export places the model and, with --binding, writes an item definition and a blockstate next to it. The checks cover structure and reference validity. No Minecraft client renders the result, so appearance and in-game behavior are not verified.

model preview renders a fixed diagnostic image from cuboid elements: three square panels side by side (front = north face, right = east face, top = up face with north at the top), each --size pixels (64, 128, or 256; default 64):

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

Exactly one of --output or --stdout is required. The report carries panel names and coordinates, the input range, coverage, and warnings. A missing texture renders as a fixed checkerboard with a warning; element rotation, non-1/256 coordinates, translucent faces, and unresolvable textures are listed as partial coverage. display transforms and game lighting are not applied: this is a diagnostic view, not a game renderer.

---

MCP Server

mc-asset mcp starts a stdio MCP server on the same core as the CLI, so a tool call and the matching command return the same result. It exposes 27 tools.

Exposed MCP Tools

inspect_asset has two modes: structure reports layers, regions, color usage, and overlaps; view returns the composited canvas as a PNG image block, with optional crop and scale (1–16). A view wider than 1024px is refused with a crop hint instead of being downscaled. apply_asset_operations takes an optional feedback object (Recipe 7); without it the result is unchanged. docs/mcp-guide.md has one captured call per tool.

Configuration

Every client runs the same stdio command, npx -y mc-asset mcp. Config file locations change between client versions, so check the client's own docs if one below has moved.

Claude Code

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor

Add to .cursor/mcp.json:

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

OpenCode

Add to opencode.json or opencode.jsonc:

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

---

Command Reference

Generate animation and GUI metadata (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
  • Required: --frame-size <N|WxH> (a single row or column of equal frames dividing the PNG; grids are not accepted).
  • Optional: --frametime <int> (default 1), --frames <json> (frame indices or {index,time} objects with positive integer times), --interpolate.
• gui
  • Required: --type <stretch|tile|nine_slice>; nine_slice also requires --border <N|json> with non-negative left, top, right, bottom and a positive center.
  • Optional: --stretch-inner (nine_slice only). GUI scaling requires pack format 16.0 (stretch_inner requires 42.0); see docs/cli-surface.md for version gates and output options.

Compare PNG changes (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

Compares two same-size PNGs and reports rawChangedPixels, visibleChangedPixels, rawBounds, and visibleBounds. With --output or --stdout (--scale 1..16, longest edge at most 1024px), it writes a diagnostic marker PNG where visible changes are magenta (255,0,255,255), raw-only alpha-zero RGB changes are cyan (0,255,255,255), and unchanged pixels are transparent.

---

Batch Operations (--operations)

The import, render, and build commands support batch pixel edits via --operations <path> or --operations - (stdin).

[
  { "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 }
]

• Atomicity: Execution is all-or-nothing. If an operation fails (e.g. out of bounds), all preceding operations in the batch roll back.
• Color Values: Accepts transparent, #RRGGBB, or #RRGGBBAA.
• Vocabulary: 25 typed variants, including 9 pixel operations (setPixel, clearPixel, drawLine, drawRect, fillRect, floodFill, ellipse, polygonFill, strokeMask) plus layer, region, stampRect, and regionFromSelection operations. The full per-type table lives in docs/cli-surface.md.
• Shapes: ellipse fills or outlines the ellipse inside a rect; polygonFill takes up to 4096 integer [x, y] points (more is RESOURCE_LIMIT_EXCEEDED; a self-intersecting ring is SELF_INTERSECTING_POLYGON; no holes); strokeMask outlines a source selection on one layer.
• Selection: Pixel operations accept an optional selection expression; an empty match refuses the write with EMPTY_SELECTION and rolls the batch back.

---

Architecture & Reliability Guarantees

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

Determinism Model

1. Byte-Identical PNG Encoding: Uses fixed deflate levels and filter strategies (src/io/png.ts) with pure integer color blending. Output files do not embed timestamps or host metadata.
2. Seed-Driven PRNG: Procedural generation relies exclusively on an integer xorshift32 PRNG initialized via --seed.
3. Cross-Runtime Consistency: Output bytes produced under Bun match bytes produced under Node.js byte for byte for the commands covered by the scripts/compare-runtime.mjs matrix.

File & Channel Safety

• Atomic Writes: Every output file is written to a unique temporary file (.tmp-<pid>-<counter>-<randomhex>-<original name>) in the target directory and committed via atomic rename.
• Collision Protection: Paths are resolved to absolute normalized paths folded with Unicode NFC and case-folding. Aliasing the input without --in-place or defining duplicate output targets fails before any bytes land on disk.
• Channel Isolation:
  • Without --stdout: Human logs route to stdout. With --json, a structured { success, result, error } envelope routes to stdout and logs route to stderr.
  • With --stdout: Raw artifact bytes exclusively own stdout. Envelope and logs route to stderr.

Standardized Exit Codes

---

Development

# 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

---

License

MIT © 2026 Smile Minecraft Project