Scenario Blender 2D animation
Overview
Generate the art once per look; animate it once in Blender. A concept frame (an imagined in-game
screenshot) fixes the style, and the eight other pictures (sky, far and mid layers, ground strip,
foreground plants, props sheet, tree, the hero in two poses) take it as their reference, so the set
holds together. An image-to-video clip of the hero running in place on magenta becomes a looping
image sequence. One Blender script lays the pictures out as flat cards in depth, drives their
parallax from an orthographic camera that follows the hero, keys the jumps and runs rigid-body
physics on the props. A new look is ten new generations and a few measured numbers. The reference
result is a 7.7 second, 1080p, 24 fps shot in three looks. The deliverable is the film and its
.blend, which reads the pictures from SET_DIR/game/ by relative path, so ship the folder with
it; for sprite strips a game engine plays, use scenario-side-view-game-kit or
scenario-sprite-animation.
Discover both lanes with recommend, the user's words as prompt: capability: "txt2img" for the
pictures, which need a reference-image input, a transparent background and exact width and height
(if the pick lacks one, or is a specialty for another style than the look, such as pixel art for a
painted cartoon, take the next ranked pick), and capability: "img2video" for the run clip, which
needs a first frame. model_schema_get each pick. Payload names below (referenceImages,
background, numOutputs) are examples: use the fields your pick's schema lists. Before
generating, tell the user the total for the nine pictures and the clip: dry_run the concept frame
and quote the rest from recommend, since a dry_run naming an asset that does not exist yet
returns 404. Then dry_run each later payload once its input exists, before running it.
Connection, uploads and the core loop: the scenario skill. If a sibling skill named here is
missing from your available skills, load it with skill_get (Scenario MCP) or ask the user to
install it (https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas
and flag the gap.
The scripts run locally and never call Scenario. Blender 5.x runs the scene script, headless or in
an open session (through a Blender MCP connection, for example); in a session, start from File >
New, since --live empties the open file and refuses any file but a new one or its own output.
Python 3 with Pillow, NumPy and SciPy runs the helpers, and ffmpeg reads the clip. Every helper
prints its usage when run without arguments and refuses to overwrite an existing output (or its
input) unless given --force.
Quick reference
| Step |
How |
| Pick models |
recommend (txt2img, img2video), model_schema_get, then model_run with dry_run: true per distinct payload |
| Concept frame |
Text to image, 16:9, opaque, two takes: an in-game screenshot, strict side view, layers named in order (prompts) |
| Layers |
One call per layer with the concept as reference; transparent except the sky; wide (3072 x 1152) for tiled layers |
| Sheets |
Props, tree and foreground on transparent backgrounds with wide gaps, numbered in reading order |
| Hero |
Two poses (rest, jump) side by side on flat magenta; reframe_stills.py makes square first frames |
| Run clip |
Image to video from the rest pose: "like a treadmill", locked camera, magenta that never changes; 5 s is enough |
| Run loop |
run_loop.py: key, find the cleanest one-period loop, write hero_run/run_001.png... |
| Cut and key |
prep_assets.py cut (sheets), key (magenta stills), tile (seamless wide layers) |
| Hulls |
trace_hulls.py: convex hull of each prop's alpha into shapes.json |
| Measure |
measure_set.py: horizon, ground line, island and pedestal tops (example config) |
| Build |
build_scene.py -- --set SET_DIR --review, then --final |
| New look |
New concept frame, the same eight pictures and clip, same file names, a new config.json; nothing else changes |
| Wait |
jobs_wait with up to 32 job_ids; on timeout re-call with the returned pending_job_ids |
Worked example: a jungle run, then a snow day
Pass team_id and project_id on every call (the scenario skill covers picking them).
- Concept frame.
recommend { "capability": "txt2img", "prompt": "<the user's request>; needs reference image input, transparent background, exact width and height" },
model_schema_get the pick, price two takes with
model_run { "model_id": "<pick>", "dry_run": true, "parameters": { "prompt": "...", "width": 1536, "height": 864, "background": "opaque", "numOutputs": 2 } }
and the screenshot prompt from references/prompts.md section 1. Run it,
jobs_wait if it returns a job_id, asset_display both takes and keep the one whose layers
you can name one by one. Its asset id is the reference for everything that follows.
- Layers, one call each. The same pick with
referenceImages: ["<concept id>"]: the sky (2560
x 1440, opaque), the far layer and the mid layer (3072 x 1152, transparent), the ground strip
(2048 x 768, transparent, a flat walkable top at about 30 percent from the top, no end caps) and
a foreground sheet of five plant clusters (3072 x 1024, transparent). Price them, then run them
with wait: false in waves within the team's concurrency ceiling (the parallel-custom-jobs row
in the scenario skill: a launch refused with that 429 created no job, so relaunch it in the
next wave), retiring each wave with jobs_wait.
- Props and tree. A props sheet (2048 x 1536, transparent): numbered props in a loose grid with
wide gaps (a pot, a tall vessel, a lidded jar, a heavy statue, the fruit that will fall, a coin,
a floating island, a flat pedestal), and the tree alone (1024 x 1536) with no fruit in its crown.
The names
cut gives them in step 6 are roles, whatever a new look draws: jar stands on the
pedestal with idol, the heaviest, on its lid and pot_round beside it, amphora stands on the
grass past the landing, and coconut is the fruit.
- Hero. Two poses on flat magenta (1536 x 1024, opaque, two takes): rest on the left, jump on
the right, both the same size, pure side profile facing right.
asset_download the kept take,
then python3 scripts/reframe_stills.py hero.png --name hero --out frames writes hero_rest.png
and hero_action.png (lower --figure for a long tail). Upload the rest frame with
upload_asset and upload_asset_complete.
- Run clip.
recommend { "capability": "img2video", "prompt": "<the user's request>; first frame input, 5 seconds" },
model_schema_get, price a five-second clip with the rest frame's asset id in the schema's
first-frame field and the treadmill prompt (prompts.md section 5), with
audio off and a 1:1 aspect ratio where the schema has those fields (the loop keeps only silent
frames, and the jump still's scale assumes the clip is the square first frame resized), run it,
jobs_wait (minutes, re-called as needed), asset_download.
- Process. Into
jungle/game/ (the sky stays one wide card: copy it as sky.png):
python3 scripts/prep_assets.py tile raw/sea.png jungle/game/sea_tile.png 384, the same for the
mid layer (jungle_tile.png; a fade of one eighth of the width) and the ground
(ground_tile.png, 256 for 2048 px);
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 (it prints run_n,
run_fig_px, run_pad_px and run_canvas_px, the clip's height);
python3 scripts/trace_hulls.py jungle/game. Copy the tree (keyed or already transparent) as
palm.png.
- Measure.
python3 scripts/measure_set.py jungle/game --ground-h 4.3 (the ground card's
height in meters, ground_h in the config) prints the horizon, the walkable line (already moved
10 cm down so the feet sink into the grass lip), the island and pedestal tops and the jump
still's feet row. Write them with the run numbers into jungle/game/config.json. Layer heights,
the fruit positions and the hero's height in meters are set by eye on the review stills: start
from examples/config.json
(references/pipeline.md lists every key).
- Build and review.
blender -b --factory-startup --python-exit-code 1 -P scripts/build_scene.py -- --set jungle --review.
Outputs land in the folder holding jungle/ (or --out DIR): platformer_scene<tag>.blend,
review<tag>/ and, with --final, platformer<tag>.mp4; a rebuild over them needs --force.
Look at the 11 review stills: feet on the ground, the tree standing on the ground, no seam, the
tower standing until the hero reaches it, every piece inside the frame. Then --final renders
the film. Before delivery, walk references/checks.md.
- A new look. Generate a new concept frame (a white winter valley, a snow leopard cub in a red
hat), the same eight pictures and clip with it as reference, process into
snow/game/ with the
same names, measure a new config.json (with "tag": "_snow") and run the same build with
--set snow. Two looks line up frame for frame. The snow clip's background drifted, so its loop
came from
run_loop.py clip.mp4 snow/game/hero_run --key border --from 60 --to 124 --skip 0 --periods 8:16 --clean.
- Ledger. One line per Scenario job with model, parameters, inputs, outputs, job id, cost,
kept or not, and why.
Common mistakes
- Trusting the grass tips as the ground line: every look's hero floated 3 to 8 cm plus the run bob
until the line moved about 10 cm into the lip, which
measure_set.py now applies.
- Keying a drifting clip on fixed magenta: one run clip went from magenta through red and yellow to
green. Use
--key border and take the loop from a stretch away from any red or pink on the
character.
- Cutting leafy sheets with the default grow: the five foreground plants came out as four pieces
until the cut ran with
CUT_GROW=2. Check the printed count against the names.
- Not checking enclosed pink after keying:
prep_assets.py key keeps pink enclosed by the
silhouette (a cat's inner ears), but look at ears, tongues and flowers.
- Hard-coding the run length: the cat and the snow leopard looped in 12 frames, the red panda in 9.
Copy
run_n from run_loop.py's output.
- A landmark at the end of a wide layer:
tile joins the two ends along the path where they differ
least, keeping a tree whole or dropping it, but a landmark as wide as the overlap gets cut; ask
for content spread across the width.
- Passing a local path or URL to
model_run: upload the file first and pass the asset id.
- Hard-coding model ids or prices, or polling
job_get instead of re-calling jobs_wait.
Changing build_scene.py itself (depths, parallax factors, physics): read
references/pipeline.md first, which records the decisions the reference
shot paid for.
1---2name: scenario-blender-2d-animation3description: "Use when a 2D side-scroller shot, platformer cutscene, game trailer or parallax animation has to be built in Blender from Scenario-generated pictures (flat image cards, an orthographic camera, keyed jumps, rigid-body props), or when a finished shot needs a new theme or look without re-animating. Also use when image planes in Blender float above the ground, a tiled parallax layer shows a seam, or physics props leave the picture plane."4license: MIT5metadata:6 source: https://skillmd.com/skills/scenario-labs/scenario-blender-2d-animation7---89# Scenario Blender 2D animation1011## Overview1213Generate the art once per look; animate it once in Blender. A concept frame (an imagined in-game14screenshot) fixes the style, and the eight other pictures (sky, far and mid layers, ground strip,15foreground plants, props sheet, tree, the hero in two poses) take it as their reference, so the set16holds together. An image-to-video clip of the hero running in place on magenta becomes a looping17image sequence. One Blender script lays the pictures out as flat cards in depth, drives their18parallax from an orthographic camera that follows the hero, keys the jumps and runs rigid-body19physics on the props. A new look is ten new generations and a few measured numbers. The reference20result is a 7.7 second, 1080p, 24 fps shot in three looks. The deliverable is the film and its21`.blend`, which reads the pictures from `SET_DIR/game/` by relative path, so ship the folder with22it; for sprite strips a game engine plays, use `scenario-side-view-game-kit` or23`scenario-sprite-animation`.2425Discover both lanes with `recommend`, the user's words as `prompt`: `capability: "txt2img"` for the26pictures, which need a reference-image input, a transparent background and exact width and height27(if the pick lacks one, or is a specialty for another style than the look, such as pixel art for a28painted cartoon, take the next ranked pick), and `capability: "img2video"` for the run clip, which29needs a first frame. `model_schema_get` each pick. Payload names below (`referenceImages`,30`background`, `numOutputs`) are examples: use the fields your pick's schema lists. Before31generating, tell the user the total for the nine pictures and the clip: `dry_run` the concept frame32and quote the rest from `recommend`, since a `dry_run` naming an asset that does not exist yet33returns 404. Then `dry_run` each later payload once its input exists, before running it.3435Connection, uploads and the core loop: the `scenario` skill. If a sibling skill named here is36missing from your available skills, load it with `skill_get` (Scenario MCP) or ask the user to37install it (https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas38and flag the gap.3940The scripts run locally and never call Scenario. Blender 5.x runs the scene script, headless or in41an open session (through a Blender MCP connection, for example); in a session, start from File >42New, since `--live` empties the open file and refuses any file but a new one or its own output.43Python 3 with Pillow, NumPy and SciPy runs the helpers, and ffmpeg reads the clip. Every helper44prints its usage when run without arguments and refuses to overwrite an existing output (or its45input) unless given `--force`.4647## Quick reference4849| Step | How |50| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |51| Pick models | `recommend` (`txt2img`, `img2video`), `model_schema_get`, then `model_run` with `dry_run: true` per distinct payload |52| Concept frame | Text to image, 16:9, opaque, two takes: an in-game screenshot, strict side view, layers named in order ([prompts](references/prompts.md)) |53| Layers | One call per layer with the concept as reference; transparent except the sky; wide (3072 x 1152) for tiled layers |54| Sheets | Props, tree and foreground on transparent backgrounds with wide gaps, numbered in reading order |55| Hero | Two poses (rest, jump) side by side on flat magenta; [reframe_stills.py](scripts/reframe_stills.py) makes square first frames |56| Run clip | Image to video from the rest pose: "like a treadmill", locked camera, magenta that never changes; 5 s is enough |57| Run loop | [run_loop.py](scripts/run_loop.py): key, find the cleanest one-period loop, write `hero_run/run_001.png`... |58| Cut and key | [prep_assets.py](scripts/prep_assets.py) `cut` (sheets), `key` (magenta stills), `tile` (seamless wide layers) |59| Hulls | [trace_hulls.py](scripts/trace_hulls.py): convex hull of each prop's alpha into `shapes.json` |60| Measure | [measure_set.py](scripts/measure_set.py): horizon, ground line, island and pedestal tops ([example config](examples/config.json)) |61| Build | [build_scene.py](scripts/build_scene.py) `-- --set SET_DIR --review`, then `--final` |62| New look | New concept frame, the same eight pictures and clip, same file names, a new `config.json`; nothing else changes |63| Wait | `jobs_wait` with up to 32 `job_ids`; on timeout re-call with the returned `pending_job_ids` |6465## Worked example: a jungle run, then a snow day6667Pass `team_id` and `project_id` on every call (the `scenario` skill covers picking them).68691. **Concept frame.**70 `recommend { "capability": "txt2img", "prompt": "<the user's request>; needs reference image input, transparent background, exact width and height" }`,71 `model_schema_get` the pick, price two takes with72 `model_run { "model_id": "<pick>", "dry_run": true, "parameters": { "prompt": "...", "width": 1536, "height": 864, "background": "opaque", "numOutputs": 2 } }`73 and the screenshot prompt from [references/prompts.md](references/prompts.md) section 1. Run it,74 `jobs_wait` if it returns a `job_id`, `asset_display` both takes and keep the one whose layers75 you can name one by one. Its asset id is the reference for everything that follows.762. **Layers, one call each.** The same pick with `referenceImages: ["<concept id>"]`: the sky (256077 x 1440, opaque), the far layer and the mid layer (3072 x 1152, transparent), the ground strip78 (2048 x 768, transparent, a flat walkable top at about 30 percent from the top, no end caps) and79 a foreground sheet of five plant clusters (3072 x 1024, transparent). Price them, then run them80 with `wait: false` in waves within the team's concurrency ceiling (the `parallel-custom-jobs` row81 in the `scenario` skill: a launch refused with that 429 created no job, so relaunch it in the82 next wave), retiring each wave with `jobs_wait`.833. **Props and tree.** A props sheet (2048 x 1536, transparent): numbered props in a loose grid with84 wide gaps (a pot, a tall vessel, a lidded jar, a heavy statue, the fruit that will fall, a coin,85 a floating island, a flat pedestal), and the tree alone (1024 x 1536) with no fruit in its crown.86 The names `cut` gives them in step 6 are roles, whatever a new look draws: `jar` stands on the87 pedestal with `idol`, the heaviest, on its lid and `pot_round` beside it, `amphora` stands on the88 grass past the landing, and `coconut` is the fruit.894. **Hero.** Two poses on flat magenta (1536 x 1024, opaque, two takes): rest on the left, jump on90 the right, both the same size, pure side profile facing right. `asset_download` the kept take,91 then `python3 scripts/reframe_stills.py hero.png --name hero --out frames` writes `hero_rest.png`92 and `hero_action.png` (lower `--figure` for a long tail). Upload the rest frame with93 `upload_asset` and `upload_asset_complete`.945. **Run clip.**95 `recommend { "capability": "img2video", "prompt": "<the user's request>; first frame input, 5 seconds" }`,96 `model_schema_get`, price a five-second clip with the rest frame's asset id in the schema's97 first-frame field and the treadmill prompt ([prompts.md](references/prompts.md) section 5), with98 audio off and a 1:1 aspect ratio where the schema has those fields (the loop keeps only silent99 frames, and the jump still's scale assumes the clip is the square first frame resized), run it,100 `jobs_wait` (minutes, re-called as needed), `asset_download`.1016. **Process.** Into `jungle/game/` (the sky stays one wide card: copy it as `sky.png`):102 `python3 scripts/prep_assets.py tile raw/sea.png jungle/game/sea_tile.png 384`, the same for the103 mid layer (`jungle_tile.png`; a fade of one eighth of the width) and the ground104 (`ground_tile.png`, `256` for 2048 px);105 `python3 scripts/prep_assets.py cut raw/props.png jungle/game pot_round,amphora,jar,idol,coconut,coin,island,pedestal`;106 `CUT_GROW=2 python3 scripts/prep_assets.py cut raw/foreground.png jungle/game fg_bush,fg_fern,fg_hibiscus,fg_boulder,fg_curl`;107 `python3 scripts/prep_assets.py key frames/hero_action.png jungle/game/hero_jump.png`;108 `python3 scripts/run_loop.py clips/hero_run.mp4 jungle/game/hero_run` (it prints `run_n`,109 `run_fig_px`, `run_pad_px` and `run_canvas_px`, the clip's height);110 `python3 scripts/trace_hulls.py jungle/game`. Copy the tree (keyed or already transparent) as111 `palm.png`.1127. **Measure.** `python3 scripts/measure_set.py jungle/game --ground-h 4.3` (the ground card's113 height in meters, `ground_h` in the config) prints the horizon, the walkable line (already moved114 10 cm down so the feet sink into the grass lip), the island and pedestal tops and the jump115 still's feet row. Write them with the run numbers into `jungle/game/config.json`. Layer heights,116 the fruit positions and the hero's height in meters are set by eye on the review stills: start117 from [examples/config.json](examples/config.json)118 ([references/pipeline.md](references/pipeline.md) lists every key).1198. **Build and review.**120 `blender -b --factory-startup --python-exit-code 1 -P scripts/build_scene.py -- --set jungle --review`.121 Outputs land in the folder holding `jungle/` (or `--out DIR`): `platformer_scene<tag>.blend`,122 `review<tag>/` and, with `--final`, `platformer<tag>.mp4`; a rebuild over them needs `--force`.123 Look at the 11 review stills: feet on the ground, the tree standing on the ground, no seam, the124 tower standing until the hero reaches it, every piece inside the frame. Then `--final` renders125 the film. Before delivery, walk [references/checks.md](references/checks.md).1269. **A new look.** Generate a new concept frame (a white winter valley, a snow leopard cub in a red127 hat), the same eight pictures and clip with it as reference, process into `snow/game/` with the128 same names, measure a new `config.json` (with `"tag": "_snow"`) and run the same build with129 `--set snow`. Two looks line up frame for frame. The snow clip's background drifted, so its loop130 came from131 `run_loop.py clip.mp4 snow/game/hero_run --key border --from 60 --to 124 --skip 0 --periods 8:16 --clean`.13210. **Ledger.** One line per Scenario job with model, parameters, inputs, outputs, job id, cost,133 kept or not, and why.134135## Common mistakes136137- Trusting the grass tips as the ground line: every look's hero floated 3 to 8 cm plus the run bob138 until the line moved about 10 cm into the lip, which `measure_set.py` now applies.139- Keying a drifting clip on fixed magenta: one run clip went from magenta through red and yellow to140 green. Use `--key border` and take the loop from a stretch away from any red or pink on the141 character.142- Cutting leafy sheets with the default grow: the five foreground plants came out as four pieces143 until the cut ran with `CUT_GROW=2`. Check the printed count against the names.144- Not checking enclosed pink after keying: `prep_assets.py key` keeps pink enclosed by the145 silhouette (a cat's inner ears), but look at ears, tongues and flowers.146- Hard-coding the run length: the cat and the snow leopard looped in 12 frames, the red panda in 9.147 Copy `run_n` from `run_loop.py`'s output.148- A landmark at the end of a wide layer: `tile` joins the two ends along the path where they differ149 least, keeping a tree whole or dropping it, but a landmark as wide as the overlap gets cut; ask150 for content spread across the width.151- Passing a local path or URL to `model_run`: upload the file first and pass the asset id.152- Hard-coding model ids or prices, or polling `job_get` instead of re-calling `jobs_wait`.153154Changing `build_scene.py` itself (depths, parallax factors, physics): read155[references/pipeline.md](references/pipeline.md) first, which records the decisions the reference156shot paid for.