create_sprite_atlas

Combine multiple images into a single sprite atlas or spritesheet for game development. Specify columns, padding, and save options to organize assets efficiently.

Instructions

Combine multiple images into a sprite atlas/spritesheet.

Args:
    images_base64: List of base64 encoded images
    columns: Number of columns in the atlas
    padding: Padding between sprites in pixels
    save_to_file: Whether to save atlas to disk
    filename: Custom filename for the atlas

Returns:
    JSON with the combined atlas as base64

Input Schema

TableJSON Schema

Name	Required	Description	Default
`images_base64`	Yes
`columns`	No
`padding`	No
`save_to_file`	No
`filename`	No

Implementation Reference

server/main.py:870-909 (handler)

The primary handler function for the 'create_sprite_atlas' MCP tool. It decodes input base64 images, calls the create_spritesheet helper to generate the atlas, encodes it back to base64, and returns a JSON response. Also handles optional file saving. The @mcp.tool() decorator registers it with the MCP server.

@mcp.tool()
async def create_sprite_atlas(
    images_base64: List[str],
    columns: int = 4,
    padding: int = 0,
    save_to_file: bool = False,
    filename: Optional[str] = None
) -> str:
    """Combine multiple images into a sprite atlas/spritesheet.
    
    Args:
        images_base64: List of base64 encoded images
        columns: Number of columns in the atlas
        padding: Padding between sprites in pixels
        save_to_file: Whether to save atlas to disk
        filename: Custom filename for the atlas
    
    Returns:
        JSON with the combined atlas as base64
    """
    import base64
    images = [base64.b64decode(img) for img in images_base64]
    
    atlas_bytes = create_spritesheet(images, columns=columns, padding=padding)
    
    result = {
        "success": True,
        "image_base64": image_to_base64(atlas_bytes),
        "sprite_count": len(images),
        "columns": columns
    }
    
    if save_to_file:
        output_dir = ensure_directory(OUTPUT_DIR / "atlases")
        fname = filename or generate_filename(prefix="atlas")
        file_path = output_dir / fname
        file_path.write_bytes(atlas_bytes)
        result["file_path"] = str(file_path)
    
    return json.dumps(result, indent=2)

server/utils.py:56-89 (helper)

Supporting utility function that implements the core spritesheet creation logic using PIL. Arranges input images in a grid layout with optional padding and returns the combined PNG bytes. Called by the tool handler.

def create_spritesheet(
    images: List[bytes],
    columns: int = 4,
    padding: int = 0
) -> bytes:
    """Create a spritesheet from multiple images."""
    if not images:
        raise ValueError("No images provided")
    
    # Load all images
    pil_images = [Image.open(BytesIO(img)) for img in images]
    
    # Get dimensions (assume all same size)
    sprite_width = pil_images[0].width
    sprite_height = pil_images[0].height
    
    # Calculate sheet dimensions
    rows = (len(pil_images) + columns - 1) // columns
    sheet_width = columns * sprite_width + (columns - 1) * padding
    sheet_height = rows * sprite_height + (rows - 1) * padding
    
    # Create spritesheet
    sheet = Image.new("RGBA", (sheet_width, sheet_height), (0, 0, 0, 0))
    
    for i, img in enumerate(pil_images):
        row = i // columns
        col = i % columns
        x = col * (sprite_width + padding)
        y = row * (sprite_height + padding)
        sheet.paste(img, (x, y))
    
    buffer = BytesIO()
    sheet.save(buffer, format="PNG")
    return buffer.getvalue()

ComfyMCP Studio