As you may know, the process of creating an .ipa file from an .app file looks like this:

1. Create a directory called “Payload” (case sensitive).
2. Copy/move your .app file into that directory.
3. Zip the directory.
4. Rename it to “whatever.ipa”.

This is all pretty simple, but if you do this via Finder it can get pretty tedious if you have to do it very often - for example, one current client requires separate localized builds of the app I’m working on. So for them, I need to repeat those steps for the English and the French versions (thankfully in this context, Canada only has two official languages). That’s a lot of clicking around with the mouse.

To automate the process, I whipped up this simple little bash script:

1
2
3
4
5
6
7
8
9
10
11
12

#!/bin/bash

if [ -d "Payload" ]; then
  rm -fr Payload/*
else
  mkdir Payload
fi
# if you'd rather copy the .app file, then replace the next line with:
# cp -r $1 Payload
mv $1 Payload
zip -r $2.ipa Payload
rm -fr Payload

To set this up on your system:

1. Copy and paste the script above into an empty text file. Save it as apptoipa.sh (or another name of your choosing).

2. Open up Terminal.app and navigate to the directory where you saved the script.

3. Make the script executable: chmod +x apptoipa.sh should do it (if you used TextMate for step 1, the Shell Script bundle has a command to make the script executable).

4. You’re all set

The script requires two arguments: the name of the .app file, and the name of the resulting .ipa file. For the latter, don’t include the .ipa extension, so usage would look like this:

1

Behemoth:Desktop darren$ /path/to/script/apptoipa.sh MyFabulousApp.app App\_1\_0\_45

A few things to bear in mind:

• This script will delete any existing Payload directory.
• It will also delete the Payload directory after the .ipa file has been created.
• It moves the .app file into Payload instead of copying it, so your .app file WILL BE DELETED. If you want to preserve the .app file, see the comments in the script. I haven’t tested it, but it ought to work.

This script is very straightforward and doesn’t do any checking for required arguments or anything like that, so exercise caution, use at your own risk, and do not use while driving.

Doing so will trim approximately 2.5 MB from the file, which is a pretty substantial savings.

(Update: it turns out that the bulk of the savings comes from simply rebuilding the apk file using the tools in the SDK. This was pointed out by a commenter in a thread on Ansca’s forums. So I tried it with Poker Solitaire. Simple repackaging the apk decreased the total size by about 2.1 MB, so it turns out that the libraries actually take up a pretty small proportion of the apk. So if you’re at all leery about deleting libraries from your app, you can simple rebuild the app and still reap a substantial reduction in file size!)

It can also help you reassure clients who may wonder why all this extraneous stuff is being included in their app (I have had to answer this question for enterprise clients who are using Corona-built apps internally). To recoup this space, there are a few prerequisites:

1. You need to have the Android SDK installed;
2. You need to have the Java JDK installed;
3. You need to be at least somewhat comfortable with the command line.

I’ve tested this in OS X using builds of both my own apps and client apps. I see no reason why it wouldn’t work in Windows, but I haven’t tested it. The resulting apps have installed and worked fine for me in all cases, but please bear in mind that you’re doing this at your own risk and I’m not responsible for anything at all that you care to do with the following information. So let’s get started:

First Things First

You need an apk generated by Corona, so build your app as you normally would.

Next, open up Terminal.app and navigate to the directory containing your apk file. The apk is essentially a zip archive, so you could simply change the extension and unzip it. If you do this and examine the results, you’ll notice that the manifest file is in a binary format - this is done as part of the build process. Since we need to edit that file, we need it in plain text. Instead of simply unzipping the file, we’re going to use apktool, which is part of the Android SDK, to ‘decode’ the apk file. Enter this at the command line - I’m using my Poker Solitaire game in this example, so obviously replace that with the name of your apk file as you follow along - and you should see the resulting output:

1
2
3
4
5
6
7
8
9
10
11

$ apktool d PokerSolitaire.apk
I: Baksmaling...
I: Loading resource table...
W: Skipping "android" package group
I: Loaded.
I: Loading resource table from file: /Users/darren/apktool/framework/1.apk
I: Loaded.
I: Decoding file-resources...
I: Decoding values*/* XMLs...
I: Done.
I: Copying assets and libs...

If apktool isn’t in your path, you’ll need to enter the full path, which will look something like this:

1

$ \path\to\AndroidSDK\platform-tools\apktool

This will create a directory called ‘PokerSolitaire’, which will contain the following files and directories:

The first thing to do is open up the AndroidManifest.xml file in your favourite text editor and remove some entries. Basically, you need to remove anything that looks like it’s related to Papaya Mobile, Open Feint, or Super Rewards. These will be entries where the android:name attribute starts with com.papaya, com.openfeint, or com.adknowledge. Here are a few by way of example - this is not an exhaustive list:

1
2
3

<activity android:theme="@style/OFNestedWindow" android:label="NativeBrowser" android:name="com.openfeint.internal.ui.NativeBrowser" android:configChanges="keyboardHidden|orientation" />
<provider android:name="com.papaya.social.PPYSocialContentProvider" android:authorities="com.ludicroussoftware.test.PokerSolitaire.ppy_cache" />
<activity android:name="com.adknowledge.superrewards.ui.activities.SRPaymentMethodsActivity" android:screenOrientation="portrait" />

You can also delete any entries that start with com.zong. I haven’t actually investigated what these do - they seem to be related to Super Rewards - but I was able to safely delete them. Once you’ve got them all, save the file.

Next, we’ll delete the actual libraries. Expand the smali\com directory, and you should see something like the screenshot above. Delete directories for any libraries that you’re not using. Poker Solitaire uses none of these, so I was able to safely delete the adknowledge, facebook, flurry, inmobi, inneractive, openfeint, papaya, and zong directories. I also deleted the zongfuscated directory with no ill effects. Obviously, if you are using any of these services, do not delete them.

Rebuild the apk

Back in the Terminal, here’s what you need to do:

1. Build the apk file using apktool:

1
2
3
4
5
6
7
8

Behemoth:Desktop darren$ apktool b PokerSolitaire PokerSolUnsigned.apk
I: Checking whether sources has changed...
I: Smaling...
W: Unknown file type, ignoring: PokerSolitaire/smali/.DS_Store
I: Checking whether resources has changed...
I: Building resources...
I: Copying libs...
I: Building apk file...

2. Sign the apk using the jarsigner tool that’s part of the Java JDK. You’ll also need your keystore and key alias that you used to sign the app, as well as the password. The key alias is the last argument passed to jarsigner:

1
2

Behemoth:Desktop darren$ jarsigner -verbose -keystore ~/Dropbox/LudicrousRelease.keystore ~/Desktop/PokerSolUnsigned.apk ludicrousRelease
Enter Passphrase for keystore: 

After you enter your passphrase, you’ll see a whole bunch of ‘signing:’ messages zoom by; once it’s all done, you have a signed apk file.

3. The last step is to zipalign the apk file:

1

Behemoth:Desktop darren$ zipalign -v 4 PokerSolUnsigned.apk PokerSol.apk

And you’re all done. You can test your app as you normally would, upload the Android Market, etc.

But Wait, There’s More!

If you poke around in the directory created by apktool, you’ll notice a bunch of other files related to Papaya and Open Feint, mainly. There are all kinds of image files in the res directory, as well as a bunch of entries in the various xml files in res/values. I tried going for a wholesale removal of all of these things, which resulted in the build process breaking. I haven’t yet figured out why that’s happening. The completist in me would like to figure it out, but these images add up to a small percentage of the total space taken up by all of these libraries, so it’s not a huge deal if they’re left in the app. It’s bothersome, but at a certain point the law of diminishing returns kicks in and I just need to Let It Go.

First off, I’ve posted the basic Bunnymark code to GitHub. Included in it is a simple FPS counter that I put together. If you look at the code for the counter, you’ll see that you can specify a ‘target’ frame rate, and the counter will dispatch an event when the frame rate drops below that target. This makes it a bit easier to stop any particular code from running if the FPS drops too low. Also, to account for any temporary dips in the frame rate (e.g. by creating a couple hundred display objects in a single frame) it tracks the frame rate as an average of the rate over the last 60 frames.

The bulk of my income is in client work, so my main goal in developing/distributing these apps wasn’t necessarily the income they would generate. I don’t do any marketing, unless you want to count as marketing a couple of mentions on Twitter that I’d released the games (but you probably shouldn’t). So these numbers can perhaps be seen as what happens if you create a game and then essentially neglect it (but you probably shouldn’t).

I ported Poker Solitaire to the PlayBook because it was a good exercise in familiarizing myself with AIR development for the device (and because I like the game). Marblous is a very straightforward collapse clone. I’d originally created it because I wanted to figure out the logic for finding matching neighbours - this was back in about 2006 when I was doing Flash Lite 1.1 work. (Side note: the algorithm had to execute over the course of multiple frames because Flash Lite was pretty slow on a Nokia 6620 - I also had to walk uphill in the snow to and from the mobile phone store; you kids these days have it easy). Then early last year, during the brief period of time when I was under contract to write a book on AIR for Android game development, I dusted off the code and ported it to AS3 with the intent of using it in the book. Ultimately, I never did finish the book, but I had the completed game code sitting around, and figured that since at least something should come out of all that work, I released the game for free for the PlayBook.

So all that said, here’s the sales chart for Poker Solitaire, broken down by week (Excel is the one that figured there are 53 weeks in a year, for what that’s worth). The game was available at the launch of the PlayBook - note the anemic launch sales. I’d have expected at least a moderate bump at launch, given the small size of the app market for the PlayBook at launch:

The sales are pretty inconsistent, but overall there’s an uptick starting in week 53 of 2011, which would of course be right after Christmas. As far as total numbers are concerned, there have been 138 sales altogether. 43 of those sales have happened since week 53 of 2011. Of the 138 sales, 105 were from either the US (42) or Canada (63). So sales to Canadian PlayBook owners accounts for almost half of the total sales.

My guess is that the price drops on the PlayBook meant that there were a lot of them showing up under Christmas trees, which would explain the relatively recent increase in sales. This is even more pronounced in the chart of Marblous downloads:

First off, the scale of the chart is obviously much higher, which is to be expected from a free app. But the trend is most consistent and more apparent with the free app, too: after its initial release in July, it settled down into a pattern of about 30 to 50 downloads per week. However, the same spike in week 53 of 2011 occurs here too, only it’s much more pronounced. Now, the game is being downloaded about 200 times per week, give or take (since week 8 isn’t yet complete, it’s a bit lower than the others). Although the chart doesn’t show total numbers, it turns out that Marblous has already been downloaded almost as many times in 2012 as it was in all of 2011, more if you include week 53 to capture all post-Christmas sales.

Also, the PlayBook is a predominantly North American and overwhelmingly Canadian device, if the downloads broken down by country are any indication (sorry for the small print):

In terms of actual numbers, Marblous has been downloaded 3422 times since it was released. 2271 of those downloads are from the US and Canada, and 1691 (49.4%) are from Canada alone.

From my perspective, I think this points to the PlayBook as an attractive development target - I suspect that this is true of it were a developer’s primary target for development, but I’m pretty confident that it’s worth the time and effort required to port to the PlayBook an application that was originally developed for a different device/platform. It also means that I’d give serious thought to using Adobe AIR, since it would mean less work in porting to the PlayBook (as compared to something like Corona, which would require a rewrite to a different language).

Local v. Global

First off, the difference between local variables and global variables. The basic difference is pretty simple: anything that is not explicitly declared as a local variable is automatically made global. You don’t need to explicitly make a variable global by using _G, nor do you have to declare globals in a specific location. So, for example:

MyModule.lua:

1
2
3
4
5

local MyModule = {}

foo = "foobar"

return MyModule

main.lua:

1
2
3
4

local MyModule = require("MyModule")

-- outputs 'foobar' to the console
print(foo)

If you’re coming to Lua from another language, you have a few options for how to handle things:

1. Avoid using global variables at all. Probably a comfortable approach if you’re coming from a language like AS3, where globals are allowed but not really encouraged as a best practice.

2. Use globals, but restrict their definition to main.lua. Optionally also use _G when declaring and accessing global variables (e.g. _G.foo = "foo") to make it clear that this variable is global on purpose.

3. Put all your globals into a single module whose sole purpose is to store global values.

Which one do you choose? That’s entirely up to you. I usually go with the third approach, since it forces me to do a little extra work to create a global variable, which helps make sure that I actually think through whether some needs to be global before I make it so. But I’ve also gone with option two on occasion, and it works just fine.

Local Scope

Local variables are local to the enclosing chunk. Chunks are basically one of four things:

1. The enclosing module (i.e. the .lua file);

2. The enclosing function

3. The enclosing control structure

4. do/end chunks

So, consider the following simple module:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

local Module = {}

local counter = 0

function Module.new()
  
  local g = display.newImage("myImage.png", 0, 0)
  
  local xPos = 0
  
  local function onTouch(event)
      if event.phase == "ended" then
          local xDelta = math.random(5)
          xPos = xPos + xDelta
          g.x = xPos
          counter = counter + 1
      end
      print("xDelta", xDelta)
      print("touches", counter)
  end
  
  g:addEventListener("touch", onTouch)
  
  return g
  
end

print("xPos", xPos)

return Module

When called, Module.new() will return a new display object. When touched, the object’s x position will be incremented by a random amount from 1 to 5. The amount is stored in a local variable, xDelta, and the actual position is stored in a different local variable, xPos. The callback also tracks the number of times the object has been touched.

So, there are three different local variables:

• counter: declared at the module level, this variable is accessible throughout the entire module. Since it’s declared at the module level, all instances created with Module.new() will refer to the same counter variable. This is basically how you would implement static methods or properties in Lua

• xPos: declared inside the new() function, this is accessible only within new(). When the statement print("xPos", xPos) is executed, it will return a value of nil, because xPos isn’t accessible outside of its scope.

• xDelta: declared inside the if control block, this value is accessible only within the if block. As a result, the statement print("xDelta", xDelta) will return a value of nil. However, the value of counter will be properly printed, because counter is accessible throughout the module.

(In both cases, the value returned is nil because Lua is looking for a global variable with that name since it hasn’t found any locals. Undeclared globals have a value of nil.)

Other control blocks for the purpose of local variables:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

while foo < bar do
  local q = 5
end

repeat
  local j = 10
until foo < bar

for i = 1, 10 do
  local k = 15
end

do
  local i = 5
end

The trickiest part in these examples is that in a for statement, the iterator variable is automatically declared as a local variable. This means that the value of i in the example above is unavailable outside of the loop. So, if you want to iterate over something, potentially breaking out of the loop when some condition is reached, and you need to remember the point at which you broke out of the loop, you need to declare a local variable outside of the for loop, and set its value equal to the iterator before your break.

Scope in Functions

Another aspect of scope in Lua is when dealing with functions. Unlike other languages, with many Lua functions you need to explicitly declare the scope of a function call. You can see this throughout the table and string packages:

1
2
3
4
5

table.insert(myTable, "foo")
table.remove(myTable, 5)
local length = string.len(myString)
myString = string.lower(myString)
-- etc.

In effect, the first argument being passed to these functions is scope of the function call. It’s telling table to insert or remove values from myTable, or to do stuff with myString.

This is done so frequently that in many cases Lua provides “syntactic sugar” to make it easier to make the same function calls. It doesn’t apply to the table package, but for the string methods above they could be rewritten this way:

1
2

local length = myString:len()
myString = myString:lower()

In effect, using a colon to call these methods lets you emulate the sort of object-oriented approach that you get in other languages. With the colon, Lua knows to pass the object as the first parameter of the function.

You can recreate this same approach in your own code in one of two ways: either declare your function using a colon, or make self the first parameter of the function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

local g = display.newRect( 0, 0, 100, 100 )

print("g", g)

function g:test()
  print("g:test", self)
end

function g.test2(self)
  print("g.test2", self)
end

g:test()
g:test2()
g.test2()

The output from this will be:

1
2
3
4

g       table: 0x5bdaf0
g:test  table: 0x5bdaf0
g.test2 table: 0x5bdaf0
g.test2 nil

Since the value of self from both functions matches the value of g from the original print statement, you can see that whether done implicitly or explicitly, calling a method using the colon will correctly set the proper scope. However, in the last case, where the function was called using dot notation, no reference to self was passed to the function, so self is nil.

One implication of this approach is that in Lua the scope of a method of an object can be set to any other object. Like this:

1
2
3
4
5
6
7
8
9
10
11
12

local g = display.newRect( 0, 0, 100, 100 )
local h = display.newRect( 0, 200, 100, 100 )

print("g", g)
print("h", h)

function g:test()
  print("g.test", self)
end

g:test()
g.test(h)

This gives us the following output:

1
2
3
4

g       table: 0x202d490
h       table: 0x202d5e0
g.test  table: 0x202d490
g.test  table: 0x202d5e0

So even though test2 is a method of the display object g, it can act on h if we pass it to that function. Not that you’d want to do that.

Specifically in the Corona APIs, you see the colon notation fairly frequently:

1
2
3
4
5
6
7
8
9
10

local g = display.newImage("image.png")

g:removeSelf()

-- is the same as:
g.removeSelf(g)

-- so yes, you could also do:
g.removeSelf(h)
-- but again, why would you want to?

All That Said…

I never (okay, very rarely) actually use self in Corona apps. About the only time I’ll use it is if I’m creating a bunch of ‘anonymous’ objects - i.e. objects for which I’m not explicitly storing a reference - and need to create some kind of event handler for them. In that case, I’ll typically use a table listener rather than a function listener:

1
2
3
4
5
6
7
8
9
10
11
12

local function onTouch(self, event)
  if event.phase == "ended" then
      print(self)
  end
end

for i = 1, 6 do
  local rect = display.newRect( i * 15, i * 15, 10, 10 )
  rect.touch = onTouch
  rect:addEventListener("touch", rect)

end

(Even though in this case you could also use event.target to figure out what object was touched.)

However, the far more common approach I’ll take is not not use self at all and simply rely on the closure to take care of scope for me. So for example, here’s a condensed version of the module we looked at earlier:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

local Module = {}

function Module.new()
  
  local g = display.newImage("myImage.png", 0, 0)
  
  local xPos = 0
  
  local function onTouch(event)
      if event.phase == "ended" then
          local xDelta = math.random(5)
          xPos = xPos + xDelta
          g.x = xPos
      end
  end
  
  g:addEventListener("touch", onTouch)
  
  return g
  
end

return Module

Notice that inside the onTouch event handler, I’m referencing the display object g directly, rather than using self. Because Lua supports closures, even though g is a local variable (and so the reference to it should be removed when the function has finished execution), it remains in scope as long as it’s required for some other chunk of code to run.

(That may not be the most elegant way to describe closures, but should get the point across.)

The added benefit of this approach is that it doesn’t really matter whether you use colon or dot notation to access your object’s methods. I remember reading one comment where the developer said they prefer to use colon notation to reinforce the fact that they’re calling methods of an instance of a class, rather than a class/static method. My current inclination is to use the AS3-style naming conventions to distinguish between classes and instances of a class (so, Class.new() v. instance.doStuff()). But as with some many things in Lua: whatever floats your boat.

The hasEventListener function I wrote relies on the fact that there are some “hidden” properties in Corona that aren’t mentioned in the reference documents, but are completely accessible using plain old Lua. Specifically, objects that can listen for events will have a table storing the events being listened for and the functions to call when the events occur - you can get more background about this in an earlier post about the fastest way to remove all event listeners.

You can grab the code from the github repository I set up to hold all of the utility functions I use for Corona development. (I’ll be adding to it over time.)

Usage is pretty straightforward:

1
2
3
4
5
6
7
8
9
10
11
12

  -- import the module
  -- local Utilities = require("com.ludicroussoftware.Utilities")
  
  -- check for a function listener
  hasListener = Utilities.hasEventListener(object, "touch", onTouch)
  
  -- check for a table listener
  hasListener = Utilities.hasEventListener(object, "touch", object)
  
  -- check for any listener whatsoever
  hasListener = Utilities. hasEventListener(object, "touch")
  

A somewhat more detailed example is included in the repository.

(The app is for internal use, so it won’t be released publicly and I can’t share specific images.)

From watching the console output as the app was built, it was clear that the bottleneck is the process of compressing/copying all the images into the app (Corona runs all PNG images through pngcrush to optimize them; this is also what Xcode does). Since copying a file isn’t particularly time-consuming, I assumed that the compression was the problem.

My initial thought was that it would be great if there were a way for Corona to cache any image optimizations that it does, so that it doesn’t have to do them again if the image changes. This would be similar to how Flash Pro will now cache the compressed version it generates from a WAV file during the build process.

I mentioned this to Carlos, and he suggested that I manually optimize the images ahead of time, and that he thought this would cause that step to be skipped during the build process. The optimization is performed by a program called iphoneos-optimize in the iOS SDK, so you’ll need to have the SDK installed. iphoneos-optimize is basically just a wrapper for pngcrush, passing in the optimal settings so you don’t need to do that yourself.

The major downside of this approach is that it renders your images unusable on the desktop - you can get some technical background on how the images are optimized in this blog post, but the short version is that an optimized PNG isn’t a ‘real’ PNG, so it looks like a corrupt file. If you optimize the images yourself and then try to test your app in the Corona Simulator, you’ll get a lot of “incorrect header check” error messages, and your images won’t show up.

So, this means that you’ll need to export your project to a separate folder so that you don’t destroy your original images. Here’s the basic process:

1. Export your project to a separate folder; if you’re using git, then git checkout-index -a -f --prefix=/path/to/target/folder/, when run from the root folder of your project, is an easy way to do this.
2. Open up the Terminal and change to the directory containing the copy of your project (cd /path/to/target/folder/)
3. Run iphoneos-optimize on the folder. You need to provide the target folder, so just use the dot to pass in the current folder: /Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/iphoneos-optimize .
4. Open the project in the Corona Simulator. Ignore the fact that none of your images show up.
5. Build as usual.

So, what are the results for my ginormous image-heavy app?

The regular build process, where Corona handles the optimization, took 8 minutes, 8 seconds, just now.

Manually running the image optimization from the command line took 1 minute, 36 seconds.

Creating the device build with Corona using the pre-optimized images took 42 seconds.

So, clearly, even if you factor in the time spent copying images, etc., pre-optimizing images can save a lot of time during the build process. This is especially true if you’re debugging stuff that can’t be tested in the Simulator anyway (like multitouch), so it doesn’t matter if your app doesn’t ‘work’ in the Simulator.

Also, since these images aren’t going to be changing a lot, I don’t need to run the optimization every time, so things could be even faster if I were to write a shell script to move all my images out of my project folder and replace them with the optimized images. Then I could do the build and then call another script to copy all the images back again so I could have something that does work in the Simulator.

(It would be so nice to be able to automate the whole process from the command line! At least with Android builds you can go into the Simulator resource bundle and tweak the build.xml file. It’s not much, but it’s something. But that’s another blog post.)

So why the huge discrepancy here? I’m not sure why the ‘default’ build takes so long, but my best guess is that iphoneos-optimize can work a little more quickly because it’s doing things in batch mode - it iterates through the entire project just optimizes the images. Based on the output you get when Corona creates a device build, it looks like the build process iterates through every individual file in the project and decides what to do with it. So, images are getting optimized one at a time and then copied into the app. I’m not sure if that’s actually the problem, but that seems to be what’s happening.

dyld: Library not loaded: /usr/lib/libedit.3.dylib
  Referenced from: /Applications/CoronaSDK/debugger
    Reason: image not found
Trace/BPT trap

So the problem is that libedit.3.dylib isn’t found on my machine. Based on a bit of Googling, it looks like the problem is that I’m running Snow Leopard, which has libedit.2.dylib. However, my guess is that Ansca is building against Lion, which ships with libedit.3.dylib.

Luckily, there’s an easy fix to the problem. Open up the Terminal, and issue the following commands:

cd /usr/lib
sudo ln -s libedit.2.dylib libedit.3.dylib

All you’re doing is navigating to the directory where the debugger is looking for libedit.3.dylib, and creating a symbolic link to libedit.2.dylib named libedit.3.dylib. So when the debugger looks for the latter, it’ll get pointed to the former. After you enter the second command, you’ll have to enter your password.

This seems to be working fine for me so far, but hopefully it’s something for which Ansca can issue a proper fix in the future.

The workbook will walk you through all the steps involved in building the game, right from configuring the project through to adding sound effects and creating custom components to control the volume. Along the way, you’ll build a game that, among other things:

• Uses Corona’s cross-platform capabilities to build a game that can be deployed to both iOS and Android devices from the same code base;
• Uses the built-in physics engine to handle collision detection;
• Uses sprite sheets for in-game animations, and learn how to incorporate sprite sheets sized for different devices from within the same code base (i.e. manually doing for sprites what display.newImageRect() does for images);

The only things currently not covered in the tutorial, which I may add down the road if I have some spare time (ha!) is:

• Creating a menu system with a main menu, help screen, and so on. Once Corona publicly releases their new Storyboard API, I may add this;
• Creating a device build and deploying to your device for testing. In the meantime, there are other tutorials online that cover this, including a pretty thorough explanation of the steps involved on Ansca’s website - look under the “Basics” heading.

Please be aware that a few points that probably should be fleshed out in the text are glossed over. This was intentional, since there were some things I felt would be better explained during the course of the workshop itself, rather than putting it all into the workbook. If there is sufficient interest, I may expand on these explanations (again, given this mythical spare time I seem to think exists).

Update: added one more example for further context. It’s at the bottom of the post.

While working on an app that uses a particularly popular Corona library I encountered a forward declaration bug in the library. If you’ve been using Corona/Lua for any length of time, you’ve probably encountered this kind of bug before. It occurs when you try to reference a local variable that you haven’t yet declared. It looks something like this:

1
2
3
4
5
6

myFunction printA()
  print(a)
end

local a = "5"
printA()

The problem is that the printA() function is referencing the local variable a, but a wasn’t declared before printA(). So, not having found a local variable a, it looks for a global variable with the same name. If that exists, then it prints out the value of that variable (which probably isn’t your intent), or you get a nil value error. The easy way to avoid this kind of error is to declare all your variables at the top of your chunk of code, before they’re referenced.

The actual forward reference bug in the library was a little more involved, because the local functions were also assigned to properties of the table that the library returns, because the functions need to be publicly accessible. It looks something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13

myTable = {}

local function functionA()
  functionB()
end
myTable.functionA = functionA

local function functionB()
  -- whatever
end
myTable.functionB = functionB

return myTable

So you can probably spot the forward declaration bug. This could have been fixed by a bunch of forward declarations. But in thinking about this, I wondered if that would even be worthwhile. All of the functions are being added as properties of the table, so why not just do this:

1
2
3
4
5
6
7
8
9
10

myTable = {}
function myTable.functionA()
  myTable.functionB()
end

function myTable.functionB()
  -- whatever
end

return myTable

I don’t know what the developer was really thinking about, but I suspect that the answer is “performance”. Since Lua is able to look up local variables faster than table properties, referencing the functions via local variables is presumably faster for function calls from within the module.

So I wonder if that is really true.

Or if it is, whether the speed difference makes the extra effort involved in the ‘local’ approach to be worthwhile.

And it’s not. At least, not enough to matter.

To test this, here’s the sample app I whipped up:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

local myTable = {}

local function stress()
  local i = 1 + 1
end

myTable.stress = stress

-- test calling the local function
local startTime = os.time()
for i = 1, 10000000 do
  stress()
end
print("stress(), elapsed ", (os.time() - startTime))

-- test calling the table function
startTime = os.time()
for i = 1, 10000000 do
  myTable.stress()
end
print("myTable.stress(), elapsed ", (os.time() - startTime))

So here’s what the code does:

1. Create a local function;
2. Store a reference to that function in a table;
3. Time how long it takes to call that local function;
4. Time how long it takes to call the function via the table property.

And the result when I built this and tested it on my iPhone 4: 7 milliseconds for the local function calls, and 9 milliseconds for the table function calls. Now, you may be thinking that that is actually pretty significant, but take a look at how many times I had to call the functions to get that difference: 10,000,000 times.

Ten million times. To save two milliseconds

Now, just to be clear, I’m a big fan of optimizing code up front in a lot of cases. Having started my development life in the world of Flash Lite, that sort of behaviour is ingrained. But even for me, it’s tough to see the benefit to the “local and table” approach. If there’s a value in that approach that I’m not quite seeing, please let me know what it is!

Update: I just wanted to expand on my comments above. Initially, I had meant this comparison of the execution of local and table functions to be applicable within a limited context: when you’re creating a local function that you’re planning to make public via the table. To be clear, my point is that there is no reasonable benefit to be gained from making that function local in the first place. Just skip that step altogether.

But as I thought about it more, I started to wonder about the general wisdom of the usual approach of making local references to table functions to increase performance speed. For example, doing this sort of thing:

1
2

local asin = math.asin
local myVar = asin(43)

This is the usual recommendation, and at first I feared that what I’d written above might be construed as contradicting that general wisdom. But it turns out that I’m not sure there’s enough benefit to be gained from doing this. Here’s the sample code:

1
2
3
4
5
6
7
8
9
10
11
12

startTime = os.time()
for i = 1, 5000000 do
  local j = math.floor(4.35)
end
print("math.floor, elapsed ", (os.time() - startTime))

local floor = math.floor
startTime = os.time()
for i = 1, 5000000 do
  local j = floor(4.35)
end
print("floor, elapsed ", (os.time() - startTime))

Turns out that over the course of 5,000,000 calls to the local function, a grand total of one millisecond is saved. Again, this is tested on an iPhone 4. I realize that a) these results may vary quite a bit on different devices, so thorough testing on all targets should be undertaken, and b) in other contexts, where you may in fact be handling that many function calls (e.g. if you’re using Lua in a non-mobile setting, perhaps), local references to table functions may be worthwhile.

But, for my part, I think I’ll probably skip it, at least until the point where I think it might actually help when implemented as part of a broader range of optimizations.

Even though this code may only run once, it might be very involved. Because you value clean, readable code, you might end up using a lot of local variables, even though you won’t need to reference these values again. The problem is, if you just stick this code inside your main.lua file (or a module), these variables will persist, taking up memory when you no longer need them. You have a couple of options to deal with this:

• you could nil out all these variables, but that involves writing more code than necessary. I’ve done this before, and I’d like to avoid the extra work if I could. Plus, I think it’s somewhat inelegant to manually nil out a bunch of variables to make them eligible for garbage collection.
• you could wrap all the initialization code inside a function. This is a little more elegant, since any locals within the scope of the function will get cleaned up after the function has completed. However, the function itself is still lying around (since that’s the whole point of a function), so you haven’t cleaned up after yourself completely. It’s like when you sweep debris onto a dustpan and you get that little line of dirt along the front edge of the pan. I hate that.

There’s one more option, which I think is more elegant than these two: wrap your initialization code inside a do/end block. Unlike code inside a function, code inside do/end is executed immediately. But the real beauty of do/end is that it has its own scope, just like a function, so any local variables inside the block can be garbage collected after the code block has finished execution. To compare it to a function, consider this simple code:

1
2
3
4
5
6

local function init()
  local a = "foo"
  print(a)
end
init()
print(a)

This is pretty standard Lua function scope. The first line of output will be “foo”, because init() is called first and references the local variable a within the scope of the function, and the second line of output is nil because a is within the scope of init(). In comparison, here’s similar code without the function call:

1
2
3
4
5

do
  local a = "foo"
  print(a)
end
print(a)

In this case, the code inside do/end is executed immediately - no function call required and no function hanging around after it’s no longer needed. And even though the code is executed immediately, it still has its own scope. The first line of output will be “foo”, and the second line will be nil, just as before, because a exists only within the scope of the do/end block.

Now, you may think that this degree of concern over memory consumption is unnecessary, but I hate that little line of dust in front of the dustpan. Plus I like the fact that this clearly communicates that the initialization code is completely and utterly disposable

What they wanted was something like this:

1
2
3
4
5

function restartLevel(boolVal, stringVal)
  print("boolVal", boolVal)
  print("stringVal", stringVal)
end
timer.performWithDelay( 1000, restartLevel( true, "resetScore"))

Ignore syntactical issues for the moment as I’m copying their pseudo-code directly; also, I have no idea what their restartLevel function looks like, so I just made one up.

My first thought was that the simplest approach would be to just use a closure, so the code would look something like this:

1
2
3
4
5
6
7
8
9
10

function restartLevel(boolVal, stringVal)
  print("boolVal", boolVal)
  print("stringVal", stringVal)
end

local function doIt()
  restartLevel(true, "resetScore")
end

timer.performWithDelay( 1000, doIt)

This will work nicely, but if you have to do this a lot, then you’ll end up with closures all over the place. That in itself isn’t a bad thing, since Lua is so closure-friendly, but it means having to write all those closures, which is more work for you. And since there are a lot of cool things you could be doing that don’t involve writing a bunch of repetitive code, here’s a way to avoid all of that:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

timer.oldPerformWithDelay = timer.performWithDelay

timer.performWithDelay = function(interval, func, ...)
  local iterations, params
  local options = {...}
  if type(options[1]) == "number" then
      iterations = options[1]
      params = options[2]
  else
      iterations = 1
      params = options[1]
  end
  local function doIt()
      func(params)
  end
  timer.oldPerformWithDelay(interval, doIt, iterations)
end

local function restartLevel(params)
  print("boolVal", params.boolVal)
  print("stringVal", params.stringVal)
end

timer.performWithDelay(1000, restartLevel, {boolVal = true, stringVal = "yo"})
timer.performWithDelay(1500, restartLevel, 5, {boolVal = false, stringVal = "iterations!"})

All I’ve done is move the closure, which is called doIt, into the new timer.performWithDelay function. doIt calls the function passed to performWithDelay, along with whatever parameters have been provided.

Because the original timer.performWithDelay accepts an optional third argument (the number of iterations), the new function needs to account for that. To do this, the new function checks to see if the third value passed to it is a number. If it is, then it’s assumed that this is the number of iterations, and the fourth value is the table of parameters to pass along. If the third value is not a number, then plan for a single iteration, and assign the third value passed to the new function to the parameters to be passed on. You can see the iterations in action in the second performWithDelay call.

Here’s a simple main.lua that creates four walls and a bouncing ball:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

local physics = require("physics")
physics.start()
physics.setGravity(0, 0)

-- create wall objects
local topWall = display.newRect( 0, 0, display.contentWidth, 10 )
local bottomWall = display.newRect( 0, display.contentHeight - 10, display.contentWidth, 10 )
local leftWall = display.newRect( 0, 0, 10, display.contentHeight )
local rightWall = display.newRect( display.contentWidth - 10, 0, 10, display.contentHeight )

-- make them physics bodies
physics.addBody(topWall, "static", {density = 1.0, friction = 0, bounce = 1, isSensor = false})
physics.addBody(bottomWall, "static", {density = 1.0, friction = 0, bounce = 1, isSensor = false})
physics.addBody(leftWall, "static", {density = 1.0, friction = 0, bounce = 1, isSensor = false})
physics.addBody(rightWall, "static", {density = 1.0, friction = 0, bounce = 1, isSensor = false})

-- create a ball and set it in motion
ball = display.newCircle( 0, 0, 15 )
ball.x, ball.y = display.contentWidth / 2, display.contentHeight - 80
physics.addBody(ball, "dynamic", {density = 1, friction = 0, bounce = 1, isSensor = false, radius = 15})
ball.isBullet = true
ball:applyForce(100, 10)

local function onCollision(event)
  print(event.phase, ball:getLinearVelocity())
end

ball:addEventListener("collision", onCollision)

A force is applied to the ball, and when the ball hits the bottom wall, it will ‘stick’, which is not the behaviour that we want. As you’ll see from the output of the onCollision event handler, eventually, the y velocity becomes 0, meaning that the object is not moving up or down at all, which creates the effect of sticking.

One other thing you may notice from the terminal output: the x and y velocities follow a consistent pattern from the began phase of the event to the ended phase: one of the values will flip from positive to negative depending on which way the ball was moving before and after the collision. Here’s how it breaks down:

• Bounce to the left: the x value goes from negative to positive
• Bounce to the right: the x value goes from positive to negative
• Bounce downwards: the y value goes from negative to positive
• Bounce upwards: the y value goes from positive to negative

In the example code above, the y velocity toggles between 12.73 and -12.73 (I’m rounding off for the sake of convenience). Then, at some point instead of remaining at 12.73, it becomes 0. The ball is moving downward (positive y velocity) and instead of moving upward (negative y velocity), it stops moving up/down at all.

So the immediate solution presents itself: we know what the y velocity should be, so we can override the calculated value of zero and set it to what it should be. Here’s the new resetLinearVelocity function with the modified onCollision function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

local function resetLinearVelocity(event)
  local thisX, thisY = ball:getLinearVelocity()
  if thisY == 0 then
      thisY = -ball.lastY
  end
  if thisX == 0 then
      thisX = -ball.lastX
  end
  ball:setLinearVelocity(thisX, thisY)
  ball.lastX, ball.lastY = thisX, thisY
  end
end

local function onCollision(event)
  timer.performWithDelay(0, resetLinearVelocity)
end

onCollision will call resetLinearVelocity after a delay of 0 milliseconds - all this does is force Corona to call the function on the next frame. We wait a frame so that we don’t interfere with the calculations being performed by the physics engine, and so that we don’t have to wait for another collision before resetting any values that need it (try calling the resetLinearVelocity function immediately to see the difference).

If the x or y velocity is zero, we just need to set them to the signed opposite of their last non-zero value. The ball object has a couple of new properties, lastX and lastY that stores the values for the x and y velocities, respectively, from the previous collision. If either of the new velocities are zero, then we manually set the linear velocity to the proper values.

All of this is being done by the resetLinearVelocity function. Here’s what it does, in order:

1. It gets the current linear velocity values, storing them in local variables.
2. It checks to see if the current y velocity (stored in thisY) is 0. If it is, then it's set to the negative value ofball.lastY`.
3. The same check is done for the x velocity.
4. :setLinearVelocity() is called. If thisX and/or thisY have changed, then this means the ball should have bounced after the last collision, but didn’t. This will force the bounce.
5. The x and y velocities are stored for the next time there’s a collision.

One inefficiency in the code is that it will call :setLinearVelocity() even if neither value has changed, so you may want to add some conditional logic to only make that call when necessary - I haven’t tested it, but my suspicion is that a couple of if statements will have less overhead than the :setLinearVelocity call, especially in an app with a lot of collisions.

Keep one thing in mind: the physics engine is meant to more or less accurately emulate real-world physics. My guess is that the real problem is that, in real life, the ball is supposed to stop bouncing. The y velocity is simply not great enough for an object of that (simulated) size to bounce off the wall. For example, if you comment out the collision event listener and if you play around with the values used in the :applyForce() function call (e.g. ball:applyForce(100, 30)), you’ll find that the workaround isn’t even required, and the visual effect of the bouncing ball in this case isn’t significantly different from the lesser initial y velocity of 10. However, just because Box2D is meant to model the real world, doesn’t mean you have to use it to do that, so hopefully you can use this to get you out of the ‘sticky’ situations you may sometimes find yourself in with the Corona physics engine.

1
2
3
4

function removeAllListeners(obj)
  obj._functionListeners = nil
  obj._tableListeners = nil
end

The function takes as its argument the object for which you want to remove the listeners. This would typically be a display object, but could also be the global Runtime object - basically anything that could have event listeners attached to it.

After looking at that function, you’re probably asking, “That’s great, but where did these _functionListeners and _tableListeners tables come from, and how did they get the information about the listeners in the first place?” They’re built-in properties of objects that listen for events. Since they start with an underscore, they’re meant to be somewhat private properties, but they’re completely accessible. In an object that has no event listeners, those tables don’t exist, so by setting their values to nil, we’re effectively returning the object to its pre-event listener state.

This sort of thing would be handy if you’re creating objects dynamically, such that they may have a different set of event listeners depending on their specific role. Rather than create a separate property to track the event listeners you need to remove, you can use the above function to take care of this clean-up for you. One word of warning: since these are semi-private properties that aren’t really meant to be exposed, it’s possible that Ansca will at some point change how things work under the hood, and this may stop working. So use at your own risk, etc., etc.

(Also, I’m not suggesting the approach I just described is the best way to architect your application, but it’s possible. And you may want to use this function for extra assurance that you got all the event listeners that were added. I’m just reporting my findings here; what you do with it is up to you!)

If you’re interested: I found out about these tables while playing around with the debugger, specifically the dump command, which as I mentioned in my last post, can yield some interesting findings (There’s also this post on the Ansca forums that shows a whole bunch of information via straight Lua code, rather than using the debugger). If you attach function listeners to an object, you’ll see something like this in the debugger:

1
2
3
4
5
6
7

> dump square
square(table: 0x1c320e0) =
{
  _proxy = userdata: 0x1c320d4
  _class = table: 0x1c1d8f0
  _functionListeners = table: 0x1c36580
}

And there’s _functionListeners. dump that, and here’s what you see:

1
2
3
4
5

> dump square._functionListeners
square._functionListeners(table: 0x1c36580) =
{
  touch = table: 0x1c37590
}

As you can see, the _functionListeners table uses the name of the event to listen for as the key, and the value is a table. You might think that the value would be a function instead of a table, but since you can attach multiple listeners for a single event, Corona uses a table to store all of those listeners. Here’s the output from an object that has multiple touch event listeners:

1
2
3
4
5
6

> dump square._functionListeners.touch
square._functionListeners.touch(table: 0x1a27820) =
{
  1 = function: 0x1a23420
  2 = function: 0x1a23910
}

So, you could use pairs() and ipairs() on these tables to iterate through them and remove listeners selectively. You can also use table.insert() to add event listeners if you so chose. Setting the tables to nil results in the wholesale removal of listeners.

Starting the Debugger

The debugger is part of the Corona SDK, and needs to be invoked from the command line. So, fire up Terminal.app, make sure there are no instances of the Corona Simulator already running, and from the command prompt type:

1
2

# replace /Applications/CoronaSDK with the actual path to your SDK installation
/Applications/CoronaSDK/debugger

The debugger will start the Corona Simulator and prompt you to run the program you want to debug. Once you’ve selected your program to debug, the debugger will pause execution so you can set it up to, well, debug your program. If you just tell the debugger to continue running the program at this point - we’ll see how in a little bit - it actually won’t be terribly useful. That’s because you haven’t told the debugger to do anything. You can do this by setting breakpoints and watch expressions. We’ll look at both of these - and more! - but first, here’s the program that I’m using for the purpose of this tutorial:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

local square = display.newRect( 0, 0, 10, 10 )
square:setFillColor(255, 0, 0)

local function foo()
  print("foo")
end

local function moveSquare(event)
  square.x = square.x + 3
  foo()
  if square.x == 100 then
      Runtime:removeEventListener("enterFrame", moveSquare)
  end
end

Runtime:addEventListener("enterFrame", moveSquare)

The code creates a red square positioned at the 0, 0 point on the screen and an enterFrame listener that moves the square three pixels to the right on every frame. When square.x is equal to 100, the enterFrame listener is removed. (foo() is just a dummy function to help demonstrate some of the capabilities of the debugger.) You can probably already see the bug in this program - since 100 isn’t evenly divisible by 3, the square never stops moving to the right. The simplest approach in this case would be to stick a print(square.x) statement in the function to see the values of square.x. With that approach you end up with a ton of output in the terminal, and in even a moderately complex program you probably have a bunch of other print() statements, so you may not even see the output as it zooms by the screen mixed in with other output. So, we’ll use the debugger to look at a couple of different ways of debugging this application: breakpoints and expressions.

Breakpoints

A breakpoint is a point where you want to pause the execution of the program. When the program hits a breakpoint, it will stop in its tracks to let you use the debugger to examine the current state of the application to figure out what’s going wrong.

The command for setting breakpoints uses the following syntax:

1

> setb <file> <line>

(Note: do not enter the greater than symbol; that symbol is the prompt from the debugger.)

You can create as many breakpoints as you like, on any line of any Lua file in your project folder. Just make sure not to put them on blank lines, or they’ll be ignored. This command will create a breakpoint inside moveSquare():

1

> setb main.lua 9

Once you’ve created the breakpoint(s), you can tell the debugger to continue running the program. The command to do this is your choice of run, continue, or simply c (short for continue). After you type c in the debugger and hit enter, the program will run until it hits a breakpoint. When that happens, the program will pause execution and the debugger will tell you where this happened. So for the breakpoint already set, you’ll see this message from the debugger:

1

Paused at file main.lua line 9

At this point, we can examine the value of square.x:

1

> print square.x

The only difference between this and the standard Lua print() function is that in the debugger you must omit the parentheses; otherwise you can print whatever value you wish to examine. You can abbreviate the command to just the letter ‘p’, so p square.x will give you the same output.

Once execution has stopped at a breakpoint, you can “step” through the code using the following commands:

step (si)

step (or si for short) will advance your progress through the program one line at a time. The short form of the command stands for “step into”. This means that when the debugger encounters a function call, it will “step into” that function and allow you to step through its code.

You can see what I mean by entering si a couple of times in the debugger after execution has been paused at line 9. If you do that, your output will look like this:

1
2
3
4
5
6
7
8
9

> setb main.lua 9
> c
Paused at file main.lua line 9
> si
Paused at file main.lua line 10
> si
Paused at file main.lua line 5
> si
foo

The program paused at line 5 in main.lua, which is the print("foo") statement inside foo(). When the debugger encountered the call to foo() on line 10, it jumped to that function to let us step through it. Once it’s finished there, program flow will return to the function that called foo(), just as it normally would.

(Also, you can see that output from print() statements in your code will be directed to the debugger.)

But what if you know that foo() is unproblematic, and you just want to let it do its thing without having to bother stepping through that function? That’s where over comes in handy.

over (so)

over is the companion to step, and as soon as I tell you that so is short for “step over”, you’ll probably guess what so does. It steps on to the next line in the program, but if that line is a function call, it simply executes that function and continues stepping through the code. In other words, it causes the debugger to “step over” function calls. So the output in the debugger for so will look like this:

1
2
3
4
5
6
7

Paused at file main.lua line 9
> so
Paused at file main.lua line 10
> so
foo
Paused at file main.lua line 11
>

We can see that foo() was called because of the “foo” output from the function, but we didn’t have to manually step through it while debugging. This is handy when we’re sure that a certain function isn’t relevant to whatever bug we’re hunting down.

run/continue (c)

The last command you can use to control the debugger after you’ve hit a breakpoint is the run or continue command (c for short). This command simply lets the program continue to run until it hits another breakpoint or watch expression. This is very handy if you’re only interested in the code immediately after your breakpoint, and don’t want to have to step through all the lines of code between it and the next breakpoint. If you enter the c command in the debugger, you’ll see this output from the program:

1
2
3
4
5
6
7

Paused at file main.lua line 9
> c
foo
Paused at file main.lua line 9
> c
foo
Paused at file main.lua line 9

As you can see from the output, after entering the continue command, the program simply continues to run. foo() is executed, and then when the program hits the breakpoint in moveSquare() again - remember, this is the handler function for the enterFrame event, so it’s getting called 30 times per second, and that breakpoint will get triggered every time - the program is paused.

(If you haven’t noticed it already, check the Corona Simulator window as you enter the continue command; you’ll see the red square move across the screen a little bit after every time you hit ‘enter’. That’s because the code is actually running, so the square is being animated across the screen.)

Deleting Breakpoints

If you’re finished with a breakpoint, but you’re not done debugging your code, you can delete it using the following command:

1

> delb <file> <line>

So to delete our breakpoint, we would enter:

1

> delb main.lua 9

Delete all breakpoints with:

1

> delallb

Listing Breakpoints

The command to see all of the breakpoints that you’ve created in your debugging session is:

1

> listb

As you can see, breakpoints can be extremely handy. But given the current example, you can also see a potential downside: the bug in our code occurs somewhere around the time when square.x is about 100. That means having to sit there and enter continue about 30 times before we finally get to the point in the program that really interests us. That would be tedious. Happily, there’s a nice way to skip ahead in the program to get closer to where we want to be, and that’s by using watch expressions.

Watch Expressions

A watch expression is a Lua expression that is being constantly evaluated by the debugger. As soon as it evaluates to true, execution of the program is paused. So you can think of it kind of like a breakpoint, where instead of specifying a particular line where you want to stop the program, you give the debugger a specific condition.

In our example program, we’re expecting square.x to be equal to 100 at some point, but that’s not happening. So we want to know the value of square.x around that point. The easiest way to do that would be to be able to pause the program as soon as square.x is greater than 99. We can create a watch expression to do that:

1
2
3

> setw square.x > 99
Inserted watch exp no. 1
>

The debugger tells us the number of the watch expression we’ve created. The particular expression can be any valid Lua condition to check - as far as I know, if you can use the expression in a Lua if statement, you can use it in the debugger. So if, for example, we were also fading out the square, we could enter a watch expression like this:

1

     setw square.x > 99 and square.alpha < 0.5

Returning to our original expression, now we can continue the program and wait until our condition is met:

1
2
3
4
5
6

> c
foo
# lots more foos snipped for the sake of brevity
foo
Paused at file main.lua line 10 (watch expression 1: [square.x > 99])
>

Now we’re talking! The program just did whatever it was supposed to do until our condition is true. Now that square.x is greater than 99, the program is paused. So we can print the value we’re interested in and do whatever else we need to help figure out what’s going on. Couple things to keep in mind:

1. As long as a watch expression is true, the debugger will pause execution on every line of the program until either the expression is no longer true or the watch expression is removed. In this sense, it kind of acts like having a breakpoint on every line.

2. Your watch expression can specify local variables. So if there’s a particular variable that’s within the scope of a function, and you want to set a watch expression on that, go right ahead. It doesn’t matter if the local variable doesn’t exist when you create the watch expression. Keep in mind that if you’re in the habit of using the same name for local variables in different functions, the watch expression will apply to all of them.

Deleting Watch Expressions

To delete a watch expression, use the following command:

1

> delw <number of expression to delete>

The expression number is the number provided to you by the debugger after you’ve entered the expression. So in the case of our expression, which we were told was “exp no. 1”, we would enter:

1

> delw 1

If you want to see all the watch expressions you’ve created:

1

> listw

If you want to delete all of the watch expressions you’ve created:

1

> delallw

Other Helpful Commands

There are a few other commands that may be helpful in your debugging efforts. As before, the short form of the command is in parentheses:

• locals (l) - shows you the names and values of all of the local variables in the program.

• backtrace (bt) - shows the function call stack (similar to what you see in the terminal when you have an error in your code).

• eval - basically the same as print

• exec - this command allows you to execute any chunk of valid Lua code in the current context (i.e. with access to all local variables, etc.). For example, when our example code is stopped by a breakpoint or watch expression, you could move the square to any arbitrary x or y position:

  “`bash

  > exec square.y = 200
  nil
  

  “`

  Since a chunk in Lua can be multiple lines of code, one way to enter a chunk would be to type it on one line, separating each statement with a semi-colon. Remember: in Lua a semi-colon is an optional end-of-line marker - you don’t need to put the semi-colon at the end of a line if the line contains only one statement. But if you want to put multiple statements on a single line, you must separate them with a semi-colon. For instance, the following will create a large green square on the screen:

  “`bash

  > exec local rect = display.newRect(100, 100, 100, 100); rect:setFillColor(0, 255, 0)
  nil
  

  “`

• dump (d) - this is like print on steroids. It will give you detailed information about whatever variable you want. For example, when execution of the test program is paused in the moveSquare function, you can dump the value of any variable that exists at that point in time (remember, use locals/l to get a list of those). So you can take a look at the event object that gets passed to moveSquare like this:

  “`bash

  > dump event
  event(table: 0x2a443e0) =
  {
      name = "enterFrame"
      time = 8817.956
  }
  

  “`

  This can give you access to a lot of detailed information about the current state of your application (and also lets you discover some potentially interesting things about what’s going on under the hood in Corona, if you’re the nosy type and start checking out anything that comes to mind).

• help - a list of all the commands available in the debugger.

Incidentally, some of the functionality in the debugger seems to be added on top of RemDebug, such as being able to list local variables and the backtrace. (One thing that has me confused is the frame command - not really sure what that one does, but I’d like to find out one day.) I think that’s pretty cool - they’ve put effort into something that ships with the SDK and that most users will probably never touch.

(Maybe if you all start to use the debugger and submit suggestions for improving it, we’ll see even more cool new features added, like having breakpoints and watch expressions persist between debugging sessions, the ability to restart a debugging session without having to exit out of Simulator and debugger completely first, and maybe a nice GUI on top of it all.)

Conclusion

A lengthy post, to put it mildly, but I hope you found it interesting and educational. The debugger hides a lot of power behind a not very user-friendly interface, and I think that the time spent getting familiar with it will easily repay itself the first time you can use it to track down a particularly nasty bug.

If you want to see the results in action, I encourage you to grab Knight’s Puzzle from the Android Market. And click on some ads while you’re at it. My boys’ RESP isn’t going to grow by itself, you know.

The first thing you need to do is create an InMobi account, as this is the only ad provider that is currently supported. That’s pretty straightforward so I’ll assume you don’t need to be walked through that.

Once that’s done, you can create your app from the “My Sites/Apps” screen:

One thing to bear in mind: once an app is created, you cannot delete it. I find this kind of annoying - you can see in the above screen shot that I tried creating an iOS test app, as well as a web app, when I was getting things set up. I’ll now be staring at these unneeded apps for the entire time I have an InMobi account. Ah well.

Here’s the information required for an Android app; the requirements for an iOS application are pretty much the same (substitute App Store URL for “Market URL”):

The package name is the reverse-DNS style name that you’ll use when you’re building your Android app from within Corona (e.g. com.bar.foo.mygreatgame). The Market URL follows a standard format: http://market.android.com/details?id= followed by the reverse-DNS package name. I’ll assume you don’t need me to explain the app name and description.

Once you’ve created your app, you’ll be provided with an App ID. You can find this on the “App Details” page. You’ll need this in a little bit to plug into your Corona application. Ignore the reminders to download the InMobi Android SDK.

A word of warning: before they start serving ads to your app, InMobi must approve the app. This seems to apply even when you set your ad code to test mode - more on that in a bit. When I first created the Knight’s Puzzle entry, the game wasn’t yet live in the Android Market, so I left the App URL empty. But, InMobi wouldn’t begin the approval process because I hadn’t provided all of the required information. Since the Market URL is easy enough to figure out in advance (see above for the formula), I plugged that in and waited to see what would happen. I received notice that my app had been rejected because of an invalid URL - this makes sense, given that the app wasn’t live yet (which I’d indicated when I first filled out the form), but it makes it kind of tough to test the ad integration before the app goes live. The other strange thing was that it took about 12 days to find out that the app was rejected. I’m pretty sure that’s some sort of outlier - or at least I hope it is. And yes, I could have made an inquiry with InMobi to find out what was going on. In any event, after Knight’s Puzzle went live in the Android Market, I resubmitted the app to InMobi and it was approved within a matter of minutes, so there must be some sort of automatic check that happens after an app is submitted.

Unless I did something wrong - which is entirely possible - the upshot of this is that to capitalize on the initial downloads of your app, you want to make sure that your ad code is as bulletproof as possible. This is less of an issue with Android, because you can upload an update and it will get picked up almost immediately, but the lag with iOS approvals can cause problems. Happily, Ansca has done a great job of making the integration of ads as easy as possible. I hit only minor speed bumps, which I’ll mention in a little bit.

Here’s the basic code to get you ready to show ads:

1
2
3
4
5

local ads = require("ads")
local adNetwork = "inmobi"
-- the value for appID is the string assigned by InMobi after you create your app
local appID = "adflksadjflkasdfjoasgu" -- not a real app ID
ads.init(adNetwork, appID)

First, we include the ad module. Next, the name of the ad network and the app ID are set. Right now, InMobi is the only ad network supported by the Corona ad API, so you can certainly skip creating the variables and just set the adNetwork and appID as literals in the ads.init() call. Once that initial code is in place, then you can display an ad using the ads.show() method. Here’s where I started:

1
2
3
4

local showBanner = function()
  local adX, adY = (display.contentWidth - 320) / 2, display.contentHeight - 48
  ads.show( "banner320x48", { x = adX, y = adY, interval = 60, testMode = false } )
end

The first parameter passed to ads.show() is the size/type of ad you want to show. The second parameter is a table of optional values. The first values are the x and y positions of the ad, the third is the refresh rate, expressed in seconds (aside: this is in seconds, timer.performWithDelay() intervals are in milliseconds; that sort of inconsistency drives me bonkers).

The last argument sets the test mode - I’m still unsure of its purpose. During initial testing, the ads.init() call would fail because the app wasn’t live in the Android Market yet. Perhaps I’m missing something? The table is optional. Without it, you’ll get an ad appearing at the 0, 0 position of the screen that will refresh every ten seconds.

And that’s all you need to get your ads showing. The ads seem to behave like a native widget, rather than a Corona display object, which means that they’ll appear on top of whatever other display objects you have in your app. If you want to remove the ad at any point in your application, all you need to do is call ads.hide().

You’ll notice that I’m requesting an iPhone-sized ad, since the API reference for ads.show() doesn’t list any Android-specific sizes. Accordingly, I initially tried to position the ad according to the size I requested (centred on the screen, 48 pixels up from the bottom of the screen). This is where I hit a couple of issues:

1. It looks like InMobi will override the ad size you’ve requested in some cases. In this case, it displays a banner ad that is 480 pixels wide by 72 pixels high, instead of the size requested. So the positioning was off because of that.

2. After I modified the values of adX and adY accordingly, the ad was still showing up in the wrong position. It turned out that passing in the value of variables for the ad position wasn’t working, for some reason. Instead, I had to inline the calculation. Once I did that, the ad shows up exactly where I want it:

1
2
3

local showBanner = function()
  ads.show( "banner320x48", { x = 0, y = display.contentHeight - 72, interval = 60, testMode = false } )
end

I didn’t change the value for the ad that I’m requesting. I probably should do this, or at the very least do some device sniffing and display a more appropriate ad (e.g. a larger ad for tablet devices).

Another thing to bear in mind: when an ad request fails, it fails silently, at least from the user’s perspective, and the area reserved for the ad will remain ‘blank’. So, you have to plan for the possibility that no ad will appear. What will the user see in your app if the space reserved for an ad isn’t showing an ad? In the case of Knight’s Puzzle, it’s not really a problem, since the game play is confined to a smaller area of the screen. But for other games, you may need to plan for the possibility that the ad request will fail.

For example, assume you’re building a game with a lot of enemy objects moving around the screen. If your code assumes an object is off-screen when it reaches the area reserved for an ad, but there’s no ad there, what happens? One approach may be to code your app as if the ad will never be there, and accept that when an object is in the ad space, it’s still “in play”. This can have consequences for some types of games, however - for example, you may not want your enemy planes shooting at the player from underneath an ad, since the bullets can look like they’re coming out of nowhere. So perhaps in that situation, the planes keep moving until they’re completely off the screen, but don’t shoot at the player unless they’re in the ‘safe’ (i.e. non-ad) area. There may be other approaches depending on the specifics of your game, but it’s something you should keep in mind.

Handling this sort of thing would be easier if Corona dispatched an event indicating whether an ad request was successful, so hopefully we’ll see that added in a later version (or if InMobi served up house ads, the way AdMob does, then you wouldn’t need to worry about a less than 100% fill rate, since the unfilled requests could be filled with house ads).

All in all, I’m pretty pleased with the ad integration in Corona. Now go play Knight’s Puzzle so my kids can go to a good university!

You can grab the code on GitHub. It includes a sample main.lua that will show you how to use the functions, but if you’re familiar with AS3’s Array methods, then you can probably skip that altogether.

If you are familiar with the Array class, then there are a few things you’ll still need to remember:

• I’ve renamed Array.concat to table.concat_as3, to avoid conflict with Lua’s built-in table.concat method.
• Since tables in Lua are 1-based, wherever you’d see a 0 in the docs for the Array class, just substitute a 1.

The library does some basic error checking (e.g. to make sure you’re calling the method on an actual table), and will use the same default values as the Array methods for optional parameters.

If you catch any bugs, or if there are any other Array methods you think should be added to the library, let me know in the comments!

For example, if you want to insert a value into a table, you’ll often see the code written like this:

1
2

local myTable = {"a", "b", "d"}
table.insert(myTable, 3, "c")

This is different from, say, ActionScript, where the equivalent code would look like this:

1
2

var myArray:Array = ["a", "b", "d"];
myArray.splice(2, 0, "c");

Ignoring the differing syntax between insert and splice for the moment, notice that the splice method is called directly on myArray, which determines the scope. In Lua, the insert method is akin to a static method of the table module, and the first argument is the table that will have the value inserted.

If you want your Lua to look more like ActionScript (or JavaScript, etc.), then all you need to do is make one simple change to your code:

1
2

local myTable = {"a", "b", "d"}
myTable:insert(3, "c")

Basically, using the colon before the function call is for convenience: it lets you skip having to pass the object as the first argument. When you’re writing functions in your own code, the colon serves the same purpose:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

local myRect = display.newRect(0, 0, 100, 100)

function myRect.rotateTo(self, angle)
  self.rotation = angle
end

-- These two calls are functionally (ha ha!) equivalent
-- Pass myRect explicitly
myRect.rotateTo(myRect, 45)
-- myRect is the implicit first argument
myRect:rotateTo(45)

function myRect:fadeTo(newAlpha)
  -- 'self' isn't declared, but it's the implicit first parameter because of
  -- the colon in the function declaration
  self.alpha = newAlpha
end

-- again, these do the same thing
myRect:fadeTo(0.5)
myRect.fadeTo(myRect, 0.5)

To employ this method, here are the steps to follow:

1. You must have your Corona app set up in TextMate as a project.

2. When you have the project drawer open, make sure that no files in the drawer are selected (just click on some white space within the drawer).

3. Click the ‘info’ button at the bottom of the project drawer. You should see this window pop up:

4. Click the ‘+’ button to add a new environment variable. Name the variable SDK_PATH and set the value to the location of the SDK version you want to use for this project. Make sure to leave off the trailing slash! Like this:

5. Close the window and when you hit Cmd-R from within TextMate, it should launch your project in the SDK version you’ve specified. If nothing happens, then you probably have a typo somewhere. Right now the script isn’t doing much in the way of sanity or other checking, so it’s up to you to make sure things are set up properly.

Octopress, if you’re not already familiar with it, is a framework for Jekyll. If you’re not familiar with Jekyll, it’s a Static Site Generator. Instead of querying a database every time somebody requests a particular web page and building it on the fly, it pre-generates all of the pages on the site, and then rsync (or whatever you like) is used to sync the local build with the remote server. The result is nothing but plain old html, etc. on the site. Certainly, that doesn’t make my site hack-proof, but it has eliminated the primary attack vector, and that’s a good thing.

I liked using WordPress, and I’m glad that I can set up and configure a WP-based site if I need to. But in the long run, for my own needs, it’s overkill. The extensibility via plug-ins makes it attracting, but is probably also a significant cause of my problems.I run another WP-based site that has no plugins installed, and it’s clean of spam at the moment (correlation does not equal causation and all that, I know). I’ve no doubt that it’s entirely possible to run a WP-based site and keep it entirely clean of spam, etc.

However, since I’m not a frequent blogger, I’m sure that my WP install is out-of-date more often than it should be, which opens me up to attacks. I could and should have been more vigilant, and this isn’t a criticism of WordPress, it’s more the realization that WordPress isn’t the tool that fits my needs (if I chop off my hand because I’m using a chainsaw to slice bread, it’s not the chainsaw’s fault). In my personal battle against spam on this site, as a very smart computer once said, “the only winning move is not to play.”

So, all that said, here are some notes/comments on the migration process and my experience so far. A lot of this is me stumbling down a sometimes not terribly well-lit path, so you may have an easier time of it:

• The installation process uses Ruby and installs a bunch of stuff via gems. I’ve fiddled around with Ruby and gem installation before while doing some client work, but my use of the phrase “bunch of stuff” should be a pretty clear indication that I’m not a Ruby developer. Following the instructions went reasonably well. I still need to (figure out how to) upgrade my Ruby installation, and at some point I installed something via `sudo` when I shouldn’t have, so I need to use `sudo` to run the rake tasks.
• Installing Octopress requires installing RVM, which is I think where I hit my `sudo` issues before. Having tried the reinstall as root, I’ve hit some confusing points. The install notes for RVM recommend installing Ruby 1.7.2, but then when it comes time to review the `.rvmrc` file for the site, I’m told I need to install 1.9.2. This is easily fixed by following the instructions in the install notes and just substituting the higher version number, but it would be nice if this were all a little clearer from the get-go.
• Even after that was done, I still get prompted to trust the `.rvmrc` file every time I switch into that directory.
• The instructions say to do `bundle install` but the bundler gem isn’t installed. I installed it as root, but that doesn’t seem to be helping. Installing it via `sudo` seems to work, so I’m not sure why installing it as `root` didn’t. But at least it works!
• For importing my existing WordPress posts, I exported an xml file from WordPress and then used this script to get the data out. The script doesn’t import absolutely everything - I’ve lost comments, categories, and various other metadata-y bits. This isn’t a big deal because a) my blog doesn’t get a lot of (non-spam) comments, and b) it’s possible that the spam injection affected the database itself, so I’m inclined to think it’s best to leave some of that information in the db where it can’t do any more harm. One other note if you use that script: you need to change the value for ‘layout’ from ‘blog_post’ to just ‘post’.
• Related to the above point, the support for Octopress is fabulous. I hit the blog_post/post issue, and went to the Octopress support page, which is essentially a chat application, and Brandon Mathis seems to always be there. My question on the above was answered in about two minutes, and some additional helpful information was offered along the way.
• One thing I’m still figuring out is where Octopress stops and Jekyll starts, so to speak. For example, I’ve hit an issue where the older posts aren’t getting rendered properly because Jekyll by default uses a particular template for those pages. I’ve already bothered Brandon about this, but as I kept looking into it, it seems like it’s an issue with Jekyll, not with Octopress, per se.
• The documentation for various Jekyll-related things could be, um, a little better, let’s say.
• There are other import methods, including extracting data directly from your WordPress database. I wasn’t too concerned about getting absolutely everything out of the db, so I didn’t really mess around with these too much.
• The posts didn’t need to be cleaned up overly much at that point. Fixing a few paths for image tags, and changing the formatting of code snippets to use the built-in method, but that was all relatively quick.
• I’m not entirely sold on markdown just yet. Seems great for some things, but there are some things that it just doesn’t handle. I know that I can always fall back on writing actual HTML, so it’s not really an issue.
• Since Jekyll is the blogging framework behind Github, its support for code snippets is excellent as you’d expect. Equal or better the WordPress plugins that I’d tried before.

Overall, was this harder than setting up a WordPress install? I’d say a little bit, although I don’t really remember how long it took me to set up WordPress the very first time, for what that’s worth. And while writing this post, I took some time to set up another blog - I’m planning to start blogging at my old osadchuk.org domain one of these days - and that went much more smoothly than the first time. Learning curves and all that. Overall, for a site with about 135 posts and a handful of pages, I’d say that the whole process of installing Octopress, importing and cleaning up the data, skinning the site to resemble the WordPress version, and going live took about eight hours. I’m considering that time very well spent.