BlockReel は何をしますか？
あなたは短いブロックアニメーションをコードとして演出・構築し、フレームごとにMP4にレンダリングします。 動画モデルは使用しません。すべてのフレームはJSONストーリーボードによって駆動されるThree.jsシーンから生成されます。
流れはA→Eです。ブリーフとショットリスト（A～C）を作成する前に、ストーリーボード（D）に飛ばないでください。 品質は準備と自身のフレーム確認（E）によって生まれます。JSONの量ではありません。
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 # オリジナルゲームテクスチャ + mob/chest/steve/alexテクスチャ -> work/vanilla/ (ローカルキャッシュ、約45KB)
python tools/vanilla.py sounds # オリジナルゲーム効果音 -> work/vanilla/sounds/ (ローカルキャッシュ、約1MB、音楽なし)
デフォルトでゲームのように見えます。 ユーザーが自身のテクスチャを指定しない限り、フィルムはキャッシュからのオリジナルテクスチャを使用します（エンジンが自動的に読み込みます。"textures": "builtin" とするとCC0のオリジナルに切り替わります）。Mob: /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 | エンジンが現時点でアニメーション可能なもの、不可能なもの: シーンを約束する前に確認すること |
ジャンル（スタイルと同様に、最初に1つ選ぶ）
オープニングの場合: python tools/opening.py "<CHANNEL>" --out films/<name> から開始（名前がブロックで表示、ブラスト、オービット、ロゴホールド、ゲームサウンド、オリジナル楽曲）。その後、生成された story.json（ブロック、スキン、タイミング、追加ショット）を調整します。
docs/GENRES.md を読んでください: opening（YouTubeチャンネルイントロ、5～12秒）、cinematic short（壮大またはドラマチックな20～60秒の映像、例: examples/ および「Farol Negro」制作）、series episode（会話するキャラクター、コメディまたはアドベンチャー、1～5分、大規模Minecraftアニメーションチャンネルの形式）。各ジャンルはペース、カメラ文法、サウンド、提供物を固定します。前提はユーザーが望む任意のものにできます。
A. ブリーフィング（最大1つの短い質問をする）
リクエストから以下を抽出: 前提（1文）、トーン（コメディ、ホラー、壮大、心温まる…）、長さ（デフォルト30～60秒）、キャラクター（どのスキンか）、設定、スタイル（DIRECTOR.md §8 参照）。不足しているものがあり、適切なデフォルトが存在する場合はそれを選択し、どのデフォルトを選択したかを伝えてください。回答がフィルム全体を変える場合にのみ質問してください（例: 「これらのキャラクターのスキンはありますか？」）。結果を films/<name>/brief.md に保存します（テンプレートは docs/PREPRODUCTION.md）。
B. リサーチ（Web、リンク付きで記録）
WebSearch / WebFetch を使用。すべてを films/<name>/research.md に書き、各主張にはリンクを付けます:
- トーンに合わせたアニメーション言語: ペース、カメラ、コメディのタイミング/ホラーの恐怖/壮大なスケール。
- 剛体キャラクターアニメーション: 予備動作、オーバーシュート、フォロースルー、代用のつぶれ、インパクトフレーム。
- 設定の参考: 選択した設定に対応するブロック建築、カラーパレット、ランドマーク。
- フリー音源/効果音源: ソース、トラック名、そのライセンス をリストアップ。ユーザーの許可なく音声をダウンロードまたは追加しないでください。ユーザーが
story.jsonに含めるファイルを提供します。
次に「適用する原則」セクションを追加: 5～10の箇条書きを自分の言葉で、それぞれをこのフィルムのショットまたはルールに関連付けてください。決して他作品のシーン、キャラクター、台詞をコピーせず、原則を抽出してください。参考動画のローカルコピーは work/（gitignore対象）にのみ保存。リポジトリにはあなたの書いた結論のみを置きます。
C. 脚本とショットリスト
DIRECTOR.md §7 のテーブルを使用して films/<name>/shotlist.md を記述（意図 列を追加: ショットが視聴者に何を感じさせ、または知らせるか）。ブリーフィングと照合: 1つのアイデア、明確なビート（設定→盛り上げ→転換→解決）、エネルギー曲線（静→騒→静）、トーンに応じたショット長、すべての台詞は短く。
D. 構築
- アセット。
- ユーザーがスキンを送ってきた場合→そのスキンを そのまま変更せずにフィルムで使用（フィルムフォルダにコピーし、
story.jsonで参照）。最初にpython core/skin.py validate skin.pngを実行。レガシー64x32の場合はconvertして新しいファイルに。あなたが作成するスキンはvalidateに合格する必要があります（64x64 RGBA PNG、ベースレイヤーが完全に不透明、slim/classicを自動検出）。これにより実際のゲーム（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フォルダ）。 - Mob:
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/からのオリジナルゲーム効果音（爆発、ドア、チェスト、Mob、ヒット、足音、雨、雷、火）、効果音がない場合のみ自作音（ウィッシュ、ライザー: ゲームの音楽には他の権利者がいます）、エネルギー曲線に従ったオリジナル楽曲（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（オフラインのみ:python tools/voice.py fetchで取得したPiperニューラル音声、例:--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で欠落とマークされたもの（保持ツール、階段とフェンス、さらに多くのMob、スニーク/スイム/ライドクリップ…）が必要な場合は、事前にそれを伝え、存在する最も近いものを提案してください。サポートされていないJSONフィールドで偽装しないでください（それらは黙って無視されます）。 - クローズアップでは比率を確認してください。ワイドショットだけでなく（肩が胴体に接している、頭が直接体の上にある、顔が読める）。
- ユーザーのスキン/テクスチャはそのままにし、派生ファイルは新しい名前で隣に書き出します。
films/とwork/の下はすべてgitignoreされています。リポジトリに同梱されるサンプルはexamples/にあります。