☰
Navigation :

Working With Spritesheet

Working With Spritesheet

ATTENTION: For a full class on how to use different types of sprite sheets in Kwik, check the FREE lesson from the Official Training here.

Sprite sheets are commonly used in games and storybooks. A sheet is basically an image file with a bunch of images, representing one (or several) animation sequence. To learn more why to use them, I strongly recommend the amazing video made by Andreas Löw, from Code and Web, creator of Texture Packer (more on that below) and Physics Editor, two great tools for the Kwik user arsenal:

Same size frames sheet

Two kinds of sheets can be created. A same size frame sheet contains all elements (frames) with the same dimensions. In the example below, there are 8 cats with the same size of 512×256 pixels, making the sprite sheet file size of 1024×1024 pixels.

It is a good practice to set your frames multiples of 8 for better texture memory performance. For example, instead of creating a 15×15 pixels frame, set the canvas for 16×16 pixels.

Optimized frames sheet

An optimized frame sheet contains all elements (frames) in different positions, to avoid any empty space (saving memory). In the example below, you can see several images mixed, making the sprite sheet file size of 476×496 pixels.

The example was created with Texture Packer. Using this software is relatively simple. You drag all the desired images there and it will create an optimized file for Solar2D (Corona SDK) image sheet.

Texture packer Output files, you may find Kwik(image sheet) but it is for Kwik3. Not use it for Kwik4

Working with sprite sheets in a Kwik project

I will not spend much time here because there is a place to learn it: Sprite Sheet Replacement is the online documentation for this feature. The basis are:

if you are using a same size frame sheet created by yourself

draw an empty rectangle in a layer (you may use a real image but it may have the exact size of each frame in your sprite sheet file). Please notice that if you are using a shape, Photoshop will usually add the pixels for the borders too.

For example, a 400×400 rectangle with border of 2 points will end up being an image of 402×402 pixels)

Enter the location of the sprite sheet file (usually a .png file) and enter the dimensions of each frame and the full size of the sheet file, under the Manual entry… panel. You need to enter also all other info (Start frame, Frame Count, …)

You find a spritesheet replacement in Page 13 of Action Sample project.

b) if you are using an optimized file from Texture Packer

for instance, you have 4 frames in one sheet and each frame is just one frame without animation. this case , the sequences will be like this

and so on.

    frames = {

        {
            -- bird
            x=2,
            y=2,
            width=191,
            height=222,

            sourceX = 1,
            sourceY = 1,
            sourceWidth = 192,
            sourceHeight = 223
        },
        {
            -- cat
            x=195,
            y=2,
            width=103,
            height=158,

            sourceX = 1,
            sourceY = 0,
            sourceWidth = 104,
            sourceHeight = 158
        },
        {
            -- rabit
            x=300,
            y=154,
            width=163,
            height=98,

            sourceX = 0,
            sourceY = 1,
            sourceWidth = 164,
            sourceHeight = 99
        },
        {
            -- snail
            x=300,
            y=2,
            width=192,
            height=150,

            sourceX = 1,
            sourceY = 1,
            sourceWidth = 193,
            sourceHeight = 151
        },
    },

Note

There is a nice feature in Kwik4 to output png files from a layer group.

Settings > Publish

Each png file is outputted to build4/assets/images/pXX/ where XX is the page number. And you can use it to create spritsheet with TexturePacker.

Don’t forget to delete these files when building app for device. It is redundant files.

As Kwik4 supports current texture packer lua file which returns SheetInfo table. You just specify the exported lua file from texture packer.

You can create sheet image file from build4/assets/images/*.png which are generated with publish. create sheet image sheet from them and save it to a folder. (I don’t recommend to save it to under build4. create your own folder under the project folder and save it them, for instance, myAssets/)

If ‘build4/assets/images/’ folder contains @2x.png files, you need to pack image sheet for @2x.png files too. It is used at runtime automatically @2x is loaded according to the screen resolution. Please export @2x png to the same folder. the lua file of @2x is not necessary.

Kwik Panel > Layer Replacements > Sprite sheet replacement, you can set page1_sheet.png and page1_sheet.lua without @2x. you don’t need to make the replacement for @2x.png in the panel.