aldegad/sprite-gen

sprite-gen

하나의 그림을 넣으면, 게임에 바로 쓸 수 있는 스프라이트 아틀라스가 나옵니다.

English · 한국어 · 日本語 · 简体中文 · Español · Français

이미지 모델에 "스프라이트 시트"를 요청해 본 적이 있다면 결과가 어떤지 알 것입니다: 매 프레임마다 얼굴이 바뀌는 캐릭터, 키잉(keying)이 안 되는 배경, 겹치고 그리드에서 벗어난 포즈, 그리고 게임 엔진이 실제로 사용할 수 없는 PNG. 귀여운 데모일 뿐, 쓸모없는 에셋입니다.

sprite-gen은 이러한 격차를 해소하는 Codex/Claude 스킬입니다. 하나의 기본 이미지와 동작 목록을 입력하면, 행(row) 단위로 생성을 진행하고, 캐릭터의 정체성을 고정하며, 크로마 배경을 실제 알파로 제거하고, 각 포즈를 깨끗한 투명 프레임으로 추출한 후, 기계가 읽을 수 있는 manifest.json.frame_layout과 함께 런타임 아틀라스를 만듭니다. 위의 모든 스프라이트가 이 방식으로 만들어졌습니다.

그리고 생성만으로는 절대 완벽하게 잡을 수 없는 마지막 10%를 위해 큐레이션 웹뷰(webview)가 있습니다: 프레임을 나란히 비교하고, 망가진 프레임을 제거하고, 회전/크기/위치를 비파괴적으로 조정하고, 루프를 실시간으로 확인한 다음, 최종 결과물을 만듭니다. 파이프라인이 노동을 처리하고, 당신은 감각을 유지합니다.

sprite-request.json → layout guides + prompts → image-gen state rows
→ chroma alpha → connected components → transparent frames
→ sprite-sheet-alpha.png + manifest.json.frame_layout

전체 아키텍처: docs/architecture.md · 다이어그램 소스: docs/architecture-diagram.html

실제로 얻을 수 있는 것

• 투명 스프라이트 아틀라스 (sprite-sheet-alpha.png) — 실제 알파, 크로마 잔여물 없음, 흰색 배경에서 검증됨.
• 런타임 매니페스트 (manifest.json.frame_layout) — 절대 프레임 사각형, 상태별 fps 및 루프 플래그. 엔진이 사각형을 샘플링하며, 그리드를 추측하지 않습니다.
• 직접 확인 가능한 QA — 상태별 GIF 및 연락처 시트(contact sheet)를 제공하여, 움직임을 실제 움직임으로 판단할 수 있습니다.
• 정직한 레이블 — 짧고 읽기 쉬운 동작(idle, jump, attack, wave)이 안정적인 경로이며, 순환 locomotion(walk/run)은 모션 QA가 실제로 통과하지 않는 한 실험적(experimental)으로 표시됩니다. 조용히 과장하지 않습니다.

큐레이션 웹뷰

생성으로 90%를 얻습니다. 웹뷰는 사람이 그것을 출시 상태로 만드는 곳입니다 — 독립 실행형이며, Studio나 프레임워크 의존성이 없고, 스킬이 설치된 모든 곳(Claude Code Desktop, Codex 앱, 일반 터미널)에서 실행됩니다.

• 상태별 두 줄: 상단에 재생 시퀀스, 하단에 후보 풀(예: 두 번째 또는 세 번째 생성본). 프레임의 ⠿ 그립을 드래그하여 시퀀스를 재정렬하거나, 풀에서 컷을 끌어올릴 수 있습니다 — 여러 생성본 중 최상의 프레임으로 하나의 깔끔한 실행 루프를 재구성합니다. 배열은 저장되므로 다시 열면 복원됩니다.
• 프레임별 비파괴 변환: 드래그 = 이동, 휠 = 크기 조절, 상단 핸들 = 회전, 왼쪽 하단 = 기울이기(shear), 좌우 반전 토글. 편집 내용은 curation.json 사이드카 파일에 저장됩니다 — 원본 PNG는 절대 덮어쓰지 않으며, 합성 단계에서 결정론적으로 결과를 만듭니다. 미리보기와 합성은 동일한 아핀 행렬을 공유하므로, 정렬한 대로 결과가 나옵니다.
• 실시간 미리보기는 상태의 fps로 시퀀스를 애니메이션하며, 재생/일시정지, 프레임별 이동, 0.25배~4배 속도 제어 기능을 제공합니다.
• 스프라이트 전용이 아닙니다: unpackatlasrun.py --pngs-dir을 사용하여 이미지 후보(아이콘, 로고, 생성된 초안)가 있는 모든 폴더를 가리키고, 일반적인 승자 선택 뷰로 사용할 수 있습니다.

등각 투영(isometric) 바닥 그리드

등각 투영 세트의 경우, 웹뷰는 바닥 그리드(meta.json의 타일/앵커에서 가져옴)를 오버레이하여 기울이기 핸들로 가구를 다이아몬드 축에 맞출 수 있게 합니다.

언어

웹뷰는 영어와 한국어를 지원합니다. 실행 시 --lang en|ko를 전달하거나, 앱 내 토글을 사용하세요:

python3 scripts/serve_curation.py --run-dir <run-dir> --lang en   # or ko

Python 지원

sprite-gen은 CPython 3.10+를 지원합니다. CI는 최소 지원 버전(3.10)과 최신 지원 버전(3.14)을 GitHub 호스트 러너에서 테스트합니다.

퀵스타트는 venv/ensurepip가 작동하는 Python 설치가 필요합니다. 로컬 배포에서 패키지 설치 전에 python3 -m venv가 실패하면, 지원되는 모든 버전의 표준 CPython 빌드를 사용하고 동일한 명령을 다시 실행하세요.

퀵스타트

# 0. 새 virtualenv에 의존성(Pillow) 설치
python3 -m venv.venv && source.venv/bin/activate
pip install -e.

# 1. 기본 이미지로 실행 준비
python3 scripts/prepare_sprite_run.py --out-dir <run-dir> --character-id <id> --base-image base.png

# 2. 이미지 생성으로 상태별 행 이미지를 생성하고 raw/<state>.png로 저장
# 3. 프레임 추출
python3 scripts/extract_sprite_row_frames.py --run-dir <run-dir>

# 4. (선택 사항) 웹뷰에서 프레임 큐레이션
python3 scripts/serve_curation.py --run-dir <run-dir>

# 5. 런타임 아틀라스 합성
python3 scripts/compose_sprite_atlas.py --run-dir <run-dir>

완성된 시트 편집

결합된 시트만 남아 있을 때, 큐레이터가 사용할 수 있는 실행 디렉토리를 재구축한 다음 큐레이션 및 내보내기를 수행합니다:

# 프레임 재구축: 명시적 --grid, --manifest 사각형, 또는 알파 자동 감지(기본값)
python3 scripts/unpack_atlas_run.py --atlas sheet.png            # 자동 감지
python3 scripts/unpack_atlas_run.py --manifest manifest.json     # 정확한 사각형
python3 scripts/unpack_atlas_run.py --pngs-dir furniture/        # 느슨한 PNG 세트 가져오기

# 큐레이션 후, 수정 사항을 명명된 PNG로 내보내기
python3 scripts/export_curated_pngs.py --run-dir <run-dir>

출력은 기본적으로 입력 옆에 찾을 수 있는 -curator 폴더에 저장됩니다.

전체 에이전트 중심 워크플로우와 계약은 SKILL.md에 있습니다.

설치

Codex 스킬 설치 프로그램 워크플로우에서, 이 저장소를 루트 스킬로 설치하세요:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo aldegad/sprite-gen --path.

기여 (Attribution)

컴포넌트-행 워크플로우는 Apache-2.0 라이선스의 hatch-pet 스킬에서 영감을 받았지만, 일반 게임 스프라이트 아틀라스를 대상으로 하며 펫 패키지나 펫 시각 에셋을 포함하지 않습니다.