blockbench-flipbook-textures

Blockbench 翻页动画纹理

交付一张纵向 PNG，其中包含大小相同的动画帧，并提供经过验证的帧时长和目标所需的元数据。对于 N 帧、每帧 W × H 像素，最终位图尺寸为 W × (H * N)；第 0 帧位于顶部，帧与帧之间不留间隙。每帧都必须是完整的平铺图块或完整的 UV 图集。

必需的技能和工具

• 在修改 Blockbench 内容之前，加载 blockbench-use；检查和分配 UV 时，加载 blockbench-texturing。
• 每当生成或重绘图稿时，都使用 blockbench-gpt-image-textures。 使用其 GPT Image 2.5 Flare/Sunburst 工作流和脚本，包括其 FAL_KEY 处理方式。不得在未说明的情况下替换为其他图像模型。如果依赖项或模型不可用，请说明缺少的能力，并继续进行不依赖图像生成的布局/转换工作。转换现有的用户提供图像表无需再次调用生成。
• 使用 Python 3.10+ 和 Pillow 运行捆绑的转换器（在所选环境中执行 python -m pip install Pillow）。ImageMagick 也适用于经过测量的裁剪和纵向拼接；请保留完整帧边界、明确的数字顺序和 alpha 通道。

相对于已安装的技能解析脚本路径，而不是相对于工作目录。以下命令假定当前目录是此技能所在文件夹；请将输出保存在用户的资源工作区中。

1. 确定动画约定

沿用已提供的要求。生成前，先澄清会影响结果的缺失选项：主体/效果、像素画或绘画风格、每帧像素尺寸、帧数、时长/FPS 或每帧刻数、循环播放还是单次播放、透明度、空间平铺方式以及目标平台（Blockbench 预览、Java 资源包、Bedrock 方块或实体）。不要将用户提供的图像表尺寸推断为单帧尺寸。如果仅未指定时序，请建议每帧 2 刻（10 FPS），并说明这是作出的假设。

请区分以下参数：

参数	含义
W, H	单帧的最终像素尺寸；普通 Minecraft 方块贴图应使用正方形帧
N	导出条带中实际包含的帧数
U, V	单个完整帧的逻辑 UV 尺寸；可能与 W, H 不同
C, R	生成的源图像表的列数和行数，且 C * R >= N
S	整数生成放大倍数；源单元格尺寸为 W*S × H*S
T	Minecraft 元数据中每帧的正整数刻数；FPS = 20/T

对于简单的顺序循环，时长为 N*T/20 秒。自定义播放序列会改变时长。如果请求的 FPS 无法精确表示，请说明刻数取整情况；在预览和导出中保留选定的数值。标准 Minecraft 纹理元数据会循环播放；单次播放需要针对目标平台进行控制，不能虚构循环标志。

对于现有模型，请检查 get_capabilities、list_textures 和相关的 get_cube_uv / get_mesh_info 结果。每帧都应保留单帧 UV 布局和比例。独立的平铺纹理需要明确的完整单元格布局，不得虚构几何体或创建临时模型。骨骼/关键帧动画属于独立工作流。

2. 使用 GPT Image 2.5 生成图集

加载所需的 GPT 图像纹理技能及其 API 限制。在每个帧内应用考虑布局的提示词，然后在每个源单元格偏移处重复该布局。对于独立瓦片，整个单元格就是布局。在描述临时图集网格时，保持现有模型的 UV 不变。

仅当生成器能够表示其宽高比和分辨率时，才优先选择纵向源图集。否则，请选择紧凑网格。已验证的 fal 自定义尺寸限制为：尺寸必须是 16 的倍数，像素数至少为 655,360，最多为 8,294,400，最长边为 3840，宽高比不超过 3:1；必要时重新查阅依赖项当前的 API 参考。放大无法修复过大的宽高比。选择不同的网格、按测量值设置外边距，或明确规划分批生成，同时不更改所需的最终尺寸。请参阅 fal 架构。

阅读图集提示词，了解提示词结构、坐标计算和 16 帧示例。请明确指定：

• 精确的画布和单元格矩形；按行优先的时间顺序排列（从左到右，再从上到下）、已使用的单元格和未使用的末尾单元格。
• 固定的相机、构图、物体锚点、比例、调色板、光照和共享 UV 岛位置。描述每帧的运动阶段，而非主体的独立变化。
• 循环动画的首尾帧无缝衔接；采样阶段为 i/N，除非有意停留需要重复帧，否则不要同时包含 0 和 1。若纹理需要平铺，请另行要求边缘在空间上无缝衔接。
• 不透明瓦片需覆盖整个单元格，透明精灵图需使用真实透明度。不要添加标签、分隔线、说明文字、装饰边框或预先绘制的棋盘格。

使用依赖项的脚本生成，例如：

bun ../blockbench-gpt-image-textures/scripts/fal_gpt_image.mjs --prompt-file /path/to/prompt.json --model flare --width 1024 --height 1024 --background transparent --quality medium --num 1 --format png --out /path/to/output --label portal_sheet

不透明瓦片请使用不透明背景。保存提示词和下载的原始图像。在转换之前，检查实际返回的尺寸、布局、帧内容和透明度。API 的精确画布尺寸并不能确保单元格边界准确。如果内容大量缺失、重叠或不一致，请修正提示词，或使用所需的生成技能编辑相关图像；切片无法修复运动效果。不要在未诊断偏差原因的情况下反复重新生成。

3. 规范化为垂直翻页动画

对于已验证的 1024×1024 源图，其中包含 4×4 个 256×256 单元格，目标为 16 个 32×32 帧：

python scripts/sheet_to_flipbook.py /path/to/source.png /path/to/portal.png --grid 4 4 --count 16 --frame-width 32 --frame-height 32 --ticks-per-frame 2 --preview /path/to/portal-preview.apng

这会生成一个静态 32×512 RGBA PNG、一个用于检查的可选循环 APNG，以及一份输出到 stdout 的 JSON 报告。APNG 是预览图，不是导入 Blockbench 或 Minecraft 的纹理。交接素材时，请将 stdout 保存到报告文件中。转换器不会写入游戏元数据。

• 已经是垂直排列：使用 --grid 1 N；水平排列：使用 --grid N 1。如果垂直源图的尺寸、顺序和 alpha 已完全符合要求，请在验证后直接使用。
• 有未使用的尾部单元格：使用 --count N。物理帧不连续或重复：使用 --indices 0,1,2,1，而不是 --count。这些索引选择的是源单元格；游戏元数据索引指向生成条带中的帧。不要重复应用相同的重排。
• 有外边距或一致的间距：使用 --crop X Y W H 测量网格边界，并使用 --gap X Y 设置单元格之间的间距。所有单位均为源图像像素。
• 布局不规则：传入 --rects /path/to/rectangles.json，使用类似 [[8,8,256,256],[280,8,256,256]] 的 JSON 数组，并按时间顺序排列。矩形必须尺寸相同，且位于源图范围内。请测量完整单元格，并确保锚点一致；分别裁剪每个精灵的不透明边界会造成抖动。
• 像素艺术：默认的最近邻采样可保留清晰边缘。绘制类艺术：使用 --resample lanczos。每帧会在缩放之前裁剪。切勿将整个网格缩放成狭长条带。
• 默认保留 alpha。仅当需要二值抠图 alpha 时才使用 --alpha-threshold 128。不要对烟雾或柔和辉光进行阈值处理。Alpha 量化无法移除不透明的生成背景。

该辅助工具会拒绝单元格尺寸为小数、宽高比变化、索引无效以及覆盖源文件的操作。覆盖已有输出需要使用 --overwrite。测量有误时，请修正布局参数；不要靠猜测裁剪尺寸或拉伸单元格来绕过验证。

4. 导入、配置和验证

导入或生成运行时元数据时，请阅读 Blockbench 和 Minecraft 交付。检查当前格式是否支持 animated_textures、per_texture_uv_size 和 texture_mcmeta。保留预期项目，并使用可用的 MCP 工具或原生对话框。

使用 create_texture 导入静态条带，并且仅将其分配给预期元素。对于支持按纹理设置 UV 尺寸的格式，提供已确定的单帧 uv_width=U、uv_height=V；切勿将条带高度用作单帧 UV 高度。其他格式使用项目 UV 尺寸，因此更改前请检查其对现有纹理的影响。通过受支持的纹理属性或动画 UI 配置计时；不要假设存在 set_flipbook 工具，也不要向 create_texture 传递未记录的参数。

交付前验证以下内容：

• PNG 尺寸恰好为 W × H*N；每帧完整、方向和顺序正确，锚点稳定，透明度适当。
• list_textures 报告的 bitmap_size=[W,H*N]、frame_size=[W,H] 和预期的 uv_size=[U,V]。通过位图高度 / 帧高度验证帧数。
• 检查 APNG 和 Blockbench 中的多个实际帧，包括从最后一帧到第一帧的切换。检查裁切、时间闪烁、不必要的重复、UV 岛偏移、空间接缝，以及在预期查看尺寸下的滤镜效果。仅凭静态截图无法证明动画正常播放。
• 使目标元数据与导出的 PNG 匹配，并在可用时于目标运行时中验证。Java 使用 .png.mcmeta；Bedrock 方块使用 textures/flipbook_textures.json，并绑定纹理图集。Bedrock 实体需要各自的 UV 动画 / 材质设置。

交付条带、所需元数据、源提示词 / 图集、转换报告，以及可选预览，并简洁注明尺寸 / 数量 / 计时信息。说明实际运行了哪些预览和运行时检查。对于 PBR 动画，所有通道都需要相同的帧几何 / 顺序 / 计时；请分别处理各帧，以避免滤镜混合相邻帧。