High-Level Functions

You will find bellow the high-level function to easily generate tilesets and tilemaps.

Generating Tilesets

img2gb.generate_tileset(input_images, output_c=None, output_h=None, output_image=None, name='TILESET', dedup=False, alternative_palette=False, sprite8x16=False)[source]

Function that generates tileset’s C file, C header and image from an input image.

Parameters:

  • input_images (PIL.Image.Image|list) – The input image to generate the tileset from.

  • output_c (file) – A file-like object where the C code will be generated (None to not generate C code).

  • output_h (file) – A file-like object where the C header (.h) code will be generated (None to not generate C header code).

  • output_image (file) –

    A file-like object where the image representing the tileset will be generated (None to not generate the image).

    Note

    The file must be openend in binary mode (open("file", "wb")) or you must be using a binary-compatible file-like object, like a io.BytesIO.

  • name (str) – The name of the tileset (will be used in the generated code, default = "TILESET")

  • dedup (bool) – Deduplicate the tiles of the tileset (default = False)

  • alternative_palette (bool) – Use the sprite’s alternative palette (inverted colors, default = False)

  • sprite8x16 (bool) – Rearrange the tiles to be used in 8x16 sprites (default = False).

Example using files:

from PIL import Image
import img2gb

image = Image.open("./my_tileset.png")
c_file = open("example.c", "w")
h_file = open("example.h", "w")
image_file = open("example.png", "wb")

img2gb.generate_tileset(
    [image],
    output_c=c_file,
    output_h=h_file,
    output_image=image_file,
    dedup=True)

c_file.close()
h_file.close()
image_file.close()

Example using file-like objects:

from io import StringIO, BytesIO
from PIL import Image
import img2gb

image = Image.open("./my_tileset.png")
c_code_io = StringIO()
h_code_io = StringIO()
output_image = BytesIO()

img2gb.generate_tileset(
    [image],
    output_c=c_code_io,
    output_h=h_code_io,
    output_image=output_image,
    dedup=True)

# Print the C code for the example:
c_code_io.seek(0)
c_code = c_code_io.read()
print(c_code)

Generating Tilemaps

img2gb.generate_tilemap(input_tileset, input_tilemap_image, output_c=None, output_h=None, name='TILEMAP', offset=0, missing='error', replace=0)[source]

Function that generates tilemap’s C file and C header from an input tileset and image.

Parameters:

  • input_tileset (PIL.Image.Image) – The tileset that contains the tiles used in the tilemap.

  • input_tilemap_image (PIL.Image.Image) – An image that represents the tilemap (its size must be a multiple of 8 and 256x256px maximum).

  • output_c (file) – A file-like object where the C code will be generated (None to not generate C code).

  • output_h (file) – A file-like object where the C header (.h) code will be generated (None to not generate C header code).

  • name (str) – The name of the tilemap (will be used in the generated code, default = "TILEMAP").

  • offset (int) – Offset where the tileset starts (useful only of you will load the given tileset at a place different from 0 in the GameBoy video memeory).

  • missing (string) –

    Action to do if a tile of the tilemap is missing from the tileset:

    • "error" (default): raise an error,

    • "replace": replace the missing tile by an other one (see replace option).

  • replace (int) – The id of the replacement tile when missing="replace".

Example:

from io import BytesIO
from PIL import Image
import img2gb

image = Image.open("./my_tilemap.png")

# Generate the tileset image from the tilemap image
tileset_io = BytesIO()
img2gb.generate_tileset(
    [image],
    output_image=tileset_io,
    dedup=True)
tileset_io.seek(0)

# Generate the tilemap
tileset_image = Image.open(tileset_io)
img2gb.generate_tilemap(
    tileset_image,
    image,
    output_c=open("tilemap.c", "w"),
    output_h=open("tilemap.h", "w"))