nichnet/gbtd-sprite

Encodes image files as hexidecimal data for GBDK and decodes hexadecimal data generated by GBTD into PNG image files.

GBTD Sprite Encoder/Decoder

This tool generates hexadecimal sprite data for GBDK. Use it to encode image files as hexidecimal data and decode hexadecimal data generated by GBTD into PNG image files.

Explanation

There is a full explanation on my blog, here.

GBDK interprets sprite data generated by GBTD by assigning every pixel of a sprite image, 2 bits. These 2 bits determine the index for the color used in the assigned color palette.

The color is determined like so:

Bit 1	Bit 2	Color Palette Index	DMG1 Palette RGB
0	0	0	255, 255, 255
1	0	1	192, 192, 192
0	1	2	128, 128, 128
1	1	3	0, 0, 0

The data for these sprites is represented in the form of an array containing hexadecimal values (a hex value contains 8 bits - 1 byte). Thus, a byte represents a single row of 8 pixels. As there are 4 colors in the palette 2 bytes are required.

For example the data array may contain: 0xBE, 0xD2,..., which in binary and finally as a color index, is interpreted as:

B1	0xBE	1	0	1	1	1	1	1	0
B2	0xD2	1	1	0	1	0	0	1	0
Color Palette Index	0-3	3	2	1	3	1	1	3	0

As mentioned above, this is a single row of 8 pixels and in this case, the colors are black, dark, light, black, etc... (in a standard GameBoy color palette).

Every 8x8 pixels (16 bytes) is a `quadrant` .

Width	Height	Pixels	Quadrants
8	8	64	1
8	16	128	2
16	16	256	4
32	32	1024	16

The quadrants are organised in the following order:

8x8 (1 quadrant)

0

8x16 (2 quadrants)

0
1

16x16 (4 quadrants)

0	2
1	3

32x32 (16 quadrants)

0	2	8	10
1	3	9	11
4	6	12	14
5	7	13	15

Usage

Example Data

The tool comes packed with some example data. You can generate the image files from this data by running the following, and supplying one of the keys names below.

py gbtdimg.py -d [example data key]

Key	Name	Width	Height	Result
t88	Heart	8	8
t816	Sword	8	16
t1616	Link	16	16
t3232	Red	32	32

Decoding Hexidecimal Data to Image Files (PNG)

py gbtdimg.py -d [exported image name] [data]

#comma seperated or space seperated values is okay.
#py gbtdimg.py -d MySprite 0x6C,0x6C,0xFE,0x92,0xD6,0xAA,0xC6,0xBA,0x6C,0x54,0x38,0x28,0x10,0x10,0x00,0x00
#py gbtdimg.py -d MySprite 0x6C 0x6C 0xFE 0x92 0xD6 0xAA 0xC6 0xBA 0x6C 0x54 0x38 0x28 0x10 0x10 0x00 0x00

The image will be generated inside an export folder.

Encoding Images as Hexidecimal Data

Images to encode should only be 8x8, 8x16, 16x16, or 32x32 in size, and contain the RGB values mentioned previously above.

py gbtdimg.py -e [image path] [label name] 
#py gbtdimg.py -e path/to/heart.png MyHeartLabel 

The result is a C source and header file containing the hex data, e.g.:

0x6C,0x6C,0xFE,0x92,0xD6,0xAA,0xC6,0xBA,
0x6C,0x54,0x38,0x28,0x10,0x10,0x00,0x00

Issues and Concerns

Strangely, GBDK reads the quadrants (mentioned above) in an odd order.

GBTD does have export compression options, so perhaps the ordering is related to that.

Regardless, for easier interpretation, I would expect uncompressed data to be ordered horiztonally and then vertically like this:

32x32 (16 quadrants)

0	1	2	3
4	5	6	7
8	9	10	11
12	13	14	15

As a result there is some spaghetti code which organises the data appropriately for encoding and decoding until I research into this more.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

GNU General Public License v3.0