PixelForge — 시각 대형 모델 픽셀 아트 제작, 수정 및 애니메이션 제품군은(는) 무엇을 하나요?
이 스킬은 ./scripts/pforge.py를 통해 산업 수준의 픽셀 에셋 생산과 역공학 수정 능력을 제공합니다 (동시에 CLI 명령줄과 pixelforge Python 라이브러리 제공, Pillow만 의존).
1. 핵심 불문율 (절대 위반 금지)
- 희소 좌표 리스트 직접 작성 금지: 수십 줄의
putpixel((x, y))를 늘어놓는 것을 금지합니다. 기본 도형은 고정폭 ASCII 문자 그리드 (.과 공백은 고정적으로 투명을 나타냄), 컴팩트한 로컬 파트Rig(파트 자체만 그리고offset=(ox, oy)로 위치 지정, 캔버스 전체를 점으로 채울 필요 없음), 또는PixelCanvas픽셀 수준 기하 원형(안티-L 코너 직선, 대칭 타원, Bayer ordered dither)을 사용해야 합니다. - 해상도에 따라 올바른 아키텍처 선택:
16x16 ~ 32x32: 전체 캔버스 ASCII 그리드 또는 경량Rig를 직접 작성합니다.48x48 ~ 64x64: 반드시 레이어/파트로 분할 (외곽선 없는 색상 파트 +Rig(..., outline_mode="selout"|"outer")로 자동 통합 외곽선 처리); 국소 수정 시에는 전체 이미지를 다시 그리기보다 Region Patch 로컬 슬라이스를 우선 사용합니다.64x64 ~ 128x128+이상:PixelCanvas기하 밑그림 +stamp()로컬 스탬프 +dither_rect()ordered dither + 로컬 Region Patch 미세 수정을 사용합니다.
- 강제적 다중 모드 전시적 시각 피드백 루프:
- 매 생성 또는 수정 시마다 홀로그램 진단 보드
<name>_inspect.png(내용: 문자 색상 범례[char] #HEX+ 0 기반(X, Y)좌표 그리드 및 바닥 기준선 + 그리드 없는 진하기/연하기 두 가지 배경의 실기 미리보기 + 실루엣과 빨강/청색 양파 껍질 모션 궤적)와 터미널Pixel Linter보고서가 출력됩니다. - 전달 전에 반드시 이미지 뷰어 (예:
read_file/view_image/Read)를 사용하여<name>_inspect.png(수정 작업 시에는<name>_diff.png도)를 직접 확인해야 합니다! - 그림 상의 좌표와 Linter 경고를 대조하여, 외곽선 누락 (특히 밝은 배경 미리보기에서 어두운 외곽선 확인), 사선/곡선 계단형 계단 현상(Jaggies), 프레임 간 발바닥 떠다님(
baseline_y), 예상치 못한 픽셀 변경 등을 하나하나 점검하고 수정한 후 재확인을 통과한 다음에야 전달할 수 있습니다.
- 매 생성 또는 수정 시마다 홀로그램 진단 보드
2. 에이전트를 위한 최단 경로 의사 결정 트리 (우선 순위: 제로 보일러플레이트 코드 우선!)
작업 시작 전 다음 우선순위에 따라 가장 토큰을 절약하고 보일러플레이트 코드가 없는 호출 방식을 선택하세요:
- 색상 팔레트 단일 문자 명암 단계 조회 (문자 추측 오류로 인한 오류 방지):
- MCP:
pixelforge_palette_guide(palette="endesga32"); CLI:python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32 - 색상별로 그룹화된
어두운 부분 -> 중간 톤 -> 하이라이트문자 체인(예:'b' -> 'B' -> 'C')을 직접 얻습니다. 표를 뒤져 추측할 필요가 없습니다.
- MCP:
- 다중 파트 캐릭터 / 보스 / 다중 동작 레이어
.aseprite(0줄 Python 코드, 0 산술 흡착):- MCP 직접 호출
pixelforge_build_rig(또는 CLIpforge.py build-spec spec.json/ Pythonbuild_from_spec(spec)):- 오류 허용 그리드 문법:
|..BBBB..| # 행 끝 주석시각적 정렬 세로선과pad_ragged=True로 누락된 끝.자동 보완 지원! - 의미론적 관절 흡착 (좌표 및 축 계산 불필요): 주 몸통은
at="center"로 설정하고, 나머지 파트는 직접attach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip"로 작성하며,canvas_size="auto"로 전신 바운딩 박스를 자동 계산하고 칼 휘두를 때 잘리지 않도록 여유 공간을 확보합니다. - 한 줄 동작 프리셋:
clips={"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"}(또한"float_bob","slime_bounce"또는 사용자 정의poses지원), 자동으로 칼빛/연기 효과, 그림자 및 다중 레이어.aseprite포함!
- 오류 허용 그리드 문법:
- MCP 직접 호출
- 16x16 ~ 32x32 아이콘 및 단일 프레임 소형 오브젝트:
- MCP 직접 호출
pixelforge_build(외곽선 없는 색상 블록을 직접 그리고outline_mode="selout", add_shadow=True전달하여 자동 외곽선 및 그림자 추가 지원).
- MCP 직접 호출
- 복잡한 프로그래매틱 기하 / 등축 투영 / 실기 전투 샌드박스 스크립트:
- 먼저
python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|iso를 실행하여 상대 경로sys.path가 자동으로 설정된 실행 가능한 스켈레톤을 생성하고, 그 안에 로직을 채워 넣습니다 (수동 경로 연결 및 디버깅 불필요).
- 먼저
3. 6가지 표준 작업 흐름
1. 픽셀 아트 및 다중 동작 애니메이션 처음부터 제작
- 팔레트 선택: 사전 정의된 클래식 팔레트
"endesga32","pico8","sweetie16","resurrect64","gameboy"중에서 우선 선택하거나,pforge.py palette <ref.png>로 참조 이미지의 팔레트와 명암 단계를 추출합니다. 기본은 왼쪽 위 광원 (왼쪽 위 하이라이트는 따뜻하게, 오른쪽 아래 어두운 부분은 차갑게 이동)이며,outline_mode="selout"(적응형 광원 외곽선)을 권장합니다. - 제작 및 바인딩:
- 위상 변화가 큰 경우 (걷기 다리 교차, 입 벌려 송곳니 변형) -> ASCII 키프레임 또는
Part다중 상태 딕셔너리{"closed": ..., "open": ...}를 사용합니다. - 강체 회전/압축 (뚜껑이 경첩을 따라 열림, 칼 휘두름, 호흡 반동) ->
Rig+rotsprite앵커 포인트 회전 및squash_stretch를 사용합니다. - 타격감 리듬 -> 반드시 비균일
durations_ms(예: 차징180ms-> 폭발적 베기40ms-> 정지 프레임55ms-> 완충150ms)를 사용하고,vfx_slash_arc/vfx_dust_puff/vfx_hit_spark를 함께 사용합니다. - 단일 캐릭터 다중 동작 (
idle/walk/attack) ->SpriteActor를 사용하여 독립 애니메이션과 병합 시트<actor>_master_atlas.png/.json을 한 번에 내보냅니다.
- 위상 변화가 큰 경우 (걷기 다리 교차, 입 벌려 송곳니 변형) -> ASCII 키프레임 또는
- 스크립트를 실행하여 GIF + 진정한 반투명 APNG + 무손실 동적 WebP + Aseprite JSON을 내보내고,
_inspect.png를 읽어 시각적 자가 점검하고 결함을 제거합니다.
2. 기존 픽셀 아트 기반 수정 (PNG / GIF / 스프라이트 시트)
- 먼저 이미지를 진단:
(참고: 엔진이python3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/4x/8x정수배 확대 미리보기 이미지를 자동으로 인식하고 무손실로1x원본 픽셀 그리드로 복원합니다. 원래 크기를 유지하려면--keep-scale을 추가하세요.) - 작은 이미지/전체 프레임 역컴파일 수정:
모든 프레임과 프레임 지속 시간을 자동으로 분해하고, 의미 있는 문자 색상 팔레트가 포함된python3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/edit_walk.py와_inspect.png를 생성합니다. 스크립트를 수정한 후 다시 실행하면 됩니다. - 큰 이미지 국소 부위 정밀 수정 (Region Patch, 48x48+에 강력 권장):
생성된# 1) 0 기반 좌표 상자 (X,Y,W,H)를 기준으로 로컬 그리드를 잘라내고, 생성된 자가 점검 이미지에는 전역 X/Y 좌표 눈금이 자동으로 유지됩니다! python3 <SKILL_DIR>/scripts/pforge.py region-extract hero.png --box 14,6,20,18 -o work/patch/ # 2) 잘라낸 .txt 문자 그리드를 편집한 후 다시 쓰면, Before | After | Diff 삼중 비교 이미지가 자동으로 출력됩니다 python3 <SKILL_DIR>/scripts/pforge.py region-apply hero.png --patch work/patch/hero_x14_y6_w20_h18.json -o work/out/*_diff.png를 반드시 읽어 변경 사항이 대상 영역 내에 엄격하게 속하고 가장자리 연결이 자연스러운지 확인합니다. - 한 번의 명령으로 의미 기반 색상 변경 / 진영 변형:
python3 <SKILL_DIR>/scripts/pforge.py recolor slime.gif --map B=R,b=r,C=Y -o work/fire_slime/
3. 고해상도 이미지 / AI 컨셉 스케치를 픽셀 아트로 변환 (Pixelate & Clean)
사용자가 고해상도 일러스트, 사진 또는 가장자리가 흐릿한 AI "의사 픽셀 아트"를 제공할 때:
# 일러스트/컨셉 아트는 contrast_box 사용; AI 의사 픽셀 아트는 --mode dominant_block 사용하여 비뚤어진 그리드와 잡음 제거
python3 <SKILL_DIR>/scripts/pforge.py pixelate draft.png --size 48x48 --palette endesga32 --outline "#181425" -o work/px/
생성된 *_compare.png와 *_inspect.png를 읽고, 자동 생성된 edit_*.py에서 수동으로 눈 하이라이트를 그리고, 윤곽 계단을 수정한 후 전달합니다.
4. 끊김 없는 맵 타일, 47개 블록 자동 지형 (Auto-Tile), 9슬라이스 UI, 등축 투영 및 실기 씬 명도 자가 점검
- 끊김 없는 단일 타일 및 9슬라이스 UI:
pforge.py tile grass.png(3x3 접합 단층을 빨간색으로 감지);pforge.py nine-slice frame.png --margins 4,4,4,4 --size 160x56. - 47개 블록 Blob / 16개 블록 Wang 자동 지형 타일링: 전경/배경 두 개의 기본 타일만 제공하고,
pforge.py autotile --fg grass.png --bg water.png --mode blob47(또는 Pythongenerate_blob47_tileset)를 호출하면 모든 내부/외부 모서리를 자동으로 합성하고 테스트 군도 맵*_blob47_inspect.png를 배치합니다. 2:1등축 투영 건물 및 4/8 방향 RPG 캐릭터:IsoScene을 사용하여 갈라짐 없는2:13면 조명 등축 투영 블록 씬을 구축합니다.DirectionalRig+export_multidir_sheets를 사용하여 정면 파트에서S/E/N/W4방향 또는 8방향 회전 및 걷기 시트를 파생하고,*_alignment_inspect.png를 읽어 머리/발 수평 정렬선을 확인합니다.- 다중 에셋 실기 씬 샌드박스 및 회색 명도 자가 점검:
SceneComposer+render_pixel_text(내장 컴팩트 픽셀 폰트) +build_scene_mockup을 사용하여 Y축 순서 정렬 및 점프 문자 UI가 포함된 실기 전투/탐험 애니메이션을 합성합니다. 반드시*_scene_inspect.png를 읽어 순수 회색조 눈 감은 이미지와 윤곽 대비 히트맵을 확인하여 캐릭터가 배경에 묻히는 명도 충돌 문제를 제거합니다.
5. HD-2D 픽셀 법선 동적 조명 및 "생성 이미지 분해 → 자동 뼈대 연결 (Sketch-to-Rig)"
- HD-2D 법선 맵 및 360° 횃불 조명:
pforge.py normalmap hero.png --emit "#2CE8F5"또는export_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"}))를 호출하여 Godot/Unity 호환*_albedo.png,*_normal.png,*_emission.png및*_torch_orbit_6x.gif를 한 번에 내보내고*_hd2d_inspect.png4사분면 점 광원 검증 이미지를 확인합니다. - 폭발 설정 이미지 자동 분해 및 뼈대 연결 (Sketch-to-Rig): 단색 배경 파트 분해 컨셉 이미지에 대해
pforge.py autorig sheet.png --canvas 56x56 --palette endesga32(경계 범람 안전 배경 제거, 연결 요소 분해, 균일 비율 색상 잠금, 어깨/목/칼자루 축 추론)를 실행하고,*_autorig_pipeline.png를 확인한 후 생성된rig_*.py에서 동작을 정밀 수정합니다.
6. 네이티브 .aseprite 바이너리 레이어 프로젝트 읽기/쓰기 및 MCP 도구 직접 호출
- 양방향
.aseprite프로젝트 지원: 모든 제작 흐름은 기본적으로 네이티브 바이너리<name>.aseprite를 직접 출력합니다.Rig.render_named_layers_sequence(poses)+write_aseprite(...)를 사용하여 각 파트와 효과를 독립적인 타임라인 레이어 + 동작 레이블 + 관절 축 Slice로 저장하여, 인간 아티스트가 Aseprite에서 직접 레이어별로 계속 그릴 수 있습니다. 기존.ase/.aseprite파일은pforge.py aseprite-inspect file.aseprite --unpack-layers또는decompile로 역분해할 수 있습니다. - MCP 네이티브 도구 우선: 현재 세션이
pixelforgeMCP Server에 연결되어 있다면 (pixelforge_palette_guide,pixelforge_build,pixelforge_build_rig,pixelforge_region_patch,pixelforge_scene_check,pixelforge_aseprite_inspect등 12개 도구 제공, 각 반환마다agent_checklist.must_view_images및(x, y)수정 처방전이 첨부됨), 임시 스크립트를 직접 작성하는 대신 MCP 도구를 직접 호출하는 것을 우선합니다.
4. Python 제로 산술 선언형 템플릿
import sys
sys.path.insert(0, "/path/to/pixel-forge/scripts")
from pforge import build_from_spec, format_palette_guide
# 제로 산술 좌표로 다중 파트, 다중 동작, 독립 레이어 .aseprite 캐릭터 구축
res = build_from_spec({
"name": "ember_knight",
"palette": "endesga32",
"canvas_size": "auto",
"outline_mode": "selout",
"parts": [
{"name": "torso", "at": "center", "grid": ["|..RRRR..| # 흉갑", "|.RYYYYR.|", "|RRRRRRRR|", "|.rrrrrr.|"]},
{"name": "head", "attach_to": "torso", "side": "top", "grid": ["|.1111.|", "|1KKKK1|", "|.2222.|"]},
{"name": "sword", "attach_to": "torso", "side": "right", "hinge": "grip", "outline_group": 1,
"grid": ["|.W.|", "|.1.|", "|YYY|", "|.o.|"]},
],
"clips": {"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"},
}, output_dir="output")
# 그 후 반드시 시각 도구를 사용하여 res["agent_checklist"]["must_view_images"]의 모든 대시보드를 확인하세요!
5. 고급 참조 매뉴얼 (필요시 읽기, 점진적 공개)
특정 세부 작업을 실행하기 전에 필요에 따라 이 스킬 디렉토리에 있는 주제별 가이드를 참조하세요:
- 픽셀 아트 조형, 색상 클러스터 안티앨리어싱, 명암 단계 및 디더링 기법: craft_and_shading.md
- 역컴파일, 대형 이미지 로컬 패치 수술 및 AI 이미지 픽셀화 정밀 수정: edit_and_pixelate.md
- 다중 파트 골격 Rig, RotSprite 회전, 타격감 프레임 길이 레시피 및 효과 라이브러리: animation_and_rigging.md
- 끊김 없는 Tileset 3x3 접합 설계 및 9-Slice UI 규격: tileset_and_ui.md
- 47개 블록 자동 지형, 실기 씬 명도 자가 점검, 2:1 등축 투영 및 4/8 방향 캐릭터 파생: world_iso_and_scene.md
- HD-2D 픽셀 법선 동적 조명 및 AI 설정 이미지 자동 분해 뼈대 연결: hd2d_and_autorig.md
- 네이티브
.aseprite레이어 바이너리 프로젝트 읽기/쓰기 및 MCP Server 가이드: aseprite_and_mcp.md - 전체 CLI 인수 및 Python API 빠른 참조 사전: cli_and_api.md
- 실행 가능한 실전 예제 스크립트:
./examples/디렉토리 아래 10개의 종단간 스크립트 (01~10)를 참조하세요.