video2dsprite

Video2dsprite (Grok Build 전용)

베이스 2D 캐릭터 이미지를 Grok Build의 네이티브 비디오 도구를 사용해 밀집 애니메이션 스프라이트로 변환합니다.

앱 빌더 / Grok 환경

항목	값
스킬 디렉토리	.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 선호; 이 스킬은 더 조밀한 모션 경로

베이스 스틸 → imagine_image_to_video (제자리 모션) → 프레임 추출 → 크로마키 → 샘플/정규화 → 스트립 / 그리드 / GIF

플랫폼 게이트 (먼저 읽기)

런타임	지원 여부
Grok Build (xAI)	예 — 이미지 생성기 + 이미지→비디오 도구 필요
Codex / Claude / 기타 에이전트	아니요 — Grok 비디오 도구가 없음. 사용자에게 이 스킬은 Grok Build 전용이라고 알리고 $generate2dsprite를 대신 제안

정확한 도구 이름이 아닌 기능을 기준으로 게이트합니다. 이미지 생성은 imagine_text_to_image / imagine_image_to_image로, 비디오는 imagine_image_to_video 또는 (레거시) generate_video로 나타납니다. 도구 목록에 있는 쌍을 사용하세요. 이미지→비디오 도구가 전혀 없을 때만 멈추고 설명하세요. 코드로 프레임을 그려 모션을 위조하지 마세요.

이 스킬은 선택적인 더 조밀한 모션 경로입니다. $generate2dsprite를 대체하지 않습니다:

$generate2dsprite 사용 조건…	$video2dsprite 사용 조건…
깔끔한 픽셀 시트, 고정 그리드, 정체성이 중요한 히어로	사용자가 더 조밀한 중간 자세/부드러운 루프를 원할 때
공격/캐스트 바디 시트, 소품 팩, 엔진 아틀라스	비디오 기반 달리기/걷기/대기 모션 실험
대부분의 게임 스프라이트 프로덕션 기본값	사용자가 명시적으로 비디오 → 프레임 → 스프라이트 요청

비디오는 픽셀을 부드럽게 만들고, 정체성을 흐리게 하며, 크로마 프린지를 남깁니다. 항상 품질 관리를 수행하세요. 프로덕션 히어로는 사용자가 비디오 스타일을 원하지 않는 한 $generate2dsprite를 선호하세요.

파라미터

사용자 요청에서 추론:

• subject: 캐릭터/크리처 설명 또는 기존 스틸 경로
• action: run | walk | idle | attack | 사용자 정의 모션 구문
• view: 보통 side (사이드 스크롤러). topdown은 더 어렵습니다 — 경고하고 카메라 고정 유지
• duration: 6 (기본값) 또는 10초
• frame_counts: 내보낼 더 조밀한 세트, 기본값 8,16,24,48
• cell_size: 출력 스프라이트 셀, 기본값 128
• anchor: feet (사이드 이동 기본값) | center
• bg: 단색 #FF00FF (크로마 필수)
• name: 출력 슬러그
• out_dir: 작업 폴더 (기본값 ./sprites/video2dsprite/<name>/ 또는 프로젝트 상대 경로)

에이전트 규칙

1. Grok 전용. Grok 런타임이 아니면 짧은 설명 + $generate2dsprite 대안과 함께 거절하세요.
2. 스틸→비디오, 텍스트→비디오만 단독으로 사용하지 않음. 프레임 1을 imagine_text_to_image로 깨끗한 스틸로 스테이징하세요 (프롬프트 또는 참조 file_path에서). 그런 다음 해당 스틸의 file_path로 imagine_image_to_video를 호출하세요.
3. 제자리 모션. 달리기/걷기를 고정 방향을 향해 제자리에서 하도록 프롬프트하세요. 카메라 팬, 배경 스크롤, 장면 변경 없음. 피사체는 대략 중앙에 유지됩니다.
4. 단색 마젠타 배경을 베이스에 사용하고 비디오 프롬프트에 유지하세요 (#FF00FF / 순수 마젠타). 플러드 필 크로마에 필요합니다.
5. PIL/Canvas로 아트를 만들지 마세요. 베이스 아트는 imagine_text_to_image 또는 사용자/로컬 스틸에서 가져옵니다. 스크립트는 후처리만 합니다.
6. 실험적 출력을 게임에 넣지 마세요 사용자가 통합을 요청하지 않는 한.
7. 게임 사용에는 하나의 로코모션 사이클을 선호하세요. 미리보기의 경우 전체 6초 멀티사이클 클립에서 조밀하게 샘플링해도 괜찮습니다. 엔진 시트의 경우 시각적 QC 후에 단일 사이클(12–16프레임)을 다시 샘플링할 수 있습니다.
8. 완료 시 비디오, 정리된 프레임, 스트립, 미리보기 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. 참조 일치: 참조 file_path로 imagine_image_to_image하여 마젠타 위에 배치하고 정체성 유지

베이스 요구사항:

• 전신 가시적, 충분한 마젠타 여백
• 달리기/걷기용 사이드 뷰 (프로필 또는 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 호출:

• 소스 경로: <베이스 스틸 file_path> (T2I/I2I가 반환한 샌드박스 경로)
• duration: 6 (기본값) 또는 10
• resolution_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. 품질 관리

시각적 확인:

• 미리보기 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

요청되지 않으면 게임 코드를 수정하지 마세요.

기본값

• 지속 시간: 6초
• 동작: 제자리 사이드 달리기, 오른쪽 facing
• 내보내기 개수: 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 — 루프/플립 테스트/모션 법칙 및 엔진 준비 기본값; 샌드박스 실행에는 여전히 이 스킬의 스크립트 사용 (마젠타 베이스 + 크로마), 자유 형식 배경색 사용 안 함