scenario-blender-2d-animation

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; 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, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); 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).

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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).
8. 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.
9. 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.
10. 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: the tile seam goes where the silhouette is lowest, so 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.