blockreel은(는) 무엇을 하나요?
블록 애니메이션 단편을 코드로 연출하고 제작한 후, 프레임별로 MP4로 렌더링합니다. 비디오 모델은 사용되지 않습니다. 모든 프레임은 Three.js 장면을 JSON 스토리보드로 구동하여 생성됩니다.
흐름은 A → E입니다. 브리핑과 샷 리스트(A–C)를 먼저 작성하기 전에 스토리보드(D)로 건너뛰지 마십시오. 품질은 더 많은 JSON이 아니라, 준비 과정과 자신의 프레임(E)을 직접 확인하는 데서 비롯됩니다.
0. 부트스트랩 (첫 사용)
export BLOCKREEL_HOME="${BLOCKREEL_HOME:-$HOME/blockreel}"
[ -d "$BLOCKREEL_HOME" ] || git clone https://github.com/ViniciusNoetzold/mine-blockreel-skill- "$BLOCKREEL_HOME"
cd "$BLOCKREEL_HOME" && npm install && pip install -r requirements.txt
python tools/vanilla.py fetch # 원본 게임 텍스처 + 몹/상자/스티브/알렉스 텍스처 -> work/vanilla/ (로컬 캐시, 약 45KB)
python tools/vanilla.py sounds # 원본 게임 사운드 효과 -> work/vanilla/sounds/ (로컬 캐시, 약 1MB, 음악 없음)
기본적으로 게임처럼 보입니다. 사용자가 자신의 텍스처를 요청하지 않는 한, 영화는 캐시의 원본 텍스처를 사용합니다.
(엔진이 자동으로 선택하며, "textures": "builtin"을 설정하면 CC0 원본으로 대체됩니다.) 몹: /work/vanilla/entity/zombie.png,
creeper.png, pig.png, spider.png; 기본 스킨 steve.png / alex.png. 이 파일들은 Mojang의 자산이며, 사용자
기기의 work/ 폴더에 남아 있으며 절대 커밋되거나 배포되지 않습니다(docs/LEGAL.md 참조).
Node 20+, Python 3.11+, ffmpeg 및 Chrome/Chromium이 필요합니다(CHROME_PATH 설정 또는
python -m playwright install chromium 실행). $BLOCKREEL_HOME/films/<name>/ 또는 사용자가 시작한
폴더에서 작업하며, core/ 내부에는 절대 쓰지 마십시오.
1. 가이드 (해당 단계에 도달하면 읽기)
| 파일 | 읽어야 할 때 |
|---|---|
docs/PREPRODUCTION.md | A–C 단계: 브리핑, 연구 규칙, brief.md / research.md / shotlist.md 템플릿 |
DIRECTOR.md | 스토리, 리듬, 카메라, 연기, 액션 시퀀스 |
TECHNIQUE.md | 파이프라인, 단위, 성능, 엔진 확장 |
docs/STORYBOARD.md | 정확한 story.json 스키마 (필드의 유일한 진실 공급원) |
docs/QA.md | E 단계: 체크리스트 및 tools/qa.py |
styles/<style>/STYLE.md | 선택한 스타일의 비주얼 |
docs/SKINS.md, docs/BLOCK-ATLAS.md, docs/RESOURCE-PACKS.md, docs/MOBS.md | 에셋 작업 |
docs/COVERAGE.md | 엔진이 현재 애니메이션할 수 있는 것과 없는 것: 장면을 약속하기 전에 확인 |
장르 (스타일처럼 먼저 하나 선택)
오프닝의 경우, python tools/opening.py "<채널명>" --out films/<name>(이름 블록, 블래스트, 오빗, 로고 홀드,
게임 사운드 및 오리지널 스코어)로 시작한 후 생성된 story.json(블록, 스킨, 타이밍, 추가 샷)을 조정합니다.
docs/GENRES.md를 읽으십시오: 오프닝(YouTube 채널 인트로, 5-12초), 시네마틱 단편(서사적 또는 극적인 20-60초 영화,
예: examples/ 및 "Farol Negro" 제작), 시리즈 에피소드(말하는 캐릭터, 코미디 또는 모험, 1-5분, 대규모
마인크래프트 애니메이션 채널의 형식). 각 장르는 페이싱, 카메라 문법, 사운드 및 전달할 내용을 고정합니다. 프레미스는
사용자가 원하는 모든 것에 관한 것일 수 있습니다.
A. 브리핑 (최대 한 개의 짧은 질문)
요청에서 추출: 프레미스(한 문장), 톤(코미디, 공포, 서사, 힐링…),
길이(기본값 30–60초), 캐릭터(어떤 스킨), 배경, 스타일(DIRECTOR.md §8 참조).
누락된 항목이 있고 합리적인 기본값이 존재하는 경우, 기본값을 선택하고 어떤 기본값을 선택했는지 말하십시오.
답변이 영화 전체를 바꾸는 경우에만 질문하십시오(예: "이 캐릭터들의 스킨이 있습니까?").
결과를 films/<name>/brief.md(docs/PREPRODUCTION.md의 템플릿)에 저장합니다.
B. 연구 (웹, 링크와 함께 기록)
WebSearch / WebFetch를 사용합니다. 모든 내용을 films/<name>/research.md에 기록하고, 모든 주장에 링크를 첨부합니다.
- 톤에 맞는 애니메이션 언어: 페이싱, 카메라, 코미디 타이밍 / 공포의 불안감 / 서사적 스케일.
- 강체 캐릭터 애니메이션: 예비 동작, 오버슈트, 후속 동작, 스쿼시 대체, 임팩트 프레임.
- 배경 참조: 선택한 배경에 대한 블록 건축, 색상 팔레트, 랜드마크.
- 무료 사용 가능한 음악 및 사운드 효과 소스: 소스, 트랙 이름 및 라이선스를 나열합니다. 사용자의 허락 없이
오디오를 다운로드하거나 추가하지 마십시오. 사용자는
story.json에 들어갈 파일을 제공합니다.
그런 다음 "적용할 원칙" 섹션을 추가합니다: 자신의 말로 된 5–10개의 글머리 기호, 각각 이 영화의 샷 또는 규칙과 연결됩니다.
다른 작품의 장면, 캐릭터 또는 대사를 복사하지 말고 원칙을 추출하십시오. 참조 비디오의 로컬 복사본은
work/(gitignore됨)에만 보관하십시오. 작성된 결론만 리포지토리에 남깁니다.
C. 대본 및 샷 리스트
DIRECTOR.md §7의 표를 사용하여 films/<name>/shotlist.md를 작성합니다(의도 열 추가: 샷이 시청자에게 무엇을
느끼게 하거나 알게 하는지). 브리핑과 대조 확인: 하나의 아이디어, 명확한 비트(설정 → 고조 → 전환 → 해소),
에너지 형태(조용함 → 시끄러움 → 조용함), 톤에 따른 샷 길이, 모든 대사는 짧게.
D. 제작
- 에셋.
- 사용자가 스킨을 보내면 → 해당 스킨을 변경 없이 영화에 사용합니다(영화 폴더에 복사하고
story.json에서 참조). 먼저python core/skin.py validate skin.png를 실행합니다. 레거시 64x32인 경우convert하여 새 파일로 만듭니다. 직접 만든 스킨은validate(64x64 RGBA PNG, 베이스 레이어 완전 불투명, 슬림/클래식 감지)를 통과해야 실제 게임(Java 스킨 페이지/런처)에도 업로드할 수 있습니다. - 스크린샷 / 크기 조정된 이미지로 제공된 스킨 →
python core/skin.py snap in.png out.png --crop x0,y0,x1,y1을 실행한 다음validate를 실행합니다. 행이 누락된 경우, 말하고 전체 이미지를 요청합니다. - 캐릭터의 렌더링된 3D 그림으로 제공된 스킨 → 텍스처로 안정적으로 변환할 수 없습니다. 그렇게 말합니다.
- 만들거나 개선해야 할 스킨 →
blockreel-skins스킬(/blockreel:blockreel-skins) 실행: 연구, 팔레트 계획, 레이어드 페인팅,python tools/turntable.py skin.png --out tt.png및 최소 2회 검토. 블록/아이템 텍스처 또는 리소스 팩 →blockreel-textures(core/tilecheck.py,tools/pack_preview.py,core/pack.py) 실행. 결과를 영화 내에서 사용합니다(story.json스킨 경로 /blocks폴더). - 몹:
docs/MOBS.md(사용자의 텍스처 필요; 크리퍼-, 돼지-, 거미 모양 리그 및 플레이어 리그를 통한 좀비). - 스킨 없음 →
python core/skin.py make ...또는core/builtin/skins/의 원본. - 블록/아이템 시트 →
python core/atlas.py slice|label|faces실행(docs/BLOCK-ATLAS.md참조). 식별할 수 있는 것만 레이블 지정.
- 사용자가 스킨을 보내면 → 해당 스킨을 변경 없이 영화에 사용합니다(영화 폴더에 복사하고
- 스토리보드. 레터박스 바와 비네트(어두운 모서리)는 스타일(
letterbox,vignette)에서 비롯됩니다. 2.37:1 전달의 경우 마지막에 바를 잘라냅니다(ffmpeg -vf crop=iw:iw/2.37). 플레이어에서 검은 막대가 표시되지 않도록 하고, 사용자가 원하지 않으면 비네트를 끕니다(styleOverride.vignette: false). 샷 리스트에서story.json을 작성합니다(docs/STORYBOARD.md). 가장 가까운examples/*/story.json에서 시작합니다. 카메라 오프셋은 월드 공간입니다: 보고 싶은 얼굴 앞에 카메라를 배치합니다. - 테스트 스틸.
python tools/render.py story.json --frame <t> --out check.png를 실행하고 이미지를 확인합니다 (먼저 프레이밍, 그 다음 조명, 마지막으로 연기). - 미리보기.
python tools/render.py story.json --out preview.mp4 --fps 12 --scale 0.5를 실행합니다. - 사운드 (선택 사항이 아님).
audio블록이 가리키는 모든 파일을 제작합니다:work/vanilla/sounds/의 원본 게임 효과 (폭발, 문, 상자, 몹, 타격, 발소리, 비, 천둥, 불), 게임에 없는 경우에만 직접 만든 사운드(휘익, 라이저: 게임의 음악은 다른 권리 보유자가 있음), 에너지 형태를 따르는 오리지널 스코어 (python tools/score.py --out music.wav --duration 30 --sections calm:0:7,build:7:15,battle:15:23,silence:23:26,dawn:26:30), 그리고 음성: 먼저 사용자의 녹음; 그렇지 않으면tools/voice.py(오프라인 전용: Piper 신경망 음성은python tools/voice.py fetch로 가져옴, 예:--voice piper:faber, 또는 Windows OneCore 음성daniel/maria(SSML 일시 중지 및 강조 포함)), 캐릭터 프리셋(hero,villain,monster,child,narrator,radio) 사용. 각 대사를 해당 샷 내에 맞춥니다: 길이를 측정한 다음,--rate또는 샷 길이를 조정합니다.docs/GENRES.md의films/스타일make_audio.py를 참조하십시오.python tools/audio.py story.json --out mix.wav를 실행하고, 듣고, 오디오와 함께 렌더링하거나(또는 믹스를 무음 렌더링에 먹스합니다). - 최종 렌더링.
python tools/render.py story.json --out film.mp4를 실행합니다. 소프트웨어 GL은 960x540에서 약 1초/프레임입니다: 긴 영화의 경우 얼마나 걸릴지 사용자에게 알리십시오.
E. 품질 검토 (전달 전 필수)
python tools/qa.py films/<name>/story.json --out films/<name>/qa
최소 8개의 분산된 프레임(오프닝, 모든 샷 변경, 클로즈업, 엔딩)을 렌더링하고, 연락처 시트를 만들고, 자동 검사를 실행합니다
(블록 내부의 카메라, 배우가 프레임 밖, 얼굴이 카메라에서 멀어짐, 자막 잘림, 샷이 톤에 대한 한계보다 김). 그런 다음 모든 프레임 이미지를 열고 보고 스크립트가 확인할 수 없는 것을 판단합니다:
스킨 구멍, 이상한 그림자, 어색한 포즈, 불분명한 스토리, 페이싱. 수정하고, 다시 렌더링하고, 깨끗해질 때까지 반복합니다.
결과를 films/<name>/qa.md(docs/QA.md의 템플릿)에 기록합니다: 확인한 것, 발견한 것, 수정한 것,
그리고 확인할 수 없었던 것. 그런 다음에만 film.mp4와 프로젝트 폴더를 전달합니다.
규칙
- 게임 에셋(텍스처, 사운드, 글꼴)을 리포지토리나 영화 폴더에 복사하지 마십시오. 단, 사용자가 제공하고 소유하는 경우는 예외입니다.
그렇지 않으면 원래 내장 에셋을 사용하십시오.
docs/LEGAL.md를 참조하십시오. - 실행하지 않은 기능이 작동한다고 주장하지 마십시오. 렌더링 또는 에셋 단계가 실패하면 무엇이 실패했는지 말하십시오.
- 엔진의 실제 기능(
docs/STORYBOARD.md에 나열됨)을 사용하십시오. 장면에docs/COVERAGE.md에서 누락된 것으로 표시된 것이 필요한 경우 (도구 들기, 계단 및 울타리, 더 많은 몹, sneak/swim/ride 클립...), 미리 말하고 가장 가까운 대안을 제시하십시오; 지원되지 않는 JSON 필드로 속이지 마십시오(자동으로 무시됨). - 와이드 샷뿐만 아니라 클로즈업에서 비율을 확인하십시오(어깨가 몸통과 일치, 머리가 몸체에 직접 연결, 얼굴 읽기 가능).
- 사용자 스킨/텍스처를 그대로 두십시오. 파생 파일은 새 이름으로 옆에 작성하십시오.
films/및work/아래의 모든 것은 gitignore됩니다. 리포지토리와 함께 제공되는 예제는examples/에 있습니다.