Debugging Your iOS Game

At some point during testing, your game may quit unexpectedly to the home screen. This guide explains what to do if this happens.

Viewing Device Logs on Windows

If you're on Windows or even on a Mac, viewing the console logs for your device when it's running your app untethered from Xcode is very useful. There are various ways to do this.

Method 1: Use the Console App

This app displays your device's console logs. Useful if your game crashes, and you don't know why.

http://itunes.apple.com/us/app/console/id317676250?mt=8

Pros: For quick checking
Cons: Hard to get the info off the device. E-mailing it to yourself is your best bet.

Method 2: Use iTunes

http://aplus.rs/apple/how-to-find-crash-logs-for-iphone-applications-on-mac-vista-and-xp/

Pros: Better for generating bug reports or a more detailed look
Cons: Harder to get to because you have to hook the device up

Understanding Crashes

Crashes are errors in your game’s logic or the Stencyl engine that cause the game to suddenly quit. Many types of errors can cause crashes. The most common ones include the following:

•    Referring to something that no longer exists, such as a dead actor.
•    Doing something illegal, such as dividing by 0 or attempting to grab an element from a list that does not exist.
•    Performing an operation on something that doesn’t support that operation.

When you test your game, the OS X Console app pops up. Don’t close this! It’s a useful window that displays your game’s output and crash information.

When a crash happens, the iOS simulator (or Xcode, if you’re testing on the device) will generate a crash log and sometimes display the stack trace, the sequence of events that took place before a crash, for the error in Console.

Crash Logs: Where to find them

Crash logs describe exactly what led to the crash. You can find them in the Console’s sidebar under User Diagnostic Reports.

To locate the Crash Log so you can attach it to a forum post or e-mail, right-click the entry, and either select Mail or Reveal in Finder.

Stack Traces: What caused the error?

A stack trace is the sequence of lines of code that the engine executed before the crash, where the items at the top happened LAST, and the items toward the bottom happened FIRST.

Don’t fret over the details.

The key takeaway is to recognize a stack trace when you see one. Sometimes, but not always, you can recognize a behavior’s name from the stack trace and begin your investigation there.

In this case, the “HUDDrawer” behavior (shown on line 2 above) is at fault, so you would check that out.

The difference between a stack trace and a crash log is that a stack trace is part of a crash log. A crash log can contain multiple stack traces and other information.

How to Effectively Debug Your Game

Putting the elements discussed previously together, you can now debug your game when it crashes. Here’s a summary of what to do:

Step 1: Make the crash happen again (“repro,” short for “reproduce,” the problem)
This will cue you in on what actually caused the problem.

Step 2: Examine the game logs and stack trace in Console
See if you can recognize your behaviors. Is it something you can trace back to your game and fix?

Step 3: Tinker with your game to isolate the issue
If you can’t recognize the faulty behavior, disable suspicious behaviors, based on what you know causes the crash, until the game no longer crashes.

Once you’ve figure out the offending behavior(s), try to narrow it down to particular blocks, if possible. If you are unable to fix the issue, or if you think it’s a problem on our end, follow the instructions below.

If all else fails...

If you get stuck or discover that the issue is beyond your control, contact us on the forums.

Provide the following:

1) Crash Log (link back to above)

2) Exact steps taken to make your game produce the crash. If the crash happens randomly, let us know.

3) A ZIP of your game’s project, if possible. If not possible, e-mail us the project or generate a simple test case game that demonstrates the issue.

Commenting Guidelines