Video2dsprite (Grok Build 전용)은(는) 무엇을 하나요?
기본 2D 캐릭터 이미지를 밀도 높은 애니메이션 스프라이트로 변환합니다. Grok Build의 네이티브 영상 도구를 사용합니다.
앱-빌더 / Grok 환경
| 항목 | 값 |
|---|---|
| Skill 디렉터리 | .grok/skills/video2dsprite/ |
| 스크립트 | python3 .grok/skills/video2dsprite/scripts/video2dsprite.py … |
| 영상 도구 | imagine_image_to_video — 하나의 베이스 file_path로 애니메이션 (존재 여부 확인) |
| 검사 | read_file로 스틸/프레임 확인; 비디오 경로 보고 |
| 의존성 | ffmpeg + Pillow + numpy (앱-빌더 이미지에 사전 설치됨) |
| 출력 홈 | /workspace 아래 assets/sprites/video2dsprite/<name>/ |
| 기본 | 프로덕션 히어로용으로는 generate2dsprite 선호; 이 경로는 더 밀도 높은 모션용 |
base still → imagine_image_to_video (제자리 모션) → 프레임 추출 → 크로마 키 → 샘플/정규화 → 스트립 / 그리드 / GIF
플랫폼 게이트 (먼저 읽기)
| 런타임 | 지원? |
|---|---|
| Grok Build (xAI) | 예 — 이미지 생성기 + 이미지→비디오 도구 필요 |
| Codex / Claude / 기타 에이전트 | 아니오 — Grok 비디오 도구가 없음. 이 스킬은 Grok 전용임을 알리고 $generate2dsprite 제안 |
정확한 도구 이름이 아닌 기능을 기준으로 판단하세요. 이미지 생성은 imagine_text_to_image / imagine_image_to_image로 나타나고, 비디오는 imagine_image_to_video 또는 (레거시) generate_video로 나타납니다. 툴 목록에 있는 쌍을 사용하세요. 이미지→비디오 도구가 전혀 없는 경우에만 중단하고 설명하세요. 코드로 그린 프레임으로 모션을 가짜로 만들지 마세요.
이 스킬은 선택적인 밀도 높은 모션 경로입니다. $generate2dsprite를 대체하지 않습니다:
$generate2dsprite를 사용할 때… | $video2dsprite를 사용할 때… |
|---|---|
| 깔끔한 픽셀 시트, 고정 그리드, 정체성이 중요한 히어로 | 사용자가 더 촘촘한 중간 포즈 / 부드러운 루프를 원할 때 |
| 공격/시전 바디 시트, 소품 팩, 엔진 아틀라스 | 비디오 소스로 달리기/걷기/대기 동작을 실험할 때 |
| 대부분의 게임 스프라이트를 위한 프로덕션 기본값 | 사용자가 명시적으로 비디오 → 프레임 → 스프라이트를 요청할 때 |
비디오는 픽셀을 부드럽게 만들고, 정체성을 흐리게 하며, 크로마 프린지를 남깁니다. 항상 QC를 수행하고, 프로덕션 히어로의 경우 사용자가 비디오 스타일을 원하지 않는 한 $generate2dsprite를 선호하세요.
매개변수
사용자 요청에서 유추:
subject: 캐릭터/크리처 설명, 또는 기존 스틸 경로action:run|walk|idle|attack| 사용자 정의 동작 구문view: 보통side(횡스크롤).topdown은 더 어려움 — 경고하고 카메라 잠금 유지duration:6(기본값) 또는10초frame_counts: 내보낼 밀도 집합, 기본8,16,24,48cell_size: 출력 스프라이트 셀, 기본128anchor:feet(측면 이동 기본값) |centerbg: 단색#FF00FF(크로마 필수)name: 출력 슬러그out_dir: 작업 폴더 (기본./sprites/video2dsprite/<name>/또는 프로젝트 상대 경로)
에이전트 규칙
- Grok 전용. 비-Grok 런타임에서는 짧은 설명과
$generate2dsprite대안을 제시하며 거절하세요. - 스틸 → 비디오, 텍스트→비디오만 단독으로 사용하지 마세요. 1단계 프레임을
imagine_text_to_image로 깨끗한 스틸로 만드세요 (프롬프트 또는 참조file_path에서). 그런 다음 해당 스틸의file_path로imagine_image_to_video를 호출하세요. - 제자리 모션. 달리기/걷기를 제자리에서 고정된 방향으로 하도록 프롬프트. 카메라 팬, 배경 스크롤, 장면 변경 없음. 피사체는 대략 중앙에 유지.
- 단색 마젠타 배경을 베이스에 적용하고 비디오 프롬프트에서 유지 (
#FF00FF/ 순수 마젠타). 플러드-필 크로마에 필요. - PIL/Canvas로 아트를 생성하지 마세요. 기본 아트는
imagine_text_to_image또는 사용자/로컬 스틸에서 비롯됩니다. 스크립트는 후처리만 수행. - 실험적 출력물을 게임에 통합하지 마세요. 사용자가 요청하지 않는 한.
- 게임 사용에는 하나의 이동 사이클을 선호. 전체 6초 멀티-사이클 클립에서 밀도 샘플링은 미리보기에 적합하며, 엔진 시트의 경우 시각적 QC 후 하나의 단일 사이클(12-16프레임)을 다시 샘플링할 수 있음.
- 작업 완료 시 비디오, 정리된 프레임, 스트립, 미리보기 GIF의 절대 경로를 보고하세요.
워크플로우
1. 계획
가장 작은 유용한 실행 선택:
- 측면 뷰 달리기/걷기 루프 → 이 스킬
- 다중 액션 히어로 키트 → 여전히 액션별로
$generate2dsprite사용; 요청된 경우에만 비디오를 이동에 사용 - FX/발사체/소품 팩 →
$generate2dsprite, 비디오 사용하지 않음
생성:
<out_dir>/
base/
video/
frames-raw/
frames-clean/
sprite/ # 기본 8-프레임 집합 + 더 밀도 높은 x16/x24/x48
prompt-used.txt
pipeline-meta.json
README.txt
2. 기본 스틸 만들기
옵션:
- A. 기존 스프라이트: 이미지 읽기, 필요한 경우 단색
#FF00FF위에 합성, 그런 다음 그 샌드박스 경로를imagine_image_to_image/imagine_image_to_video에 전달 - B. 새 캐릭터:
imagine_text_to_image로 단색 마젠타 배경, 전신, 측면 뷰, 중앙 정렬 - C. 참조 일치:
imagine_image_to_image에 참조file_path를 전달, 마젠타 위로 이동시키고 정체성 유지
기본 요구사항:
- 전신 보임, 충분한 마젠타 여백
- 달리기/걷기를 위한 측면 뷰 (프로필 또는 3/4 측면), 발이 아래쪽 1/3 근처
- 참조가 있을 때 프로젝트의 나머지 부분과 동일한 아트 스타일
- 텍스트, UI, 워터마크, 또는 두 번째 캐릭터 없음
반환된 file_path를 복사하여 <out_dir>/base/<name>-base.png로 저장; 비디오 호출을 위해 기본 file_path를 유지하세요.
정확한 이미지 프롬프트를 prompt-used.txt에 기록하세요.
3. imagine_image_to_video로 애니메이션
Grok imagine_image_to_video 호출:
- source path:
<base still file_path>(T2I / I2I에서 반환된 샌드박스 경로) duration:6(기본값) 또는10resolution_name:480p(사용자가720p를 요청하지 않는 한)prompt: 하나의 짧은 현재 시제 샷 (references/prompt-rules.md 참조)
프롬프트의 필수 모션 제약 조건:
- 피사체 제자리에서 달리기/걷기 (트레드밀 스타일)
- 카메라 고정 — 팬, 줌, 또는 궤도 이동 없음
- 배경은 평평한 단색 마젠타 유지
- 정체성, 의상, 팔레트가 전체 샷에서 안정적
- 단일 연속 동작만
반환된 비디오 file_path를 <out_dir>/video/<name>-<duration>s.mp4로 복사하세요.
비디오 도구를 사용할 수 없으면 중단 (플랫폼 게이트).
4. 추출 + 크로마 + 샘플링 (로컬 스크립트)
프로세서 실행 (ffmpeg + Pillow + numpy):
python3 .grok/skills/video2dsprite/scripts/video2dsprite.py process \
--video <out_dir>/video/<name>-6s.mp4 \
--out-dir <out_dir> \
--name <name> \
--frame-counts 8,16,24,48 \
--cell-size 128 \
--body-height 100 \
--foot-y 118 \
--fps 0
참고:
--fps 0= 디코딩된 모든 프레임 추출 (소스 fps 사용)- 모서리에서 마젠타 플러드-필 + 디스필
--frame-counts의 각 카운트에 대해 균일 샘플링- 발 정규화 셀, 가로 스트립, 그리드, 카운트별 루프 GIF
선택사항: 기존 정리된 프레임에서 더 밀도 높은 집합만 다시 샘플링:
python3 .grok/skills/video2dsprite/scripts/video2dsprite.py sample \
--clean-dir <out_dir>/frames-clean \
--out-dir <out_dir> \
--frame-counts 16,24,48 \
--cell-size 128
5. QC
시각적으로 확인:
- 미리보기 GIF가 큰 폭등 없이 루프됨
- 마젠타 제거됨 (단색 분홍 블록 없음); 프린지는 허용 또는 재키잉
- 발이 안정적인 기준선에 유지됨 (잘못된 크롭으로 인한 점프 없음)
- 정체성이 대략 안정적 (얼굴/옷이 매 프레임 변형되지 않음)
- 동작이 제자리에서 이루어짐 (프레임 밖으로 미끄러지지 않음)
- 게임용: 하나의 카운트 선택 (주로 16 또는 24) 또는 하나의 실제 사이클 잘라내기
정체성이 심하게 변하거나 픽셀이 너무 부드러우면 프로덕션 시트에는 $generate2dsprite로 대체하고 비디오 집합은 모션 참조용으로만 유지하세요.
6. 전달
경로만 보고 (사용자가 게임에 연결하도록 요청하지 않은 한):
- 비디오:
video/*.mp4 - 밀도 높은 스프라이트:
sprite/x16|x24|x48/ - 스트립 / 그리드 / GIF:
sprite/run-strip-N.png,run-grid-N.png,run-preview-N.gif - 메타:
pipeline-meta.json
요청되지 않은 한 게임 코드를 수정하지 마세요.
기본값
- 지속 시간: 6s
- 동작: 측면 제자리 달리기, 오른쪽을 향함
- 내보내기 카운트: 8, 16, 24, 48
- 셀: 128², 신체 높이 ~100, 발 y≈118
- 배경: #FF00FF
- 다중 참조보다 단일 에셋
imagine_image_to_video선호 (필요한 경우 먼저imagine_text_to_image로 다중 참조 구성)
트레이드오프 (사용자에게 한 번 알림)
장점: 더 촘촘한 중간 프레임 → 4~8개의 개별 생성 포즈보다 부드러운 느낌.
단점: 더 부드러운 픽셀, 정체성 변동, 크로마 프린지, 멀티-사이클 6초 클립은 완벽한 단일 루프가 아님, 더 무거운 에셋.
경험 법칙: 8→16→24는 보통 부드러움을 향상; 48은 종종 수확 체감; 145개의 원시 프레임은 샘플링용이며, 런타임 모두 사용하기 위한 것이 아님.
리소스
- references/prompt-rules.md — 베이스 스틸 + 비디오 프롬프트
- references/pipeline.md — 폴더 레이아웃, ffmpeg, 샘플링 전략
- scripts/video2dsprite.py — 추출, 크로마, 정규화, 내보내기
다른 스킬과의 관계
$generate2dsprite— 기본 시트 파이프라인 (Codex + Grok, 이미지 생성이 있을 때)$generate2dmap— 맵; 여기서 사용하지 않음$video2dsprite— Grok Build 전용 모션 밀도화 경로$game-asset-core/$game-animation-frames— 루프/플립-테스트/모션 법칙 및 엔진-레디 기본값; 샌드박스 실행을 위해 여전히 이 스킬의 스크립트 사용 (마젠타 베이스 + 크로마), 자유형 배경색이 아님