Image Sheet/Sprite Helpers

This plugin (library) is designed to simplify loading & using texture sheets while maintaining backward compatibility if you should change tools at a later date.

The helpers support these tools and formats:

• Texture Packer - This is the number one PAID solution and if you can afford it, you should buy it now.
• ShoeBox - This is the number one FREE solution. It doesn't have a tone of features, but it is very easy to and guaranteed to be available in the future.
• Free Texture Packer 0.2.4 - This is a pretty good tool that I came across during the course of a discussion in the Corona Forums.
• When you use this tool, be sure to export using the format JSON (array) and I suggest you use the 'bestAreaFit' as the packing Method.
• Leshy Sprite Tool - This is another good tool that was introduced to me during a forums discussion.

Texture Packer is my personal go-to-tool, but if you are on a budget, any of the last three tools in the list above will suit most basic texture packing purposes and uses.

Don't see your favorite tool here? Contact me in the Corona Fourms. (See Posting Questions To Forums below.)

---

Basic Usage

A. Activate Plugin

First, purchase the plugin on Corona Marketplace to activate it.

B. Update build.settings

Second, ensure your build.settings file has this code in it:

settings =
{
    plugins =
    {
        ["plugin.texturePackerHelpers"] = { publisherId = "com.roaminggamer" },
    },      
}

C. Require Helpers Plugin

local helpers = require "plugin.texturePackerHelpers"

You may find it helpful to localize just the helper you are going to use.

Texture Packer

local helper = helpers.texturePacker

Shoe Box

local helper = helpers.shoeBox

Free Texture Packer 0.2.4

local helper = helpers.freeTexturePacker

Leshy Sprite Tool

local helper = helpers.leshy

---

Samples

You can find an example using all four tool ouput formats here:

https://github.com/roaminggamer/RG_FreeStuff/raw/master/myPluginSamples/texturepackerhelpers/sample.zip

---

Function API Docs

All four helpers have the same functions and take basically the same parameters. This list summarizes the functions. Additionally, you will find tool specific examples below.

IMPORTANT In some cases, these functions do a little work, in others they do more. The thing to keep in mind is that these helper functions all have the same interface. So, if you change your tools in the future, or if you mix content from multiple texture packers you can easily maintain your code.

Summaries

Function	Description	Applicable Parameters
getFrameDefinitions( params )	Returns table containing the tool specific sheet definition data.	baseDir, definition
newImageSheet( params )	Returns an image sheet based on the parameters you provid.	baseDir, definition, image
newImage( params )	Returns an image made using the speficied parameters.	baseDir, definition, image, sheet, frameIndex.
newSprite( params )	Returns an sprite made using the speficied parameters.	baseDir, definition, image, sheet, x, y, parent.

'Texture Packer' Examples

newImageSheet()

local slotsSheet = helper.newImageSheet( { definition = "slots", image = "slots.png" } )

index ↑

newImage()

Example 1 - Use Previously Loaded Sheet

local apple = helper.newImage( 
   {
      sheet  = slotsSheet, 
      frameIndex = 2, 
      parent = group,
      x = 100,
      y = 100
   } )

Example 2 - Load & Use Sheet On Demand

local grapes = helper.newImage( 
   { 
      definition = "slots", 
      image = "slots.png", 
      frameIndex = 3,
      parent = group, x = 100, y = 100 } )

index ↑

newSprite()

Example 1 - Single Sheet Sprite

local ninjaGirlIdleSequenceData =
{
   name        = "idle",
   start       = 1,
   count       = 10,
   time        = 1000,
   loopCount   = 0
}

local ninjaGirlIdleSprite = helper.newSprite( 
   { 
      definition = "ninjaGirlIdle",
      image = "ninjaGirlIdle.png",
      parent = group, x = cx, y = cy 
   }, ninjaGirlIdleSequenceData )

ninjaGirlIdleSprite:scale(0.5,0.5)
ninjaGirlIdleSprite:setSequence("idle")
ninjaGirlIdleSprite:play()

Example 2 - Multi-Sheet Sprites

-- 1. Get sheets from helper
local idleSheet = helper.newImageSheet( 
   {
      definition = "ninjaGirlIdle", 
      image = "ninjaGirlIdle.png" 
   } )

local attackSheet = helper.newImageSheet( 
   { 
      definition = "ninjaGirlAttack",
      image = "ninjaGirlAttack.png" 
   } )

-- 2. Write sequence data table (defines how animation plays)
local ninjaGirlSequenceData = 
   {
      { name = "idle", sheet = idleSheet, start = 1, count = 10, time = 1000, loopCount = 0 },
      { name= "attack", sheet = attackSheet, start = 1, count = 10, time = 500, loopCount = 1 },
   }

-- 3. Create sprite and star it
--
local ninjaGirlSprite = helper.newSprite( 
   { 
      sheet = idleSheet, 
      parent = group, 
      x = cx + 200, 
      y = cy 
   }, ninjaGirlSequenceData )

ninjaGirlSprite:setSequence("idle")
ninjaGirlSprite:play()
ninjaGirlSprite:scale(0.5,0.5)

index ↑

'ShoeBox' Examples

newImageSheet()

local slotsSheet = helper.newImageSheet( 
   {
      definition = "slots.sprites",  
      image = "slots/sprites.png" 
   } )

index ↑

newImage()

Example 1 - Use Previously Loaded Sheet

local apple = helper.newImage( 
   {
      sheet  = slotsSheet, 
      frameIndex = 2, 
      parent = group,
      x = 100,
      y = 100
   } )

Example 2 - Load & Use Sheet On Demand

local grapes = helper.newImage( 
   { 
      definition = "slots.sprites", 
      image = "slots/sprites.png", 
      frameIndex = 3,
      parent = group, x = 100, y = 100 } )

index ↑

newSprite()

Example 1 - Single Sheet Sprite

local ninjaGirlIdleSequenceData =
{
   name        = "idle",
   start       = 1,
   count       = 10,
   time        = 1000,
   loopCount   = 0
}

local ninjaGirlIdleSprite = helper.newSprite( 
   { 
      definition = "ninjaGirlIdle.sprites",
      image = "ninjaGirlIdle/sprites.png",
      parent = group, x = cx, y = cy 
   }, ninjaGirlIdleSequenceData )

ninjaGirlIdleSprite:scale(0.5,0.5)
ninjaGirlIdleSprite:setSequence("idle")
ninjaGirlIdleSprite:play()

Example 2 - Multi-Sheet Sprites

-- 1. Get sheets from helper
local idleSheet = helper.newImageSheet( 
   { 
      definition = "ninjaGirlIdle.sprites", 
      image = "ninjaGirlIdle/sprites.png" 
   } )

local attackSheet = helper.newImageSheet( 
   { 
      definition = "ninjaGirlAttack.sprites",
      image = "ninjaGirlAttack/sprites.png" 
   } )

-- 2. Write sequence data table (defines how animation plays)
local ninjaGirlSequenceData = 
   {
      { name = "idle", sheet = idleSheet, start = 1, count = 10, time = 1000, loopCount = 0 },
      { name= "attack", sheet = attackSheet, start = 1, count = 10, time = 500, loopCount = 1 },
   }

-- 3. Create sprite and star it
--
local ninjaGirlSprite = helper.newSprite( 
   { 
      sheet = idleSheet, 
      parent = group, 
      x = cx + 200, 
      y = cy 
   }, ninjaGirlSequenceData )

ninjaGirlSprite:setSequence("idle")
ninjaGirlSprite:play()
ninjaGirlSprite:scale(0.5,0.5)

index ↑

'Free Texture Packer 0.2.4' Examples

newImageSheet()

local slotsSheet = helper.newImageSheet( { definition = "slots.json", image = "slots.png" } )

index ↑

newImage()

Example 1 - Use Previously Loaded Sheet

local apple = helper.newImage( 
   {
      sheet  = slotsSheet, 
      frameIndex = 2, 
      parent = group,
      x = 100,
      y = 100
   } )

Example 2 - Load & Use Sheet On Demand

local grapes = helper.newImage( 
   { 
      definition = "slots.json", 
      image = "slots.png", 
      frameIndex = 3,
      parent = group, x = 100, y = 100 } )

index ↑

newSprite()

Example 1 - Single Sheet Sprite

local ninjaGirlIdleSequenceData =
{
   name        = "idle",
   start       = 1,
   count       = 10,
   time        = 1000,
   loopCount   = 0
}

local ninjaGirlIdleSprite = helper.newSprite( 
   { 
      definition = "ninjaGirlIdle.json",
      image = "ninjaGirlIdle.png",
      parent = group, x = cx, y = cy 
   }, ninjaGirlIdleSequenceData )

ninjaGirlIdleSprite:scale(0.5,0.5)
ninjaGirlIdleSprite:setSequence("idle")
ninjaGirlIdleSprite:play()

Example 2 - Multi-Sheet Sprites

-- 1. Get sheets from helper
local idleSheet = helper.newImageSheet( 
   { 
      definition = "ninjaGirlIdle.json", 
      image = "ninjaGirlIdle.png" 
   } )

local attackSheet = helper.newImageSheet( 
   { 
      definition = "ninjaGirlAttack.json",
      image = "ninjaGirlAttack.png" 
   } )

-- 2. Write sequence data table (defines how animation plays)
local ninjaGirlSequenceData = 
   {
      { name = "idle", sheet = idleSheet, start = 1, count = 10, time = 1000, loopCount = 0 },
      { name= "attack", sheet = attackSheet, start = 1, count = 10, time = 500, loopCount = 1 },
   }

-- 3. Create sprite and star it
--
local ninjaGirlSprite = helper.newSprite( 
   { 
      sheet = idleSheet, 
      parent = group, 
      x = cx + 200, 
      y = cy 
   }, ninjaGirlSequenceData )

ninjaGirlSprite:setSequence("idle")
ninjaGirlSprite:play()
ninjaGirlSprite:scale(0.5,0.5)

index ↑

'Leshy Sprite Tool' Examples

newImageSheet()

local slotsSheet = helper.newImageSheet( { definition = "slots.txt",  image = "slots.png" } )

index ↑

newImage()

Example 1 - Use Previously Loaded Sheet

local apple = helper.newImage( 
   {
      sheet  = slotsSheet, 
      frameIndex = 2, 
      parent = group,
      x = 100,
      y = 100
   } )

Example 2 - Load & Use Sheet On Demand

local grapes = helper.newImage( 
   { 
      definition = "slots.txt", 
      image = "slots.png", 
      frameIndex = 3,
      parent = group, x = 100, y = 100 } )

index ↑

newSprite()

Example 1 - Single Sheet Sprite

local ninjaGirlIdleSequenceData =
{
   name        = "idle",
   start       = 1,
   count       = 10,
   time        = 1000,
   loopCount   = 0
}

local ninjaGirlIdleSprite = helper.newSprite( 
   { 
      definition = "ninjaGirlIdle.txt",
      image = "ninjaGirlIdle.png",
      parent = group, x = cx, y = cy 
   }, ninjaGirlIdleSequenceData )

ninjaGirlIdleSprite:scale(0.5,0.5)
ninjaGirlIdleSprite:setSequence("idle")
ninjaGirlIdleSprite:play()

Example 2 - Multi-Sheet Sprites

-- 1. Get sheets from helper
local idleSheet = helper.newImageSheet( 
   { 
      definition = "ninjaGirlIdle.txt", 
      image = "ninjaGirlIdle.png" 
   } )

local attackSheet = helper.newImageSheet( 
   { 
      definition = "ninjaGirlAttack.txt",
      image = "ninjaGirlAttack.png" 
   } )

-- 2. Write sequence data table (defines how animation plays)
local ninjaGirlSequenceData = 
   {
      { name = "idle", sheet = idleSheet, start = 1, count = 10, time = 1000, loopCount = 0 },
      { name= "attack", sheet = attackSheet, start = 1, count = 10, time = 500, loopCount = 1 },
   }

-- 3. Create sprite and star it
--
local ninjaGirlSprite = helper.newSprite( 
   { 
      sheet = idleSheet, 
      parent = group, 
      x = cx + 200, 
      y = cy 
   }, ninjaGirlSequenceData )

ninjaGirlSprite:setSequence("idle")
ninjaGirlSprite:play()
ninjaGirlSprite:scale(0.5,0.5)

index ↑

Tool Specific Export Settings

Here are some videos showing how to use the four different tools with 'Texture Packer Helpers Plugin'.

Exporting Sprite Sheets with Texture Packer

Assuming you have installed Texture Packer, run the tool and follow these steps:

1. Select textures you want in sheet and drag them onto 'the tool'.
2. Click 'Publish Sprite Sheet'
3. Set 'Save as Type' to 'Corona SDK lua file' and five the file a name (ex: ninjaGirlIdle.lua)
4. Click 'Save'.

This will produce two files:

• ninjaGirlIdle.lua
• ninjaGirlIdle.png

Exporting Sprite Sheets with ShoeBox

Assuming you have installed ShoeBox and Adobe Air, run ShoeBox and follow these steps:

1. Select textures you want in sheet and drag them onto 'Sprite Sheet' area of 'Sprites Tab'.
2. After the sprites are processed a window will pop up showing them. Click the 'settings' button.
3. In the 'Sprite Sheet Settings' Dialog that pops up, select 'Corona SDK' as the template.
4. On the same dialog, make sure 'Tex Power Of Two' is false, then click Apply.
5. The tool will re-process the sprites. When it is done, click 'Save' in the preview window.

This will produce two files (in same folder as original images):

• sprites.lua
• sprites.png

Exporting Sprite Sheets with Free Texture Packer 0.2.4

Click the link in the title above and it will open the tool in your browser. Then follow these steps

1. Select textures you want in sheet and drag them onto grey box titled "or drag'n'drop images here".
2. Use similar settings shown for step two below, then click 'Export'.
   • Texture name: and File name: set to same value (Ex: ninjaGirlIdle)
   • Format: must be set to JSON (array)
   • Allow rotation: must be clear (false).
   • Packer: should be MaxRectsBin
   • Method: should be BestAreaFit

This will produce two files in a zip file (ninjaGirlIdle.zip):

• ninjaGirlIdle.json
• ninjaGirlIdle.png

Exporting Sprite Sheets with Leshy Sprite Tool

Click the link in the title above and it will open the tool in your browser. Then follow these steps

1. Select textures you want in sheet and drag them onto grey box titled "Drag & Drop Image Files Here".
2. Select 'Text' as save 'Sprite Map' save format.
3. Choose file name for the 'Sprite Sheet' and the 'Sprite Map' that match. Ex: ninjaGirlIdle
4. Click Save buttons for both 'Sprite Sheet' and 'Sprite Map'.

This will produce two files:

• ninjaGirlIdle.txt
• ninjaGirlIdle.png

Posting Questions To The Forums

I will be providing help (exclusively) through the Corona SDK Forums. (Sorry: Direct e-mails and private messages will not be answered.)

When posting a question in the forums, be sure to follow these guidelines:

1. Post to this forum: https://forums.coronalabs.com/forum/553-other-third-party-tools/
2. Make sure the title starts with: Texture Packers Helper and includes a short and meaninful name for the the problem.
3. In the body of the post give me clear, concise, and precise description or question.

~ The Roaming Gamer

---

Copyright © Roaming Gamer, LLC. 2008-2017; All Rights Reserved