blockpixel-artist

快速开始

安装依赖

pip install -r requirements.txt

Codex 中可以从 GitHub 的 Skill 目录安装

$skill-installer install https://github.com/yzxr123/blockpixel-artist/tree/main/skill/blockpixel-artist

安装后调用

$blockpixel-artist 生成一个 64x64 的仙人掌镐子 透明背景

项目介绍

BlockPixel Artist 是一套专门用于生成 Minecraft 风格像素素材的 Agent Skill

它不是先生成高清插画再缩小

而是要求从一开始就在用户指定的目标像素网格上完成构图和细节制作

当前重点解决普通 AI 像素生成最常见的几类问题

• 物体虽然好看但结构不符合正常游戏美术经验
• 武器和工具比例错误或整体歪斜
• 技能图标特效很多但技能机制无法一眼读懂
• 64×64 或 128×128 只是小图整倍放大
• 为了填满画面无意义增加符文 宝石 光环 尖刺等元素
• 输出只有本地文件路径而没有预览和可下载 PNG

默认方向为

接近原版的高可读性 + 适量商业游戏细节强化

核心能力

能力	说明
原生像素网格	按用户指定尺寸直接制作 不依赖高清图缩小
默认透明背景	独立物品 技能图标和素材默认透明 PNG
Template First	先确定方向 比例 连接点和主体结构 再增加材质细节
Canonical Lock	对标准原型锁定 Minecraft 原版宏观轮廓
游戏美术经验层	拦截看起来精致但结构 功能或因果关系错误的设计
技能图标专项	覆盖攻击 防御 治疗 位移 控制 召唤 元素 被动 蓄力 范围等机制
大尺寸细节规则	64×64 128×128 必须增加真实像素信息
学习先验	使用训练数据蒸馏后的统计和经验规则 不携带原始训练素材
自动校验	检查 Art Plan Alpha 调色板 模板偏移 轮廓和常识错误
图片交付	完成后必须提供预览和用户可点击的下载文件

真实生成案例

以下示例均按目标尺寸直接绘制像素结构

不经过高清插画缩小或后期像素化

示例文件均为项目自有展示素材 不包含 Minecraft 原版纹理

Canonical Item

仙人掌镐子用于展示标准工具原型的结构约束

宏观轮廓和使用方向保持稳定

新增分辨率用于仙人掌表皮 棱线 刺 明暗和连接细节

Skill Icon

雷电冲刺用于展示技能机制表达

构图优先保证冲刺方向 速度和雷电路径能够被快速识别

而不是依靠无意义符文 光环或装饰填充画面

High Detail

冰霜药水用于展示原生像素细节

64x64 的额外空间用于玻璃 液体 冰晶 高光 折射和结霜层次

而不是把低分辨率图标直接整倍放大

工作流程

用户需求
  ↓
识别素材类别和机制
  ↓
查询训练先验
  ↓
匹配原型模板
  ↓
建立 Art Plan
  ↓
在目标像素网格直接绘制
  ↓
结构 轮廓 调色 Alpha 常识校验
  ↓
失败则针对问题返修
  ↓
返回预览和可下载 PNG

原版模板

公开仓库不附带 Minecraft 原版纹理

需要精确 Canonical Lock 时 用户可以提供自己合法取得的 Bedrock 资源包或 textures/items 目录

python skill/blockpixel-artist/scripts/import_bedrock_textures.py \
  "/path/to/resource-pack-or-textures.zip" \
  --clean

支持

• 完整 Bedrock 资源包目录
• textures 目录
• textures/items 目录
• 包含 textures/items/*.png 的 ZIP

导入后会在本地自动建立原版物品索引和结构模板

这些本地游戏资源路径已经写入 .gitignore 不应提交到 GitHub

当前模板族

pickaxe
sword
axe
shovel
hoe
helmet
chestplate
leggings
boots
bow
crossbow
trident
book
potion
elytra

例如生成 64×64 仙人掌镐子

标准模式会保留镐子的原版宏观结构

增加的分辨率用于仙人掌材质 棱线 刺 表面变化 高光 阴影和连接细节

而不是重新发明一个新的镐子轮廓

使用示例

物品

调用 blockpixel-artist
生成一个 32x32 的黑曜石紫水晶长剑
保持标准 Minecraft 剑的宏观轮廓
透明背景

大尺寸物品

调用 blockpixel-artist
生成一个 128x128 的仙人掌镐子
保持标准镐子宏观轮廓
必须增加真实像素细节
禁止整倍放大小图
透明背景

技能图标

调用 blockpixel-artist
生成一个 64x64 雷电冲刺技能图标
必须一眼看出冲刺方向
不加入与机制无关的符文和装饰
透明背景

方块纹理

调用 blockpixel-artist
生成一个 32x32 风化铜机械方块纹理
保持可平铺逻辑
不使用透明背景

常用脚本

查询对象模板

python skill/blockpixel-artist/scripts/find_template.py "cactus pickaxe" --json

查询学习先验

python skill/blockpixel-artist/scripts/query_priors.py --list
python skill/blockpixel-artist/scripts/query_priors.py bedrock-items:sword

检查 Art Plan

python skill/blockpixel-artist/scripts/validate_art_plan.py plan.json

检查最终像素图

python skill/blockpixel-artist/scripts/validate_pixel_art.py output.png --width 64 --height 64 --asset-class item

检查原版轮廓

python skill/blockpixel-artist/scripts/validate_vanilla_silhouette.py output.png pickaxe --json

项目结构

blockpixel-artist/
├─ README.md
├─ LICENSE
├─ requirements.txt
├─ docs/
│  ├─ assets/
│  │  └─ logo.png
│  └─ examples/
│     ├─ cactus_pickaxe_64.png
│     ├─ lightning_dash_64.png
│     └─ frost_potion_128.png
└─ skill/
   └─ blockpixel-artist/
      ├─ SKILL.md
      ├─ agents/
      │  └─ openai.yaml
      ├─ assets/
      │  └─ template-definitions.json
      ├─ references/
      └─ scripts/

关于训练数据

公开仓库只保留训练后蒸馏得到的统计先验 规则和验证逻辑

不会公开或重新分发训练时使用的第三方商业素材和 Minecraft 原版纹理

因此仓库体积较小并不代表没有训练数据

Skill 实际运行依赖的是蒸馏后的规则和统计结果 而不是把数千张训练图片全部打包进去

版本

当前公开版本

v1.0.0

建议 GitHub Release 同样使用

Tag: v1.0.0
Title: BlockPixel Artist v1.0.0

开源协议

项目代码和自有内容使用 Apache License 2.0

Minecraft 资源说明

BlockPixel Artist 是独立社区项目

它不是 Mojang Studios 或 Microsoft 的官方产品 也没有得到其批准或授权

本仓库不包含 Minecraft 原版纹理 模型 音频或其他游戏文件

使用精确原版模板功能时 需要由用户自行提供合法取得的资源文件