Dynamic Content Scaling for Corona SDK

Andreas Löw Get Sourcecode from GitHub

This is an update of the tutorial about CoronaSDK's image sheet api.

TexturePacker 3.0.0b16 comes with 2 new features which help Corona developers to speed up their development.

The new AutoSD feature

All you need is your sprites - preferably at the biggest scaling factor available. The reason for this is because scaling big images down gives you good quality - while scaling small images up usually does no good job.

Add your sprites to TexturePacker as your usually do.

Press the AutoSD's cog button - this gives you a popup window which should look like in the screenshot:

TexturePacker AutoSD settings
  1. Presets - here you find already defined presets for scaling down by 50% for retina display and another variant scaling down 50% and 25% for Retina iPad. After selecting your preset press Apply
  2. Main Extension - this is the part from the main file name that is replaced with a scaling specific extension.
  3. The variation list - It's empty here. Press the + button to add a new scaling variation.
  4. Force identical layout - this will keep all scaled variation layouts identical - exactly what we need for CoronaSDK

After pressing the + or applying a preset the list will contain some entries:

TexturePacker AutoSD settings for Corona @4x/@2x

A new box will popup for each variation you create.

  1. Scale - this is the scale factor for this variation.
  2. Extension - the extension for this variation. It will replace the Main Extension in the file names for textures and data. E.g. if your main file names are sheet@4x.png and sheet@4x.lua you need to set Main Extension to @4x. Adding @2x here will write the scaled files as sheet@2x.png and sheet@2x.lua.
  3. Max. Texture Size - the texture limits for this variation (not required with force identical layout)
  4. Accept fractional values - TexturePacker calculates a kind of base unit size - see Common factor which is a number that can be divided by all scaling factors without creating floating point numbers and ending up in sub pixel rendering. If you have a bad combination of scaling factors no reasonable common factor might be found. Check this box to exclude this scaling factor from the calculation.

This setup will do the following, assuming that your main sprite sheets are called sheet@4x.png and sheet@4x.lua

Scale factor Texture Name Data Name
1.0 sheet@4x.png sheet@4x.plist
0.5 sheet@2x.png sheet@2x.plist
0.25 sheet.png sheet.plist

With these settings the Common factor is 4. This influences padding and other features. Padding in the main settings are now handled as minimum values which are ensured across all variations.

The consequence is that if you set padding to 2px it will have 2px in the scale mode 0.25 - but in scale mode 1.0 (which is the view that you usually see) it will be 8px.

Additionally all your sprites are now padded with transparent pixels to fit the Common factor. E.g. if you have a sprite which is 61x75px it will be extended to 64x76px. With this the sprite can be scaled down to 32x38px and 16x19px. A sprite with the original size of would end up with 16.25x18.75px which would cause sub pixel rendering.

Corona SDK image sheets

This new feature does not leave you much to do in Corona SDK.

First setup the content scaling:

application = 
{
    content = 
    { 
        width = 320,
        height = 480, 
        scale = "zoomEven",
        
        imageSuffix =
        {
            ["@2x"] = 2,
            ["@4x"] = 4
        },
    }
}

This will automatically select the right scaled sprite sheet (using @2x and @4x).

With that simply load the sprite sheet and let CoronaSDK do the work:

local sheetInfo = require("spritesheet") -- lua file that TexturePacker published
local myImageSheet = graphics.newImageSheet( 
    "spritesheet.png", sheetInfo:getSheet() 
)
local background = display.newImage( 
    myImageSheet , sheetInfo:getFrameIndex("bkg_cor")
)
local hamburger1 = display.newImage( 
    myImageSheet , sheetInfo:getFrameIndex("hamburger")
)
hamburger1.x = 150
hamburger1.y = 61

Did you like the tutorial? Please share!

Source code available for download

The source code is available on GitHub. Clone it using git:

git clone https://github.com/CodeAndWeb/TexturePacker-Corona-ImageSheets.git

or download one of the archives:
TexturePacker-Corona-ImageSheets.zip TexturePacker-Corona-ImageSheets.tar.gz