BlockReel：从创意到动画

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    # 原版游戏纹理 + 怪物/箱子/史蒂夫/艾利克斯纹理 -> 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 "<频道名>" --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；如果是旧版 64×32 格式，用 convert 转换为新文件。你创建的皮肤必须通过 validate（64×64 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 以及至少两次人工审视轮次。方块/物品纹理或资源包 → 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，或 Windows OneCore 语音 daniel/maria，支持 SSML 停顿和强调），并配合角色预设（hero、villain、monster、child、narrator、radio）。让每句台词适配其所在镜头：先测量长度，然后调整 --rate 或镜头时长。详见 films/-style 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。软件 OpenGL 渲染速度约为 960×540 分辨率下每帧 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/。