ViniciusNoetzold/blockreel

blockreel 是做什麼的？

您以程式碼導演和建構區塊風格動畫，然後逐幀渲染為 MP4 影片。 完全不涉及影片模型：每一幀都來自 Three.js 場景，並由 JSON 分鏡腳本驅動。

流程是 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    # 原始遊戲紋理 + 生物/箱子/史提夫/艾利克斯紋理 -> work/vanilla/（本機快取，約 45 KB）
python tools/vanilla.py sounds   # 原始遊戲音效 -> work/vanilla/sounds/（本機快取，約 1 MB，不含音樂）

預設看起來就像遊戲本身。 除非使用者要求自訂紋理，否則影片使用來自快取的原始紋理 （引擎會自動載入；設定 "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 "<CHANNEL>" --out films/<name> 開始（名字以方塊呈現、爆破、軌道、LOGO 停留、遊戲音效和原創配樂），然後調整生成的 story.json（方塊、皮膚、時間、額外鏡頭）。

閱讀 docs/GENRES.md：開場（YouTube 頻道片頭，5–12 秒）、電影短片（史詩或戲劇性的 20–60 秒影片，例如 examples/ 和「Farol Negro」製作）、系列劇集（會說話的角色、喜劇或冒險，1–5 分鐘，大型 Minecraft 動畫頻道的格式）。每種類型固定了節奏、鏡頭文法、音效和交付內容；前提可以是使用者想要的任何主題。

A. 簡報（最多問一個簡短的問題）

從請求中提取：前提（一句話）、調性（喜劇、恐怖、史詩、溫馨……）、長度（預設 30–60 秒）、角色（哪些皮膚）、場景、風格（參見 DIRECTOR.md §8）。 如果缺少某項且存在合理的預設值，則選擇它，並說明您選擇了哪些預設值。 只有在答案會改變整部影片時才問問題（例如「您有這些角色的皮膚嗎？」）。 將結果儲存到 films/<name>/brief.md（範本在 docs/PREPRODUCTION.md）。

B. 研究（網路搜尋，記錄連結）

使用 WebSearch / WebFetch。將所有內容寫入 films/<name>/research.md，每個主張都附上連結：

1. 符合調性的動畫語言：節奏、鏡頭、喜劇時機 / 恐怖懸念 / 史詩規模。
2. 剛體角色動畫：預期動作、過衝、跟隨動作、擠壓替代、衝擊幀。
3. 場景參考：方塊建築、色彩調色盤、所選場景的地標。
4. 免費使用的音樂和音效來源：列出來源、曲目名稱和其授權條款。未經使用者許可，切勿下載或添加音訊；使用者提供放入 story.json 的檔案。

然後新增一個 「要應用的原則」 區段：5–10 個您自己的話語要點，每個都與本影片中的某個鏡頭或規則相關。絕不複製其他作品中的場景、角色或台詞；而是提取原則。任何參考影片的本地副本僅保留在 work/（已 gitignore）；只有您書面的結論才會放入儲存庫。

C. 劇本和鏡頭表

使用 DIRECTOR.md §7 中的表格撰寫 films/<name>/shotlist.md（新增一個意圖欄：該鏡頭讓觀眾感受或知道什麼）。根據簡報檢查：一個想法、清晰的節拍（鋪陳 → 升級 → 轉折 → 收尾）、能量曲線（安靜 → 大聲 → 安靜）、根據調性的鏡頭長度、每句台詞簡短。

D. 建構

1. 素材。
   • 使用者傳送皮膚 → 使用那個皮膚，不經修改，直接用在影片中（將其複製到影片資料夾，在 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 資料夾）。
   • 生物：docs/MOBS.md（您需要使用者的紋理；苦力怕形狀、豬形、蜘蛛形的骨架，以及透過玩家骨架的殭屍）。
   • 沒有皮膚 → python core/skin.py make ... 或使用 core/builtin/skins/ 中的原始皮膚。
   • 方塊/物品表 → python core/atlas.py slice|label|faces（參見 docs/BLOCK-ATLAS.md）。僅標記您可以識別的部分。
2. 分鏡腳本。 信箱黑邊和暗角（變暗的角落）來自風格（letterbox、vignette）；對於 2.37:1 的交付格式，最後裁掉黑邊（ffmpeg -vf crop=iw:iw/2.37），這樣播放器就不會顯示黑邊，如果使用者不想要暗角，則關閉它（styleOverride.vignette: false）。 根據鏡頭表撰寫 story.json（docs/STORYBOARD.md）。從最近的 examples/*/story.json 開始。 攝影機偏移是世界空間：將攝影機放在您想看到的臉部前方。
3. 測試靜幀。 python tools/render.py story.json --frame <t> --out check.png 並查看圖片 （先看構圖，然後看光線，再看表演）。
4. 預覽。 python tools/render.py story.json --out preview.mp4 --fps 12 --scale 0.5。
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（僅離線：使用 python tools/voice.py fetch 取得的 Piper 神經語音，例如 --voice piper:faber，或使用支援 SSML 停頓和強調的 Windows OneCore 語音 daniel/maria）， 配合角色設定（hero、villain、monster、child、narrator、radio）。讓每句台詞符合其鏡頭的長度：測量它，然後 調整 --rate 或鏡頭長度。請參閱 films/ 風格的 make_audio.py（在 docs/GENRES.md）。 python tools/audio.py story.json --out mix.wav，聆聽，然後使用音訊渲染（或將混音混合到無聲渲染中）。
6. 最終渲染。 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 中標記為缺失的功能（手持工具、階梯和柵欄、更多生物、潛行/游泳/騎乘剪輯...），請提前說明，並提供最接近的現有替代方案；不要使用不受支援的 JSON 欄位來偽造（這些欄位會被靜默忽略）。
• 在特寫中也要檢查比例，而不僅僅是廣角鏡頭（肩膀與軀幹齊平、頭部直接位於身體上、臉部可辨識）。
• 保持使用者的皮膚/紋理不變；將衍生的檔案以新名稱寫在它們旁邊。
• films/ 和 work/ 下的所有內容都已 gitignore。隨儲存庫附帶的範例位於 examples/。