scenario-side-view-game-kit

场景侧视游戏套件

概述

横向卷轴游戏需要两类无法通过单次生成获得的图像素材：能够在同一条脚线上流畅动画的像素精灵，以及可以叠加形成视差、无缝重复的绘制关卡图层。此工作流程来自一个在单次 Agent 会话中制作的浏览器横向卷轴游戏（一个英雄角色、两个地面敌人、五个关卡）：

1. 角色。 使用文生图生成一张含有两个姿势的静图，背景为纯洋红色（英雄：休息和跳跃；敌人：休息和攻击预备），调整构图并留出头部空间，然后为每个循环生成一个 3 秒的图生视频片段，让角色以纯侧面视角朝右，像“跑步机上跑步”一样奔跑或行走。本地脚本会抠掉洋红色背景，截取循环或单次动作片段，并将角色的每个循环像素化到共用画布和调色板上。坠落、贴墙、俯冲和冲刺动作来自同一张姿势图。只制作一个朝向，游戏会将其镜像。
2. 关卡。 每个关卡生成五张“细节丰富的高分辨率像素艺术”图（背景、中景、墙面纹理、平台条带、道具），并在本地将它们制作为 WebP 图层。

特意在本地完成最后处理：抠图、循环搜索、共用调色板和无缝交叉淡化都需要磁盘上的像素数据，而交付物是游戏文件。如果用户也想将最终条带上传到平台，请使用 upload_asset 将其上传到集合中。

连接、作用范围和核心循环：scenario 技能。帧工具、GIF 预览和引擎切片：scenario-sprite-animation。像素清理和其他静态素材：scenario-game-assets。视频模型系列：scenario-video。音乐和音效不属于此图像技能的范围。如果可用技能中缺少此处提到的某个同级技能，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；如果无人值守，则根据工具架构继续操作并注明缺失项。

Agent 在本地运行脚本（Python 3、Pillow、NumPy；side_sprites.py 还需要 ffmpeg）： reframe_stills.py 用于制作片段的首帧， side_sprites.py 用于构建条带，并导入 sprite_cycles.py（切勿直接运行），而 process_env.py 用于完成关卡图层。带占位项的提示词： references/prompt-templates.md。更改脚本标志或 --report 标记出循环问题时，请先阅读 references/processing-settings.md。

快速参考

步骤	方法	保留标准
模型	对静态图、姿势表和图层，使用 recommend，并设置 capability: "txt2img"；对片段，使用 "img2video" 并设置 features: ["endImage"]，将用户的原话作为 prompt；然后调用 model_schema_get	你了解每个架构的字段名称、枚举值和限制
调整构图并上传	reframe_stills.py：让角色占 960 方形画布的 58%，脚部位于 82% 处；使用 upload_asset 和 upload_asset_complete 上传其余静帧，以及英雄腾空旋转的动作帧	为举起武器或空翻预留头顶空间
姿势表	文本转图像，将选定的静帧作为参考，在洋红色背景上横排呈现 4 种姿势	与精灵条的设计和配色一致
价格和等待	对每种不同的负载设置 dry_run: true，然后分批设置 wait: false，不超过并发上限，并调用 jobs_wait；重复传入 pending_job_ids 调用，直到完成	用户在付费前了解了总价
精灵条	先运行 side_sprites.py --report，再不带 --report 运行	循环接缝（静止侧视除外）低于基准的 0.6 倍；没有实心色块
关卡图层	每个关卡渲染五张，先渲染第 1 关	中下部较暗，中景中心留空，各道具彼此分开
关卡处理	process_env.py --env env --out assets --levels N	纹理平铺，平台边缘平整，道具数量符合预期
交付	精灵条和姿势图以无损 WebP 格式交付，并附上 <name>_meta.json（单元格、脚部锚点、fps）；图层以有损 WebP 格式交付	每个角色只有一个锚点；边缘没有洋红色

下方的负载名称（startImage、endImage、referenceImages、background、quality、 numOutputs、cfgScale）是构建中架构的示例：请使用你选定项的 model_schema_get 列出的字段。图像选项需要具备强布局遵循能力、参考图输入、 透明背景选项和模板要求的 1536x1024 尺寸；如果其架构缺少其中任何一项（像素画专用选项的尺寸上限可能远低于该值），就选择排名下一位的选项，即使 recommend 要求你在这些尺寸受限的选项中进行选择。

完整示例

用户提出请求：“为我的横版卷轴游戏制作美术素材：一位手持细剑的狐狸骑士英雄、一位手持鹤嘴锄的鼹鼠矿工敌人，以及两个关卡：蘑菇森林和水晶矿洞。”每次调用都传入 team_id 和 project_id（scenario 技能介绍了如何选择它们）。

1. 主视觉静帧。 recommend { "capability": "txt2img", "prompt": "<the user's request>; needs reference image input, transparent output" }， 用 model_schema_get 获取所选模型的架构，使用 双姿势模板（左侧： 面向右侧准备站立；右侧：面向右侧腾空跳跃），通过 model_run { "model_id": "<pick>", "dry_run": true, "parameters": { "prompt": "...", "width": 1536, "height": 1024, "quality": "high", "background": "opaque", "numOutputs": 2 } } 估价。告知用户价格，然后运行（如果返回正在进行的任务，使用其 job_id 调用 jobs_wait）， 用 asset_display 查看两张结果；保留一张包含两个姿势、角色呈纯侧面轮廓的图片（每个片段 都会继承四分之三身侧面），且不能有粉色或紫色；用 asset_download 下载，并用 curl -L 将其保存为 fox_two_pose.png。

2. 首帧。 python3 scripts/reframe_stills.py fox_two_pose.png --name fox --out frames 会生成 frames/fox_rest.png（左侧姿势，是每个地面片段的首帧）和 frames/fox_action.png（跳跃姿势）。检查两张图片，然后调用 upload_asset { "file_name": "fox_rest.png", "content_type": "image/png", "kind": "image", "file_size": <bytes> }， PUT 各个分片，再调用 upload_asset_complete { "upload_id": "<id>" }；动作帧也执行同样的操作， 但只有空中旋转会用到它。

3. 主视觉片段。 recommend { "capability": "img2video", "features": ["endImage"], "prompt": "<the user's request>; square clip, no audio" }， 然后调用 model_schema_get。每个循环使用一份载荷，参见 动作模板。使用构建版本的架构：

   run:  { "prompt": "<run sentence> <facing and tail>", "negativePrompt": "<negative>, slowing down, stopping, standing still",
           "startImage": "<fox_rest id>", "duration": "3", "aspectRatio": "1:1", "generateAudio": false }
   atk1: { "prompt": "<attack: a fast rapier thrust ... returns to the starting ready pose> <facing and tail>", "negativePrompt": "<negative>",
           "startImage": "<fox_rest id>", "endImage": "<fox_rest id>", "duration": "3", "aspectRatio": "1:1", "generateAudio": false }
   

   Idle 和 hurt 与 attack 一样固定姿势；air spin 将动作帧 ID 同时用作首帧和尾帧。使用 dry_run: true 为每份不同的载荷估价（仅首帧、固定姿势、调整引导值），告知用户总价；将 "wait": false 的片段按波次启动，且不超过团队并发上限（scenario 技能中的 parallel-custom-jobs 行：启动因该 429 错误被拒绝时不会创建任务，因此应在下一波重新启动， 不要丢弃）；用一次 jobs_wait { "job_ids": [...] } 收集任务，如果仍有任务正在进行，则将返回的 pending_job_ids 作为 job_ids 再次调用（绝不要轮询 job_get）。对每个片段调用 asset_download（视频不传 format），并保存为 clips/fox_<cycle>.mp4；<cycle> 必须与第 5 步 --cycles 中的名称完全一致（run、idle、atk1、spin、hurt）。将每个片段制作为本地 联系表进行检查（ffmpeg -i clips/fox_run.mp4 -vf "fps=6,scale=240:-1,tile=6x3" fox_run_sheet.png）， 因为 asset_display 不显示视频帧；只重新运行那些转向或背向摄像机，或发生位移的片段。

4. 姿势表。 使用 referenceImages: ["<chosen still id>"] 和 姿势表模板进行文生图（倒地、贴墙攀附、 下坠、冲刺）。估价、告知用户、运行并下载为 fox_poses.png。

5. 条带。

   python3 scripts/side_sprites.py --clips clips --name fox --cycles run:loop:8,idle:loop:8,atk1:attack:7,spin:attack:8,hurt:attack:5 --report
   python3 scripts/side_sprites.py --clips clips --name fox --height 56 --palette 28 \
       --cycles run:loop:8,idle:loop:8,atk1:attack:7,spin:attack:8,hurt:attack:5 \
       --poses fox_poses.png --jump frames/fox_action.png --webp --out sprites
   

   将条带以 4 倍放大，并使用最近邻插值查看。如果斜线轨迹被键控成白色块，则使用 --drop atk1=<index>（从 0 开始）和 --force 重新运行。

6. 敌人。 使用相同流程：生成双姿势静帧（休息姿势，以及保持设计一致的攻击蓄力姿势）， 重新构图，只上传 mole_rest.png；行走片段仅使用首帧，采用 持械敌人的行走描述，并在架构支持时使用较低的 引导值，例如 cfgScale: 0.7；attack 和 hurt 固定姿势。 side_sprites.py --clips clips --name mole --height 72 --cycles walk:loop:8,attack:attack:8,hurt:attack:5 --report； 如果行走片段被标记为循环效果较弱，则在任何重新运行之前添加 --range walk=12:48。

7. 分层。 填写蘑菇森林的五个 环境模板（背景和纹理不透明，其余部分透明）。对每个不同的设置执行 dry_run，告知用户总数，然后运行并下载为 env/bg1.png、env/mid1.png、env/tex1.png、 env/ledge1.png、env/props1.png，接着运行 python3 scripts/process_env.py --env env --out assets --levels 1。生成水晶矿洞之前，先将第 1 关放入游戏并让狐狸站在上面；单独处理矿洞时使用 --levels 2,（单独的 2 表示数量，会重新处理第 1 关），重新渲染后使用 --force。

8. 检查。 按照 <name>_meta.json 中的 fps 播放每条动画条带，将纹理平铺到墙上，并绘制一段长平台和一段短平台。

常见错误

• 在跑步或行走动画的结尾帧设定关键帧。 在短暂的移动动画首尾都固定静止帧，会让动画大部分时间都花在加速和减速上。跑步和行走只固定第一帧；待机和所有一次性动作则固定首帧 = 尾帧，让它们回到静止状态。
• 装备武器的敌人行走时挥舞武器。 首次制作的装备武器行走动画中，敌人会在步伐之间挥舞武器，收尾时达到基准速度的 1.44 倍。添加“手臂保持静止……绝不举起、挥舞或转动武器”，在负面提示中加入武器相关措辞，并将指导值设为 0.7 后，收尾时速度降至基准的 0.42 倍。
• 保留特效变成实心色块的帧。 白色刀光轨迹和撞击尘雾会在抠图后变成实心色块；--drop 可移除采样帧，而不会改变共享画布或调色板。
• 为每段质量欠佳的循环动画都付费重新生成。 一段沉重的行走动画收尾速度是基准的 1.03 倍；扩大范围后找到相同的片段，经过审核便直接采用。扩大范围、检查循环动画，只有在明显卡顿时才付费重新生成。
• 按列拆分姿势表。 姿势在水平方向上会重叠；应按连通分量拆分（--poses 会这样做），并要求留出较宽的间隙。
• 相信纹理提示词中的“无缝平铺”。 渲染结果无法可靠地平铺；process_env.py 会交叉淡化相对边缘，无需重新渲染。
• 拉伸平台条带。 绘制左端帽 + 可重复的中段 + 右端帽，确保每种长度都保留雕刻过的端部。
• 复古风格的关卡美术。 小尺寸的复古绘画未能通过首次试玩测试；改用 1920x1152 的精细图层，并以 2 倍尺寸绘制，而精灵仍使用最近邻缩放。先在游戏中验证第 1 关，再制作其余关卡。
• 角色上出现粉色或紫色。 所有明显的洋红色都会被抠掉；提示“角色身上任何地方都不能有粉色、紫色或洋红色”，并拒绝任何出现这些颜色的结果。快速挥舞武器时可能会带上紫色的运动模糊色调，并在挥击中途被抠掉；--drop 无法修复，因为它会移除挥击本身：应拒绝该结果，或重新运行，并在提示词中加入“不要有运动模糊，武器保持原有颜色”，在负面提示中加入“武器带有紫色或洋红色色调”（一次验证运行中，这样去除了色调，但仍有一个撞击帧需要用 --drop 处理）。
• 改写被拦截的战斗片段提示词。 刺击或镐头挥击可能会返回 moderation_blocked，而过滤器由提供方决定：先阅读错误信息，再根据 scenario-moderation，从另一家提供方中选一个，使用未经修改的负载重新运行（保留相同的 recommend 和 endImage 功能），之后再弱化动作描述。
• 有损精灵条带。 有损 WebP 会改变共享调色板；只有高清图层会采用有损格式。