(Mike McRoberts) #1

What tools are people using to convert the sprite plus mask to be used with the sprites.drawPlusMask command please?



I didn’t have the time yet to write a manual but:


for the sprites converter you have to provide an image:

  • png
  • name_frameHeightxframewidth.png (test_16x16.png)
  • make sure the sprites are vertically in 1 column, first frame is the top frame

like this example png:

(Mike McRoberts) #3

OK this is great for creating separate files for the Sprite and the mask but how about the combined file for using sprites.drawPlusMask ?

I believe the bytes for that have to be in pairs (1 sprite/1 mask) (2 sprite/2 mask) etc

(Gavin Atkin) #4

I created my own tool for converting images for the various formats. It is windows only. A little slow when loading the images, but it gets the job done. You’re welcome to use it. Completely without warranty, can’t guarantee it is completely bug free. Saving as a “Sprite” is the format you want to use for drawPlusMask.

(Mike McRoberts) #5

Thanks for this but how are the sprite and masks meant to be formatted? I have a sprite and its mask as PNG’s but your program only allows one thing to be loaded at a time. Do they have to be together in the same file? If so, where do they go? Next to each other, above/below each other?


Make 1 file were transparant pixels are the pixels not masked.

the sprite tool creates 3 codes:

  • sprite
  • mask
  • sprite and mask combined

(Mike McRoberts) #7

Ahh I see. Thanks. I’ll give it a try.

(Josh Goebel) #8

I wrote the original tools for this also:

(Nicolas Mougin) #9

I wrote a very lightweight utility (windows .exe) that takes any image as input (png, bmp, gif, jpg, etc.) - or a folder full of images - and saves the array(s) for use with drawPlusMask to a header file.

Images do not need to have a width multiple of 8, it can be anything, my program will automatically add the padding. Images need to have black pixels, white pixels, and pixels in a third color (any color will do: can be transparent for pngs, but can also be pink, green whatever). This third color is used as the transparent mask data.

I checked the output was fine, but I did not test loading resulting array on an actual Arduboy, so actual tests and feedback would be very welcome.

Utility can be downloaded here: http://mougino.free.fr/zip/drawPlusMask_converter.zip
Just unzip it anywhere on your computer and drag and drop an image or a folder of images on it.


(Nicolas Mougin) #10

I tested the utility on my Arduboy and it turns out the conversion fails: bitmaps drawn with drawBitmapPlusMask are displayed as garbage.

I first used a method that appended transparent bits after every row of pixels to make it a multiple of 8 (basically every row was made to fit in complete bytes, “Case 1” in the illustration below).

Missing documentation on how conversion is made, I then tried to fill every byte with pixels from different rows, not stopping if a row width was not a multiple of 8 (“Case 2” in the illustration). This still fails :frowning: I still see garbage…

Where can I find a documentation of how bitmaps need to be dumped to array for use with drawBitmapPlusMask ?

(Mike McRoberts) #11

Why Ruby? It’s something most people would not have installed on their PC or Mac. It’s the reason why i’ve not used this utility yet - having to install a whole language just to compile this utility.


for people who don’t want to install, we made a “web app” for:

images: https://teamarg.github.io/arduboy-image-converter/

tilesheets: https://teamarg.github.io/arduboy-tile-converter/

spritesheets: https://teamarg.github.io/arduboy-sprite-converter/

But I really need to write the manuals :slight_smile:

for the sheets:

  • order your sprites/tiles vertically
  • use multiples of 8 for size to be sure
  • use transparency for masking
  • naming is name_16x16.png (size of 1 sprite/tile)
  • drop your file on the page (probably twice )
  • copy paste the code you get

(Mike McRoberts) #13

These are the tools I have been using the most as they work very well.

but yes, you do need to write those manuals :stuck_out_tongue:

(Josh Goebel) #14

It’s actually pre-installed on Mac and very easy to install on most *nix via package manager, and it’s what I use everyday for work - so it’s a familiar tool.

(Nicolas Mougin) #15

I don’t manage to have proper encoded arrays, even with JO3RI’s online tools.

I am trying to encode the spritesheets (png) at http://mougino.free.fr/tmp/ArduWB3_bitmaps.zip

I have put the resulting arrays in “HUMAN.h”, full project available at http://mougino.free.fr/tmp/ArduWB3.zip

Part of the sprites appear to be good (typically top of first frame) but most of the rest is garbage.

Can someone tell me what I am doing wrong ?


@mougino your png’s are wrong

make a separate sprite for the feet, make sure the height is a multiple of 8 add lines of transparent pixels at the bottom of each frame (width size doesn’t matter) and have 2 draw functions, one for the head, the other one for the feet (which you’ll animate)

So even if your feet are 14 pixels heigh, you have to make each frame 16 pixels heigh, just add 2 lines of transparent pixels under the feet, for each frame.

(Nicolas Mougin) #17

Thanks JO3RI! It’s definitely better, but there are still strange stuff going on, like the “HUMANLDS_32x16” sprite (LDS = Left + Down (crouching) + Sword), its dimensions are perfect multiples of 8, but when displayed with drawBitmapPlusMask() the bottom half (lower 8 rows of pixels) looks shifted by 1 or 2 pixels towards the left… very odd :sweat:

BTW I answer myself on my question a few posts back: I found the drawBitmapPlusMask() needs arrays that are composed of image pixels following this scheme:

So indeed it is better for an image height to be a multiple of 8, but it doesn’t matter for the width to be a multiple of 8.

(Nicolas Mougin) #18

I updated the utility at http://mougino.free.fr/zip/drawPlusMask_converter.zip it should now work better.