scenario-blender-2d-animation

Scenario Blender 2D 动画

概述

每种视觉风格生成一次美术素材；在 Blender 中将其动画化。概念帧（想象中的游戏截图）确定风格，另外八张图片（天空、远景和中景层、地面条带、前景植物、道具表、树木、英雄角色的两个姿势）都以它为参考，因此整套素材风格统一。将英雄角色在洋红色背景上原地奔跑的图生视频片段转换为循环图像序列。一个 Blender 脚本将图片作为平面卡片按深度排布，通过跟随英雄角色的正交摄像机驱动视差，为跳跃设置关键帧，并在道具上运行刚体物理效果。更换视觉风格只需重新生成十张素材，再调整几个测量数值。参考成片是一个 7.7 秒、1080p、24 fps 的镜头，包含三种视觉风格。交付内容是影片及其 .blend 文件；该文件通过相对路径从 SET_DIR/game/ 读取图片，因此请将此文件夹一并交付；如果要制作供游戏引擎播放的精灵图条，请使用 scenario-side-view-game-kit 或 scenario-sprite-animation。

使用 recommend 发现这两类工具，并将用户的文字作为 prompt：图片使用 capability: "txt2img"，需要支持参考图输入、透明背景和指定的宽度与高度（如果候选工具不支持其中任一项，或是面向与视觉风格不同类型的专用工具，例如为手绘卡通选择了像素艺术工具，请选取排名靠后的下一项），奔跑片段使用 capability: "img2video"，需要支持首帧。对每个候选工具调用 model_schema_get。以下载荷名称（referenceImages、background、numOutputs）仅为示例：请使用候选工具架构中列出的字段。生成前，告知用户九张图片和视频片段的总费用：对概念帧执行 dry_run，其余费用引用 recommend 的结果，因为为尚不存在的素材执行 dry_run 会返回 404。然后在每个后续载荷的输入准备就绪后、运行生成前，分别对其执行一次 dry_run。

连接、上传和核心流程：参阅 scenario 技能。如果当前可用技能中缺少此处提到的同名技能，请让用户安装 （npx skills add scenario-labs/skills --skill <name>）；在无人值守的情况下，依据工具架构继续操作，并指出缺少该技能。

脚本在本地运行，不会调用 Scenario。Blender 5.x 运行场景脚本，可在无头模式下运行，也可在已打开的会话中运行（例如通过 Blender MCP 连接）；在会话中，请从 File > New 开始，因为 --live 会清空当前打开的文件，并且只接受新文件或其自身的输出文件。 Python 3 配合 Pillow、NumPy 和 SciPy 运行辅助脚本，ffmpeg 读取视频片段。每个辅助脚本在不带参数运行时都会打印用法说明；除非指定 --force，否则不会覆盖已有的输出文件（或其输入文件）。

快速参考

步骤	方法
选择模型	对每种不同的负载，先调用 recommend（txt2img、img2video），再调用 model_schema_get，然后使用 dry_run: true 调用 model_run
概念帧	文本生成图像，16:9，不透明，生成两版：一张游戏内截图、严格侧视图、图层按顺序命名（提示词）
图层	每个图层单独调用一次，并以概念图为参考；除天空外均为透明背景；平铺图层使用宽幅尺寸（3072 x 1152）
图集	道具、树木和前景使用透明背景，彼此留出较大间距，并按阅读顺序编号
主角	两个姿势（休息、跳跃）并排放在纯洋红色背景上；reframe_stills.py 会生成方形的首帧
奔跑片段	从休息姿势图生成视频：“像在跑步机上一样”，摄像机锁定，洋红色始终不变；5 秒足够
奔跑循环	run_loop.py：指定关键帧，找到最干净的单周期循环，写入 hero_run/run_001.png...
裁切与抠图	prep_assets.py 的 cut（图集）、key（洋红色静帧）、tile（无缝宽幅图层）
凸包	trace_hulls.py：将每个道具的 alpha 通道转换为凸包，写入 shapes.json
测量	measure_set.py：地平线、地面线、岛屿和基座顶部（示例配置）
构建	build_scene.py -- --set SET_DIR --review，然后运行 --final
新外观	新的概念帧、相同的八张图片和片段、相同的文件名、新的 config.json；其他一概不变
等待	使用 jobs_wait，最多传入 32 个 job_ids；超时后使用返回的 pending_job_ids 再次调用

实例：先来一场丛林奔跑，再过一个雪天

每次调用都传入 team_id 和 project_id（scenario 技能会介绍如何选择它们）。

1. 概念画面。 recommend { "capability": "txt2img", "prompt": "<the user's request>; needs reference image input, transparent background, exact width and height" }， 用 model_schema_get 获取所选模型的架构，用 model_run { "model_id": "<pick>", "dry_run": true, "parameters": { "prompt": "...", "width": 1536, "height": 864, "background": "opaque", "numOutputs": 2 } } 对两张图进行价格估算，并使用 references/prompts.md 第 1 节中的截图提示词。运行后， 如果返回 job_id，就调用 jobs_wait；用 asset_display 查看两张图，并保留图层 能够逐一命名的那张。它的资源 ID 将作为后续所有步骤的参考。
2. 图层，每次调用一个。 使用同一所选模型，并设置 referenceImages: ["<concept id>"]：天空（2560 x 1440，不透明）、远景层和中景层（3072 x 1152，透明）、地面条（2048 x 768，透明，平坦可行走的顶部 约在距顶部 30 percent 处，没有端盖），以及包含五簇植物的前景图层（3072 x 1024，透明）。对它们进行价格估算，然后 按团队并发上限分批运行，并设置 wait: false（参见 scenario 技能中的 parallel-custom-jobs 行：如果启动因 429 被拒绝，就不会创建任务，因此应在 下一批重新启动），每批完成后调用 jobs_wait。
3. 道具和树。 一张道具图（2048 x 1536，透明）：道具按编号松散排列，彼此留有较大间距（一个花盆、 一个高瓶、一个带盖罐、一尊沉重的雕像、将会掉落的水果、一枚硬币、一座浮岛、一个扁平基座）；另生成一棵独立的树（1024 x 1536），树冠上不要有水果。 第 6 步中 cut 为它们指定的名称代表其用途，无论新外观生成了什么：jar 放在基座上，最重的 idol 放在罐盖上，pot_round 放在旁边；amphora 放在着陆点以外的草地上， coconut 就是水果。
4. 主角。 在纯洋红色背景上生成两个姿势（1536 x 1024，不透明，两张图）：左侧是静止姿势，右侧是跳跃姿势， 两者大小相同，均为朝右的纯侧面轮廓。用 asset_download 下载保留的那张，然后 python3 scripts/reframe_stills.py hero.png --name hero --out frames 会生成 hero_rest.png 和 hero_action.png（长尾巴时调低 --figure）。用 upload_asset 和 upload_asset_complete 上传静止帧。
5. 运行片段。 recommend { "capability": "img2video", "prompt": "<the user's request>; first frame input, 5 seconds" }， 用 model_schema_get 获取架构；将静止帧的资源 ID 填入架构的首帧字段，并使用跑步机提示词（prompts.md 第 5 节），对五秒片段进行价格估算；关闭音频，并在架构包含这些字段时设置 1:1 宽高比（循环只保留静音帧，且跳跃静帧的缩放比例假设片段是经过缩放的正方形首帧）。运行后调用 jobs_wait（等待数分钟，视需要重复调用），再调用 asset_download。
6. 处理。 将文件放入 jungle/game/（天空保持为一张宽图卡：复制为 sky.png）： python3 scripts/prep_assets.py tile raw/sea.png jungle/game/sea_tile.png 384，对中景层执行同样的操作（输出为 jungle_tile.png；渐隐宽度为其宽度的八分之一），地面也同样处理 （输出为 ground_tile.png，2048 px 图像使用 256）； python3 scripts/prep_assets.py cut raw/props.png jungle/game pot_round,amphora,jar,idol,coconut,coin,island,pedestal； CUT_GROW=2 python3 scripts/prep_assets.py cut raw/foreground.png jungle/game fg_bush,fg_fern,fg_hibiscus,fg_boulder,fg_curl； python3 scripts/prep_assets.py key frames/hero_action.png jungle/game/hero_jump.png； python3 scripts/run_loop.py clips/hero_run.mp4 jungle/game/hero_run（它会输出 run_n、 run_fig_px、run_pad_px 和 run_canvas_px，即片段的高度）； python3 scripts/trace_hulls.py jungle/game。将树复制为 palm.png（可以先去除背景，也可以使用已透明的版本）。
7. 测量。 python3 scripts/measure_set.py jungle/game --ground-h 4.3（地面图卡的高度，单位为米；在配置中对应 ground_h）会输出地平线、可行走线（已向下移动 10 cm，使脚陷入草地边缘）、浮岛和基座的顶部，以及跳跃静帧的脚部所在行。将这些数据连同跑步循环的数值写入 jungle/game/config.json。图层高度、水果位置和主角的米制高度需根据审核静帧目测设置：以 examples/config.json 为起点 （references/pipeline.md 列出了所有键）。
8. 构建并审核。 blender -b --factory-startup --python-exit-code 1 -P scripts/build_scene.py -- --set jungle --review。 输出会放在包含 jungle/ 的文件夹中（或 --out DIR 指定的位置）：platformer_scene<tag>.blend、 review<tag>/，以及使用 --final 时生成的 platformer<tag>.mp4；覆盖这些文件重新构建需添加 --force。 查看 11 张审核静帧：脚是否踩在地面上、树是否立在地面上、是否没有接缝、塔是否能一直立着直到主角到达，以及每个元素是否都在画面内。然后使用 --final 渲染影片。交付前，按 references/checks.md 逐项检查。
9. 新外观。 生成一张新的概念画面（白色冬日山谷、戴红帽子的雪豹幼崽），以它为参考生成相同的八张图和片段，将结果用相同的名称处理到 snow/game/，测量并生成新的 config.json（设置 "tag": "_snow"），然后运行相同的构建命令并指定 --set snow。两种外观的帧会逐帧对齐。雪景片段的背景发生了漂移，因此其循环采用以下命令生成： run_loop.py clip.mp4 snow/game/hero_run --key border --from 60 --to 124 --skip 0 --periods 8:16 --clean。
10. 记录台账。 每个 Scenario 任务记录一行，写明模型、参数、输入、输出、任务 ID、成本、是否保留，以及保留或不保留的原因。

常见错误

• 把草尖当作地面线：每个镜头里的主角都漂浮了 3 到 8 cm，此外还叠加了奔跑时的上下起伏， 直到将地面线向下移入嘴部约 10 cm；measure_set.py 现在会应用这一调整。
• 用固定的洋红色对渐变片段进行抠像：有一段奔跑动画从洋红色逐渐变成红色、黄色，最后变成 绿色。使用 --key border，并从远离角色上红色或粉色区域的一段中截取循环片段。
• 用默认扩张量裁切有叶片的图层：五株前景植物最后被切成了四块，直到裁切时设置了 CUT_GROW=2。请检查打印出的数量是否与名称一致。
• 抠像后不检查封闭的粉色区域：prep_assets.py key 会保留轮廓内部的粉色区域（例如猫的内耳）， 但仍需检查耳朵、舌头和花朵。
• 将奔跑循环的长度写死：猫和雪豹的循环为 12 帧，小熊猫为 9 帧。请从 run_loop.py 的输出中 复制 run_n。
• 在宽图层的边缘放置地标：tile 会沿着差异最小的路径连接两端，使树木保持完整或被移除； 但宽度与重叠区一样宽的地标会被裁掉；请让内容分布在整个宽度上。
• 将本地路径或 URL 传给 model_run：请先上传文件，再传入资源 ID。
• 将模型 ID 或价格写死，或者轮询 job_get，而不是重新调用 jobs_wait。

如果要修改 build_scene.py 本身（深度、视差系数、物理效果），请先阅读 references/pipeline.md，其中记录了参考镜头所采用的方案。