One of the new plugins handles the compression and un-compression of files using the popular zip algorithm. For anybody who’s unfamiliar with zip files, the most common usage is when you need to group several related files into a “package” so it’s easier to move them around and share them with others. For example, if you contract a set of artwork from a designer, he/she can compress them into a zip archive and send them via email, Dropbox, etc. All of the artwork will be contained in that one file with the .zip extension, and when you open it locally, the file will “unzip” and all of the files will be available to you, exactly as the designer intended. Another use of zip files is to compress one large file into a smaller overall .zip file. The format and type of the original file will dictate the amount of compression achieved, but in virtually every instance, you’ll save valuable storage space.

Why is this important to mobile app developers? For one, you gain the ability to expand your app’s contents. You can create a zip file containing expansion art and sounds, download it into your app, unzip it, and use those assets. Secondly, you can now produce zip files which you can upload to web servers for distribution.

In today’s tutorial, let’s examine how to download a zip file from a web server, unzip the contents, and show a list of the files within.

Using Corona Plugins

Corona Plugins are “managed” from the build.settings file in your core project directory. This makes it easy to add just the specific plugins you need for an app, ultimately resulting in a lighter compiled binary.

To use a plugin, simply add the plugins table within settings and configure the zip plugin within:

settings =
{
   orientation =
   {
      default = "portrait",
      supported = { "portrait", "portraitUpsideDown" },
   },
   plugins = 
   {
      ["plugin.zip"] =
      {
         publisherId = "com.coronalabs",
      },
   },
}

Next, in your main project code, you must require the plugin, similar to how you’d require a core Corona library or external Lua module.

local zip = require( "plugin.zip" )

That’s it! Now you’re ready to use the zip plugin. Note that when you run a project in the Corona Simulator that requires a plugin, you’ll be prompted to download the plugin; this only happens once, when you first use the plugin.

Implementing .zip in Code

Like many API calls in Corona, a callback function is required so that you can determine when the process is complete and then take the appropriate action.

local function zipListener( event )
   if ( event.isError ) then 
      print( "Unzip error" )
   else
      print( "event.name:" .. event.name )
      print( "event.type:" .. event.type )
      if ( event.response and type(event.response) == "table" ) then
         for i = 1, #event.response do
            print( event.response[i] )
         end
      end    
   end
end

Now, let’s use use the network.download API call to retrieve the zip file from a remote server and, in its callback listener, initiate the unzip process. The callback function will list all files that are successfully uncompressed.

local function networkListener( event )

   if ( event.isError ) then
      print( "Network error - download failed" )
   elseif ( event.phase == "began" ) then
      print( "Progress Phase: began" )
   elseif ( event.phase == "ended" ) then
      if ( math.floor(event.status/100) > 3 ) then
         print( "Network error - download failed", event.status )
         --NOTE: 404 errors (file not found) is actually a successful return,
         --though you did not get a file, so trap for that
      else

         local options = {
            zipFile = event.response.filename,
            zipBaseDir = event.response.baseDirectory,
            dstBaseDir = system.DocumentsDirectory,
            listener = zipListener,
         }

         zip.uncompress( options )
      end
   end
end

local params = {}
params.progress = true
local URL = "http://omnigeekmedia.com/coronasdk/test.zip"
network.download( URL, "GET", networkListener, params, "test.zip", system.TemporaryDirectory )

Let’s follow through the process step by step:

1. When network.download finishes, the networkListener function is called.
2. After checking for and catching possible error conditions, create a table of options to pass to the zip plugin. The zipFile and zipBaseDir will be given to you in the network.download “event” table. Optionally, you can specify whether to unzip all files or just some files — see the documentation for details.
3. Provide the destination directory as dstBaseDir and the zipListener function that you wrote (above) will handle the rest!

In Summary…

As you can see, using the zip plugin is simple! Just include the plugin in your build.settings file, set up a basic callback function, and pass a table of options to the plugin. For full details and instructions on how to use the zip.compress() and zip.list() APIs, please review the following documentation:

Plugin Documentation (zip.*) — http://docs.coronalabs.com/daily/plugin/zip/

Finally, before we conclude today’s tutorial, there are just a few more important points:

1. Currently, the zip plugin is only available to Corona SDK Pro subscribers using Daily Build #1115 and above.
2. zip files can contain executable code which can be problematic, in particular on Windows machines. Please do not open zip files from unknown sources, and keep your virus scanning software up-to-date.
3. On iOS, since you are downloading easily retrievable data, Apple expects those files to go into the system.CachesDirectory.
4. On Android, remember to enable Internet access as detailed here.

Questions or comments? Please provide your input below.

• Sponsorpay
• Tap for Tap
• inneractive
• Green Throttle
• Carrot

It’s great partners like these that enable Corona developers to access the best new functionality and 3rd party services. In particular, today’s batch span a wide variety of services from app advertising to cross-promotion and value-exchange ads, from social campaigns to game controllers.

You can see more information at the Corona Plugin Directory. You’ll notice a “Docs” link below each partner that’s got all the technical docs you’ll need to use the plugin in your app. In the coming days, you will see more info from these partners about their services and why you should use them.

Just keep in mind that, for now, you need access to daily builds to use these plugins.

This is just the first wave. We have more partners coming in the next few weeks, adding to the growing list of additional features and services you’ll want to use in your apps. As you can see, Corona plugins are going to play an increasingly important role in your apps.

Corona core gets lighter

Another things that is happening this week is that the core Corona engine is about to get lighter.

Last week, I talked about our plans to move certain services into plugins that currently reside in the core Corona engine.

That move is happening this week. In tomorrow’s daily build (after 1115), the following services will be moved into plugins:

• iAds: iOS
• InMobi: iOS + Android
• Inneractive: Android

This will make the core even smaller than it already is.

We’ll also be rolling out a new “Plugins” section in our daily build docs where you can get details on the ‘build.settings’ changes needed to use those plugins in your device builds. Again, this will start in tomorrow’s daily builds.

Plugins for Enterprise

Two final notes for Corona Enterprise users.

First, we plan to make plugin binaries available to you soon. These plugins will probably be available as a separate download. That’s because plugins will generally be the same across daily builds.

Second, if you are using Corona Enterprise and you require InMobi or inneractive, the corresponding plugin binaries will not be available immediately. So if you use those services, stay on 1115 or earlier for now. These will be available in the separate download I mentioned above.

We’re going to have more plugin announcements in the coming weeks, but after Memorial Day, what I’d like to get back to in the weekly updates is more eye candy. With that in mind, if you have a favorite filter effect, let me know!

Oh, and if you happen to be in the Big Apple today, we’re exhibiting at AppNation, hosting a panel on app monetization, and also crashing the Corona NYC meetup to share the latest and greatest.

This week we hung out with Ed Maurina, Gerald Bailey, Jesse Warden, Matthew Chapman, and Richard Harris to discuss memory management in Corona SDK. Ed did an excellent job of explaining the sample app he created after one of our previous Hangouts where we discussed Storyboard. His app demonstrates how memory is affected when objects are set to nil at various stages of development. Ed agreed to post his code on GitHub, so we’ll post a link to his code once that is available. We also talked about the announcements at Google IO, the ongoing Dilbert contest, and COPPA Privacy Policies.

Corona Labs T-Shirt Winner

Congratulations to Theo Rushin, Jr. for winning this week’s Corona Labs’ t-shirt. For your chance to win, follow Corona Geek on Twitter and Facebook, and complete the Corona Geek giveaway form.

Thank you for watching, we’ll see you on next week’s Corona Geek hangout!

Remember To Subscribe

• Download the Corona Geek podcast on iTunes
• Listen to Corona Geek on Stitcher
• Subscribe to Corona Geek on YouTube

In Tomb Breaker, your goal is to clear as many gem tiles as possible by swiping across tiles to make chains. The more tiles you clear in one swipe, the more points you’re awarded. As you collect gems and purchase game powerups, you can also score breaking crossovers, clears, and combos. And, if you’re feeling competitive, you can challenge friends on Game Center or on Facebook, or you can play against your own high score.

This catchy puzzle game is available for free on iTunes – give it a play!

I would also recommend that anyone interested in this topic read this blog post by ACT 4 Apps for a general overview and to understand what constitutes Personally Identifiable Information.

I will approach this in 3 sections:

1) Data collected by Corona Labs – We have always been very clear that we collect basic information from Corona-based apps via our “LaunchPad analytics”. The information collected includes:

• Device type and OS
• An app identifier – this is a string that identifies the Corona app. It does not include any end user info.
• App session time and lengths – this is data on the end user’s usage of the app, but not any personal info.
• IP address – this is the IP address related to the user’s phone connection to the Internet
• Hashed/anonymized MAC address – this is an identifier of the end user’s device

Please note that we no longer collect UDIDs, although the *anonymized* MAC address does serve as a device identifier. All data collection for analytics purposes needs some type of device identifier, otherwise the data would be almost useless.

VERY IMPORTANTLY, IT HAS ALWAYS BEEN POSSIBLE TO TURN COLLECTION OF THIS DATA OFF. This is documented in several places, but here I will direct you to the Analytics section of our Project Configuration guide.

The way to turn this data collection off is by adding the following code to your app’s config.lua file:

application =
{
launchPad = false,
}

Once your app includes that line of code, CORONA LABS DOES NOT COLLECT ANY DATA from your end users’ app sessions.

One final point on this: even in the cases when we do collect this data (i.e., when you have not turned it off), we NEVER share this data with any third parties. The data is only used as a way to give you basic analytics on your apps and by us in aggregate form to get some basic data on the Corona ecosystem.

2) Data collected by 3rd party services – Of course, Corona allows you to use a number of 3rd party services (e.g., ad networks, analytics services, etc.). We cannot control what data those services may or may not collect. It is up to you, the app developer, to make sure you know what data those 3rd parties collect and act accordingly.

If you turn off the Corona “LaunchPad analytics” but still decide to use a 3rd party service, it is possible that you are sending data to those 3rd parties via their libraries/SDKs even if we (Corona Labs) are not collecting any data.

3) Privacy policies – Finally, as we mentioned back in December, we think it is important for all developers to know what data they are using/sending and to have privacy policies that accurately reflect this.

To help with this, we have published a Privacy Policy for App Users that explains what data is being collected, if any, by Corona Labs.

We recommend that your app have a privacy policy that lists any 3rd party services used in your app, and that links back to this Corona Labs policy – this will ensure that you are informing your users of any data that is being collected.

As a proof point and also for a Google I/O demo, we also worked with Aaron at AppAbove Games to integrate Google Play game services into his fantastic Corona-based game, Chip Chain. The new version of his game, which has support for the new Google functionality is now up on Google Play. Try it out!

We’re excited about all the new innovation happening in gaming and related cloud services and we are working hard to make as much of it available to Corona developers as possible.

1. Java 7 is the most recent version of Java, why does Corona SDK require Java 6?

Developing for Android requires Java 6, not Java 7 (according to the Android site). Corona SDK uses the Java tools for signing the APK, so we have the same requirements as if you were doing native Android development.

When you run Corona SDK and try to do a build, it checks to see if Java 6 is installed. If it doesn’t find Java 6, you will be prompted to install Java 6.

Note: Starting with Build 1103, we found a way to make Corona SDK run with Java 7, so now both the Mac and Windows Simulators can run with either Java 6 or Java 7 installed.

2. I keep getting a message on my Windows machine saying Java wants to update my Java (6) to Java 7. Should I upgrade?

If you are running the public build (971 or 1076), we don’t recommend running the Java updater because it may remove the JRE 6 binary files, causing Corona SDK build errors.

3. I can’t build for Android — the “Key Alias” field is empty

This generally means the Java 6 install is damaged. You will also get “keystore password not valid” error if you browse and select the debug keystore shipped with Corona SDK.

This can happen if you try to install Java 7 over Java 6 and the Java updater removes the JRE 6 (Java Runtime) binary files. We have seen this happen when you run Java (7) Updater 45. See question 5 for how to restore JRE 6.

4. I can’t build for Android — I get a “Could not load …/jvm.dll, error 126″ message.

We added support for Java 7 in Build 1093 but it only worked correctly if you installed Java JDK7 from Oracle’s website. We found if you installed Java 7 using the Updater 45, it would remove a key DLL file, causing the above error message when trying to do a build in the Windows simulator. The solution is to use Build 1103, which now properly locates the DLL file. (This turned out to be a known Java Updater bug.)

5. I’ve installed Java 7 so how do I get Corona SDK Build 1076 working again?

Installing the Java 7 Updater removes the JRE 6 binary files but leaves the JRE 6 key in the Windows Registry making Corona SDK think Java 6 is installed. The solution is to re-install Java 6 JRE files. You can download JRE 6 here. Make sure you pick the 32-bit version for Windows (Windows X86).

Once you’ve run the Java 7 Updater and re-installed the JRE 6 files, you can build with both the public releases and the latest Corona SDK Daily Builds (starting with Build 1103).

That’s it for today’s questions. I hope you enjoyed them and even learned a few things!

Scott Adams, the legendary creator of Dilbert is on the hunt for the hottest mobile game, with the beloved cartoon engineer. We’re joining forces with Dilbert and calling on the Corona SDK community to create the hottest game with Corona SDK Starter, Pro or Enterprise. This contest runs May 14 – July 12, 2013 with winners announced on July 19, 2013.

The Dilbert comic strip is known for its humor around the vices, follies and day-to-day shortcomings of the white-collar office working environment. This is your chance to take this world famous character, create a cross-platform game with Corona SDK, and as a grand prize, have an opportunity to demo your creation to Scott Adams.

Our Corona Labs’ judging panel of experts are looking for innovation, enthusiasm and overall quality for the winning game. Not to worry, your efforts won’t go unnoticed with loads of additional prizes, including year long subscriptions to Corona SDK Pro (worth $599) and iTunes gift cards.

So, head over to Dilbert.com for a little inspiration, and get to coding! You have nearly two months to create something magical, and we’re confident the Corona community will make Scott Adams proud. Check out a complete set of rules and guidelines and sign up to compete.

Good luck!

Around the time I started using Corona SDK, there was an open source Lua module called MovieClip that I really enjoyed using. You’d simply provide a list of image file names (one image per frame) and it would load them all into memory. Then you could play them in a looping sequence, front-to-back, back-to-front, or just jump to a specific frame. MovieClip had some dark sides, however. Most obvious was that loading a whole slew of images for a “flipbook” animation was wasteful in regards to both memory and processing time. Another negative aspect was that it was open source, so people took the code and changed it to suit their needs. That sounds good in theory, but when one person built MovieClip 1.4 with feature set “X” and another developer built a different MovieClip 1.4 with feature set “Y”, nobody seemed to know which version did what. Essentially, only the author of a specific version could support it, and with no source control, the MovieClip module ran wild.

Although you can still find MovieClip floating around, it’s been effectively deprecated. And so, I realize that I must finally adapt to sprites and image sheets. In today’s tutorial, follow along as I get over my “fear of sprites” and show you how to use them in some interesting, practical ways.

Frequent Uses

A common question for beginners is how to change the “frame,” or the source file, of an image declared with newImage() or newImageRect(). This isn’t technically allowed, but obviously we still need a method to change images on the fly. There are plenty of cases in which you might need this, including:

• A two-state image, i.e. a lightbulb which turns on and off.
• Card games where some of the cards are hidden (flipped over).
• An incrementing health bar.

My first Corona-built game, OmniBlaster, used MovieClip to control the health bar, in addition to the following game aspects:

• Selecting which of the three ships (images) the player is currently using.
• Setting one of five “sensitivity” options on the settings screen.
• Setting one of the three difficulty settings.
• Controlling the current shields around the ship.
• Displaying a bar graph for  the two power-up timers.
• Displaying a bar graph to represent the current health of the ship.

Fortunately, all of these can be easily accomplished with sprites. Let’s learn how…

Getting Started: Building the Image Sheet

In Corona SDK, all sprites are assembled from one or more image sheets. An image sheet is merely a larger “canvas” which includes all of the animation frames for the sprite(s).

To create an image sheet, you can either assemble it manually using an image editor (Photoshop, the Gimp, etc.) or use an image packing tool like Texture Packer or SpriteHelper. The great thing about packing tools is that they support multiple sizes of image sheets for different screen resolutions, and they pack individual images into the most compact, memory-efficient arrangement possible. In addition, Corona SDK only has to load one image file, versus a considerable number of images as was required with MovieClip.

As a starting point for implementing sprites, I’m going to rebuild my “health bar.” Each individual image is designed to look like an LED, with green/blue representing full health and red indicating the ship is almost destroyed. Each image is 60×20 in size and there are six frames in total, so this image sheet will be very easy to create.

In the image editor, I simply create a canvas that is 60 pixels wide and 120 pixels tall. When I paste each frame on the canvas and progress downward, the result is this:

Coding the Image Sheet

Coding the sprite for the health bar (or any sprite) involves three basic steps:

1. Create the image sheet.
2. Create the sprite and position it.
3. Play the sprite.

First, let’s create the options for the image sheet:

local options = {
   width = 60,
   height = 20,
   numFrames = 6
}
local healthSheet = graphics.newImageSheet( "images/health_bar.png", options )

This block of code defines the parameters of the image sheet. Each frame is 60 pixels wide (width), 20 pixels tall (height), and there are 6 total frames (numFrames).

Next, I’ll create six sequences of frames to play — a simple animation of the health bar incrementing from zero to a certain value. In OmniBlaster, these sequences are used as an animated power-up toward a certain health increment.

local sequenceData = {
   { name = "health0", start=1, count=1, time=0,   loopCount=1 },
   { name = "health1", start=1, count=2, time=100, loopCount=1 },
   { name = "health2", start=1, count=3, time=200, loopCount=1 },
   { name = "health3", start=1, count=4, time=300, loopCount=1 },
   { name = "health4", start=1, count=5, time=400, loopCount=1 },
   { name = "health5", start=1, count=6, time=500, loopCount=1 }
}

local healthSprite = display.newSprite( healthSheet, sequenceData )
healthSprite.x = 75
healthSprite.y = 15
statusBar:insert( healthSprite )  --"statusBar" is a display group

All sequences must be identified by a unique name so you can refer to them later. In this case, I name them “health” plus a digit that indicates the life value. Then, I create the sprite using the display.newSprite API and assign the sequences to the new sprite. Finally, I position the object and add it to a display group.

Animating the Health Bar

In OmniBlaster, there’s a variable called lives which is a number from 0 (dead) to 5 (max health). When I want to animate the health bar from frame 1 to a certain destination frame, I can use the lives variable to set the sequence using basic Lua concatenation, as follows:

healthSprite:setSequence( "health" .. lives )

And then, playing the sprite is as simple as this:

healthSprite:play()

Quite simple! For sake of comparison, let’s examine the complete code that MovieClip would have required…

local healthSprite = movieclip.newAnim( {"images/lives_1.png", "images/lives_2.png", "images/lives_3.png", "images/lives_4.png", "images/lives_5.png", "images/lives_0.png"}, 60, 20 )
healthSprite.x = 75
healthSprite.y = 15
statusBar:insert( healthSprite )

healthSprite:play{ startFrame=1, endFrame=lives, loop=1, remove=false }

Although the setup is simple and the overall number of lines is less than the sprite method, in the next section we’ll explore how the same sprite object can be used for other purposes. Multi-purpose equates to higher efficiency and it also makes your life easier.

Image Swapping

In OmniBlaster, I need to animate the health bar, but I often need to set the bar to a specific increment as well. For example, if all of the shields are gone and the ship takes a hit, the player loses a health point. I could have accomplished this using MovieClip, but since this tutorial is about sprites, let’s examine the same process using that method.

If you want to set a sprite frame to any frame in the overall sheet, logically you must create a sequence that contains all of the frames. Using the OmniBlaster health bar again, that sequence is “health5″ — this is the only sequence that encompasses all six frames in the sheet. With this in mind, we set the sequence as follows:

healthSprite:setSequence( "health5" )

Then, to set the frame to a specific value, i.e from a visual increment of 4 to 3, the code is simple:

healthSprite:setFrame( 4 )

Why did I use 4 instead of 3? Because if you examine the image sheet, the visual increment of three notches in the health bar is actually the fourth frame.

Careful Now…

It’s important to understand that when you explicitly set the frame of a sprite, the integer value that you declare is related to the sequence, not the overall sheet. For example, if you configure an image sheet of six frames and a sequence that uses frames 4, 5, and 6, you must use the following to jump to frame 6:

sprite:setFrame( 3 )

Why? Because frame 3 in the sequence equates to frame 6 in the overall image sheet. To illustrate this, let’s use a modified version from the OmniBlaster sheet:

local sequenceData = {
   { name = "health_4_to_6", start=4, count=3, time=300, loopCount=1 }
}

Notice how in this new sequence, we are setting start=4 and count=3, which will encompass frames 4, 5, and 6 of the overall sheet. Then, if we use (set) this sequence and want to jump to frame 6 of the overall sheet, the proper code is:

healthSprite:setFrame( 3 )

--NOT--

healthSprite:setFrame( 6 )

If you use the second example, Corona will issue a warning similar to this:

ERROR: sprite:setFrame() given invalid index (6). Using index of 3 instead.

This will not terminate/crash your app, but you should understand how to properly set frames within a sequence, or you may encounter problems when dealing with more complex animations and image sheets.

It’s All About Efficiency

Notice that both of our examples above — animating and frame swapping — use the same image (sprite) object, from the same image sheet. This multi-purpose practice is efficient in two key ways:

1. Code Efficiency — creating one object allows us to declare, reference, track, and clean up our sprites much easier.
2. Memory Efficiency — as a mobile developer, you need to be consistently mindful of memory usage. As I mentioned in regards to MovieClip, it was easy to use but it was generally not efficient. Creating all of those individual objects from individual image files was a resource hog in regards to both Lua memory and texture memory too. Of these two, texture memory is a far greater concern for the mobile developer. If you wish to explore texture memory and how Corona/OpenGL allocate it, please refer to Conserving Texture Memory in the Performance Optimizations tutorial.

In Summary…

As you can see, sprites are not just for typical animations, but for swapping frames of a “static” image as well. Best of all,  if you optimize/pack your individual images into image sheets — and I highly recommend that you do — using sprites requires just a few more lines of setup and minimal additional effort elsewhere in code. In essence, they are flexible, efficient, and provide more control than MovieClip ever did.

So today, we are going to open up that beta starting with daily build 2013.1106.

Okay, ready to get started? Two things:

First, download daily build 2013.1106 or after. Do not use previous builds, as you may experience issues.

Second, you need to tell Corona that you are using plugins so the Corona Simulator can perform device builds properly. This boils down to adding a few lines in your ‘build.settings’ file. Head over to our new Corona plugin documentation site. Each plugin has its own documentation page that describes what you need to add in ‘build.settings’ for that plugin.

For example, here’s what you do for inneractive:

settings = {
    -- Add the following to enable inneractive support:
    plugins = {
        ["CoronaProvider.ads.inneractive"] = { publisherId = "com.inner-active", },
    },
}

That’s it! You’re ready to go.

Right now, we’re making the following initial set of plugins available:

• AdMob: iOS + Android
• Greenthrottle: Android
• Inneractive: iOS (Apple API compliant). Android is already in Corona’s core but will soon move into a plugin.
• OpenSSL: iOS + Android + Mac. Win support is coming.
• OpenUDID: iOS-only.
• Zip: iOS + Android + Mac + Win.

Note that some of the plugins only work on device, while can work within the Corona Simulator.

Also, we are going to move some services into plugins that currently reside in the core Corona engine. That means in a future build, if you want to use these services in your apps, you’ll need to add a few lines to your build.settings:

• Flurry: iOS + Android
• iAds: iOS
• InMobi: iOS + Android
• Inneractive: Android

This is just the beginning. In the coming days and weeks, you’re going to see more plugins from us and from our growing list of partners!

As we’re still at Beta, please let us know any issues in the subscriber-only Plugins Beta forum.