aldegad/sprite-gen

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

sprite‑gen이란?

sprite‑gen은 Python 기반의 명령줄 도구(그리고 Codex/Claude 스킬)로, 게임 캐릭터의 단일 정적 일러스트를 즉시 사용 가능한 스프라이트 시트로 변환합니다. 작동 방식은 다음과 같습니다:

이미지 모델(예: Grok Imagine, Codex, Claude)에 프롬프트를 보내 각 애니메이션 상태(대기, 걷기, 공격 등)에 대한 일련의 프레임을 생성합니다.
배경 크로마키를 제거하고 깨끗한 투명 PNG 프레임을 추출합니다.
프레임을 아틀라스(sprite‑sheet‑alpha.png)로 모으고, 각 프레임의 정확한 사각형, FPS, 루프 여부를 게임 엔진에 알려주는 기계 판독 가능한 매니페스트(manifest.json.frame_layout)를 함께 생성합니다.
선택 사항으로 비디오 클립에서 루프를 생성하고, 팔레트를 다시 색칠하고, 호흡 대기 루프를 추가하고, 여러 자산을 사용하여 간단한 장면을 구축할 수도 있습니다.

이 도구는 모든 프레임을 수동으로 그릴 시간이나 기술이 없는 인디 개발자나 취미 사용자를 대상으로 합니다.

주요 기능(README에서)

기능	설명	사용 방법
아틀라스 행 파이프라인 (A)	하나의 기본 이미지에서 투명 스프라이트 시트 + 매니페스트 생성. 자동 '호흡' 대기 루프 포함.	`prepare → gen-set → extract → compose-atlas` (CLI 명령)
비디오-루프 파이프라인 (B)	기본 이미지를 비디오 모델에 입력하여 각 모션 상태에 대한 원활한 투명 루프를 생성한 다음, 클립을 자연 주기로 잘라냅니다.	`video-set` (작업 생성) → `video-canvas → video → video-frames → video-loop`
큐레이션 웹뷰	최종 아틀라스를 굽기 전에 생성된 프레임을 비교, 거부 또는 미세 조정할 수 있는 대화형 UI.	`sprite-gen curation --run-dir <run>` (선택 사항)
유틸리티 (C)	단일 이미지 자르기, 다중 셀 시트 슬라이스, 기존 아틀라스를 개별 프레임으로 풀기.	`cutout`, `slice-sheet`, `unpack-atlas`
후처리 (D)	결정적 재색칠, 레이어 합성, Aseprite/Phaser/Flame 형식으로 내보내기.	`recolor`, `compose-layers`, `export-aseprite`
에셋 도구 (E)	타일 배경 만들기, 투영 그림자 생성, 모션 타이밍 및 접촉 지점 검사.	`background-tile`, `shadow`, `inspect-motion`
장면 생성 (S)	여러 스프라이트 아틀라스와 다른 PNG를 결합하여 카메라 및 조명 메타데이터가 포함된 장면(PNG, MP4, GIF)을 렌더링.	`scene-render`, `scene-inspect`
방향/핸드니스 처리	옆보기 스프라이트의 좌/우 방향을 감지하거나 강제. 잘못된 경우 미러링하거나 재생성.	`--facing`, `--facing-fix` 플래그 (`gen`/`video-set`)
다중 공급자 지원	Codex, Claude, Grok Imagine 및 서버 측 사용을 위한 명시적 `openai` 공급자와 함께 작동.	`--provider codex` 등
결정적 출력	동일한 입력 → 동일한 출력 바이트 (버전 관리에 중요).	`recolor-palette` + `recolor` 파이프라인

유용할 수 있는 대상

인디 게임 개발자: 픽셀 아트 캐릭터가 필요하지만 모든 애니메이션 프레임을 손으로 그릴 시간이나 기술이 없는 경우.
픽셀 아트 취미 사용자: AI 생성 모션 루프를 실험하면서 최종 자산을 완전히 제어하려는 경우.
도구 빌더: 파이프라인(예: 게임 자산용 CI)을 위한 프로그래밍 가능한 스프라이트 아틀라스 생성이 필요한 경우.

빠른 시작(README에서)

# 1. 깨끗한 venv를 만들고 패키지 설치
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. 단일 캐릭터 이미지에서 아틀라스 생성
sprite-gen prepare --out-dir run --character-id hero --base-image base.png
sprite-gen gen-set --run-dir run --provider codex   # 프레임 행 생성
sprite-gen extract --run-dir run                  # 투명 PNG 생성
sprite-gen compose-atlas --run-dir run            # sprite-sheet-alpha.png + manifest.json 생성

# 3. (선택 사항) 큐레이션 UI를 열어 프레임 조정
sprite-gen curation --run-dir run

비디오 기반 루프의 경우 RIFE를 한 번 설치(sprite-gen rife install)하고 video-set 워크플로를 실행합니다.

제한 사항 및 주의 사항(README에서)

생성된 프레임의 품질은 기본 이미지/비디오 모델에 따라 달라집니다. 도구는 프레임을 약간 조정하거나 미러링할 수 있을 뿐 완벽한 방향을 보장하지 않습니다.
방향 감지(--facing-fix)는 기본적으로 기록 전용이며 높은 신뢰도에서도 잘못될 수 있습니다.
일부 파이프라인(예: 비디오 루프)에는 외부 자격 증명(grok CLI 로그인 또는 XAI_API_KEY)이 필요합니다.
'walk/run' 사이클 루프는 모션 QA가 통과할 때까지 실험적입니다.
Python 3.11+가 필요합니다. 3.10은 더 이상 지원되지 않습니다.

라이선스

Apache‑2.0 – 상업적 및 비상업적 용도로 무료입니다.

위 정보는 모두 저장소의 README에서 직접 가져온 것이며 외부 가정을 추가하지 않았습니다.