Skip to main content
skill CX Codex

blockbench-flipbook-textures — Claude Code skill: how it works

blockbench-flipbook-textures is a Claude Code skill that plans and packs animated flipbook textures for Blockbench and Minecraft, turning sprite grids into vertical PNG strips.

Apache-2.0 281 installs ★ 30 updated 2026-09-26

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-flipbook-textures -a claude-code
Open on GitHub

What blockbench-flipbook-textures does

The skill organizes frame dimensions, animates textures through GPT Image 2.5, and repacks sprite sheets into a single vertical PNG strip. In Minecraft and Blockbench workflows, N frames of size W × H must sit stacked top to bottom as W × (H * N) without gutters.

Processing relies on the bundled scripts/sheet_to_flipbook.py utility. It slices row-major source grids, resizes frames, preserves transparency, and can emit a looping APNG preview alongside standard JSON output.

Python 3.10+ with Pillow and an active FAL_KEY environment variable are required before generating any new frames. Converting an existing local sheet bypasses API calls entirely.

What it helps with

  • repack a sprite grid into a vertical flipbook PNG for Minecraft
  • calculate frame durations and game tick intervals for block animations
  • generate looping animated textures using GPT Image 2.5
  • build an APNG animation preview to verify frame pacing before export

Example prompts for the agent

  • Convert the 4x4 sprite sheet in textures/water.png into a 32x32 vertical strip at 2 ticks per frame.
  • Generate a looping fire texture grid using GPT Image and turn it into a Minecraft flipbook.
  • Inspect assets/lava.png, calculate its timing at 10 FPS, and export an APNG preview.

How to install blockbench-flipbook-textures

1Skills CLI (Vercel)

npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-flipbook-textures -a claude-code

2Manually: put the files in place

~/.claude/skills/blockbench-flipbook-textures/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/blockbench-flipbook-textures/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about blockbench-flipbook-textures

How to install blockbench-flipbook-textures in Claude Code?

Run npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-flipbook-textures -a claude-code. The skill file will be stored at ~/.claude/skills/blockbench-flipbook-textures/SKILL.md.

What does blockbench-flipbook-textures do?

It manages prompt planning for GPT Image 2.5 sprite sheets and converts image grids into vertically stacked flipbook PNGs for Minecraft models.

What dependencies are needed to use this skill?

You need Python 3.10 or newer with Pillow, bun to execute the generation helper, and a valid FAL_KEY for API access.

Source text

SKILL.md · Apache-2.0
---
name: blockbench-flipbook-textures
description: Create animated flipbook textures for Blockbench and Minecraft using blockbench-gpt-image-textures and GPT Image 2.5. Plan frame dimensions and motion, generate a sprite sheet, repack grids or horizontal sheets into a vertical PNG, and configure animation playback and target metadata. Use for animated block textures, looping texture effects, or sprite-sheet-to-flipbook conversion.
---

# Blockbench Flipbook Textures

Deliver a vertical PNG containing equal-sized animation frames, with verified timing and the metadata needed by the requested target. For `N` frames of `W × H` pixels, the final bitmap is **`W × (H * N)`**, frame 0 at the top, with no gutters between frames. Each frame is a complete tile or complete UV atlas.

## Required Skills and Tools

- Load [blockbench-use](../blockbench-use/SKILL.md) before Blockbench content changes and [blockbench-texturing](../blockbench-texturing/SKILL.md) for UV inspection and assignment.
- **Use [blockbench-gpt-image-textures](../blockbench-gpt-image-textures/SKILL.md) whenever generating or repainting the artwork.** Use its GPT Image 2.5 Flare/Sunburst workflow and scripts, including its `FAL_KEY` handling. Do not silently substitute a different image model. If the dependency or model is unavailable, explain the missing capability and continue layout/conversion work that does not depend on generation. Converting an existing supplied sheet does not require another generation call.
- Use Python 3.10+ and Pillow for the bundled converter (`python -m pip install Pillow` in the chosen environment). ImageMagick is also suitable for measured crops and vertical assembly; preserve full frame bounds, explicit numeric order, and alpha.

Resolve script paths relative to the installed skills, not the working directory. Commands below assume the current directory is this skill's folder; keep outputs in the user's asset workspace.

## 1. Establish the Animation Contract

Reuse requirements already given. Clarify missing choices that change the result before generating: subject/effect, pixel-art or painted style, **per-frame** pixel size, frame count, duration/FPS or ticks per frame, loop versus one-shot, transparency, spatial tiling, and destination (Blockbench preview, Java resource pack, Bedrock block, or entity). Do not infer that a supplied sheet size is a frame size. If only the timing is unspecified, propose 2 ticks/frame (10 FPS) and state that assumption.

Keep these quantities separate:

| Quantity | Meaning |
|---|---|
| `W, H` | Final pixels in one frame; use square frames for ordinary Minecraft block tiles |
| `N` | Number of physical frames in the exported strip |
| `U, V` | Logical UV dimensions for one complete frame; may differ from `W, H` |
| `C, R` | Columns and rows of the generated source sheet, with `C * R >= N` |
| `S` | Integer generation upscale; source cells are `W*S × H*S` |
| `T` | Positive integer ticks per frame for Minecraft metadata; FPS = `20/T` |

For a simple sequential cycle, duration is `N*T/20` seconds. A custom playback schedule changes that duration. Explain tick rounding when requested FPS cannot be represented exactly; retain the chosen value in preview and export. Standard Minecraft texture metadata loops; one-shot playback requires target-specific control rather than a made-up loop flag.

For an existing model, inspect `get_capabilities`, `list_textures`, and relevant `get_cube_uv` / `get_mesh_info` results. Preserve the one-frame UV layout and proportions in every frame. A standalone tiling texture needs an explicit full-cell layout, not invented geometry or a throwaway model. Bone/keyframe animation is a separate workflow.

## 2. Generate the Sheet with GPT Image 2.5

Load the required GPT image texture skill and its [API constraints](../blockbench-gpt-image-textures/references/fal-api.md). Apply its layout-aware prompting **inside each frame**, then repeat that layout at each source-cell offset. For standalone tiles, the whole cell is the layout. Keep the existing model's UVs unchanged when describing the temporary sheet grid.

Prefer a vertical source sheet only when the generator can represent its aspect ratio and resolution. Otherwise choose a compact grid. The verified fal custom-size limits are multiples of 16, at least 655,360 and at most 8,294,400 pixels, longest edge 3840, and aspect ratio at most 3:1; recheck the dependency's current API reference when needed. An upscale cannot fix an excessive aspect ratio. Choose a different grid, measured outer padding, or explicitly planned batches without changing the requested final dimensions. See the [fal schema](https://fal.ai/models/openai/gpt-image-2.5/flare/text-to-image/api).

Read [sheet prompting](references/sheet-prompting.md) for the prompt structure, coordinate math, and a 16-frame example. Explicitly specify:

- Exact canvas and cell rectangles; row-major chronological order (left to right, then top to bottom), used cells, and unused trailing cells.
- Fixed camera, framing, object anchor, scale, palette, lighting, and shared UV island positions. Describe each frame's motion phase, not independent variations of the subject.
- A seamless last-to-first transition for loops; sample phases `i/N` rather than including both 0 and 1 unless an intentional hold calls for a duplicate. Request spatially seamless edges separately when the texture must tile.
- Full-cell coverage for opaque tiles, or real alpha for transparent sprites. No labels, dividers, captions, decorative borders, or baked checkerboard.

Generate using the dependency's script, for example:

```bash
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
```

Use an opaque background for an opaque tile. Save the prompt and downloaded original. Inspect the **actual** returned dimensions, layout, frame content, and alpha before conversion. An exact API canvas size does not enforce accurate cell boundaries. If substantial content is missing, overlapping, or inconsistent, correct the prompt or edit the relevant artwork with the required generation skill; slicing cannot repair motion. Do not repeatedly regenerate without diagnosing the mismatch.

## 3. Normalize to a Vertical Flipbook

For a verified 1024×1024 source with a 4×4 grid of 256×256 cells, targeting sixteen 32×32 frames:

```bash
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
```

This produces a **static 32×512 RGBA PNG**, an optional looping APNG for inspection, and a JSON report on stdout. The APNG is a preview, not the texture imported into Blockbench or Minecraft. Capture stdout to a report file when handing off assets. The converter does not write game metadata.

- Already vertical: use `--grid 1 N`; horizontal: `--grid N 1`. If the vertical source already has the exact dimensions, order, and alpha, use it directly after validation.
- Unused trailing cells: use `--count N`. Nonsequential or repeated physical frames: use `--indices 0,1,2,1` instead of `--count`. These indices select **source cells**; game metadata indices address the **resulting strip**. Do not apply the same reordering twice.
- Outer padding or consistent gutters: measure `--crop X Y W H` for the grid bounds and `--gap X Y` between cells. All units are source-image pixels.
- Irregular placement: pass `--rects /path/to/rectangles.json`, a JSON array such as `[[8,8,256,256],[280,8,256,256]]`, ordered chronologically. Rectangles must have equal dimensions and remain within the source. Measure complete cells with consistent anchors; independently trimming each sprite's opaque bounds introduces jitter.
- Pixel art: the default nearest-neighbor sampling preserves hard edges. Painted art: use `--resample lanczos`. Each frame is cropped **before** resizing. Never resize the entire grid into a narrow strip.
- Preserve alpha by default. Use `--alpha-threshold 128` only when binary cutout alpha is intended. Do not threshold smoke or soft glows. Alpha snapping cannot remove an opaque generated background.

The helper rejects fractional cells, aspect-ratio changes, invalid indices, and source overwrites. Existing outputs need `--overwrite`. For a measurement error, fix the layout inputs; do not bypass validation by guessing crops or stretching cells.

## 4. Import, Configure, and Verify

Read [Blockbench and Minecraft delivery](references/blockbench-and-minecraft.md) when importing or producing runtime metadata. Discover the active format's `animated_textures`, `per_texture_uv_size`, and `texture_mcmeta` capabilities. Preserve the intended project and use available MCP tools/native dialogs.

Import the static strip with `create_texture` and assign it only to the intended elements. In formats supporting per-texture UV sizes, supply the established one-frame `uv_width=U`, `uv_height=V`; **never use the strip height as the one-frame UV height**. Other formats use project UV dimensions, so check their effect on existing textures before changing them. Configure timing through supported texture properties/animation UI; do not assume a nonexistent `set_flipbook` tool or pass undocumented parameters to `create_texture`.

Verify the following before delivery:

- PNG dimensions are exactly `W × H*N`; each full frame is correctly oriented and ordered, with stable anchors and appropriate alpha.
- `list_textures` reports `bitmap_size=[W,H*N]`, `frame_size=[W,H]`, and the intended `uv_size=[U,V]`. Verify the frame count using bitmap height / frame height.
- Inspect the APNG and several actual Blockbench frames, including last-to-first. Check clipping, temporal flicker, unwanted duplicates, shifting UV islands, spatial seams, and filtering at the intended viewing size. A static screenshot alone does not prove playback.
- Match the target metadata to the exported PNG and verify in the target runtime when available. Java uses `.png.mcmeta`; Bedrock **blocks** use `textures/flipbook_textures.json` plus the texture atlas binding. Bedrock entities require their own UV animation/material setup.

Deliver the strip, requested metadata, source prompt/sheet, conversion report, and optional preview with concise dimensions/count/timing. State which previews and runtime checks actually ran. For PBR animations, all channels need the same frame geometry/order/timing; process frames separately to avoid filters mixing adjacent frames.

© jasonjgardner · Apache-2.0 · jasonjgardner/blockbench-mcp-project

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set15

The whole set →
blockbench-hytale The blockbench-hytale skill walks an agent through Blockbench MCP tools for Hytale: formats, UVs, cube stretch, shading, attachments and animation. The Hytale Models plugin is required. CX Codex +1 930installs blockbench-plugins blockbench-plugins guides JavaScript plugin development for the Blockbench 3D editor, covering custom actions, UI dialogs, Vue panels, and undoable model edits. CX Codex +1 737installs blockbench-gpt-image-textures blockbench-gpt-image-textures generates Blockbench texture sheets, skins, and atlases with OpenAI GPT Image 2.5 on fal.ai using explicit UV layout prompts. CX Codex +1 294installs blockbench-new-model The blockbench-new-model skill turns a short brief into a Blockbench model, a render-ready Blender scene, and render files for stills or video. CX Codex +1 286installs blockbench-vanilla-textures blockbench-vanilla-textures pulls original Minecraft textures from Mojang's repository and applies them to Blockbench models. CX Codex +1 273installs blockbench-particles blockbench-particles adds Bedrock particle effects and bone locators to Blockbench models via MCP tools. Useful for fire, smoke, and magic VFX in Minecraft Bedrock and GeckoLib. CX Codex +1 259installs blockbench-albedo-to-pbr blockbench-albedo-to-pbr derives height, tangent-space normal, and packed MER maps from albedo textures for Blockbench PBR materials. CX Codex +1 248installs blockbench-substance blockbench-substance connects Blockbench to Adobe Substance 3D: renders .sbsar materials into PBR maps, bakes AO and ID passes from the model, paints it in Painter and packs the maps into texture_set.json. CX Codex +1 212installs

Project sponsors

Companies that keep this analytics open