Debugging Your iOS Game

by Jon (Updated on 2014-02-02)

This article is an early draft and isn't complete. We'll expand it as Stencyl 3.0 becomes more widely adopted.


  • Introduction
  • Logs
  • Game Compiles "Forever"
  • Understanding Crashes
  • Viewing Device Logs



At some point during testing, your game may quit unexpectedly to the home screen, spew errors in the log or act in an unexpected way. It's rare for a game to run perfectly the first time you make it. Bugs and crashes are an inevitable part of the game development lifecycle. This guide exposes you to the various tools avilable for debugging your games.



Your game's logs record much of what goes on while your game is running as well as any additional information you decide to add in.

Logs come in two forms - the ones that Stencyl / Haxe emits and the ones that the iOS device emits. In most cases, even in the event of a crash, the Stencyl / Haxe ones provide all the info you need.


Viewing the Logs

Turn on the Log Viewer by selecting View > Log Viewer from the main menu.


Adding Info to the Logs

To add information to the logs, use the print block, located under Flow > Debug in the palette.

This can be particularly useful when something goes wrong and you want to know the value of an attribute, for example.


Game Compiles Forever

Before your game runs, it has to compile. Errors in your behaviors are generally caught by Stencyl, with the offending behaviors automatically opened up. Most of the time, you're able to figure out what's wrong. That's not what we're focusing on here.

What we're focusing on are the cases where your game gets stuck in the "Compiling..." state seemingly forever. The first thing to realize is that your game isn't stuck. It hit an error that we couldn't detect for reasons like these.

  • Errors with iOS certificates.
  • Errors with signing an app.
  • Internal Haxe errors.
  • Couldn't establish connection with device.

Although we try to scan and identify common errors, some inevitably slip through the cracks. Here's what you can do to stay informed during the process, so you aren't left waiting forever.

1) Turn on the Log Viewer before you run a game. (View > Log Viewer)

2) Run your game.

3) The Log Viewer should continually spew out new lines. It may slow down at times, but progress should be steady.

4) If it stops, scan the last page or so worth of lines for errors. 

5) If you locate an error, try to understand what it means and search on Google. This is most useful for iOS certificate errors where the solutions to such issues are well documented on Q&A sites such as StackOverflow. 

6) If you can't figure out what's going on, export your logs and ask a question on the forums.


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.


Viewing Device Logs

If you're on Windows (as a tester for an app) or even on a Mac, viewing the console logs for your device when it's running your app is useful to know. There are various ways to do this.


Method 1: Xcode

Xcode's Organizer (Window > Organizer) lets you browse your device's past logs.

Pros: Quick access.
Cons: Not available to Windows users.

Method 2: Use the Console App

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


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

Method 3: Use iTunes


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.
Note: In Stencyl 3.0 and above, crashes tend to occur in Haxe code, so they show up in the regular Stencyl logs. The section below no longer applies because our engine is no longer writte in Objective-C, but it may be useful in the few cases where you need to go to the low-level logs.

Skip down to Debugging Tips.

When you test your iOS game, we recommend launching Console (using Spotlight - the search icon the top-right corner of your Mac). 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.

Thread 0 Crashed:: Dispatch queue: com.apple.main-thread
0   libobjc.A.dylib                  0x017da09b objc_msgSend + 15
1   AppScaffold                      0x000276b4 -[Script sameAs:two:] + 36 (Script.mm:88)
2   AppScaffold                      0x00008697 -[HUDDrawer render:x:y:] + 327 (HUDDrawer.mm:65)
3   AppScaffold                      0x00023307 -[Behavior render:x:y:] + 103 (Behavior.mm:202)
4   AppScaffold                      0x000282dd -[BehaviorManager draw:x:y:screen:] + 221 (BehaviorManager.m:147)
5   AppScaffold                      0x00051a12 -[Game render:] + 242 (Game.mm:1689)

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.


Debugging Tips

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 the Stencyl's Log Viewer (or Mac's 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, report it on the forums and include the following info.

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) If possible, generate a simple test case game that demonstrates the issue. This forces you to understand the issue, making a resolution a lot quicker and easier for everyone.

Disclaimer: All articles are geared towards Stencyl 3.0 and above. Use comments to provide feedback and point out issues with the article (typo, wrong info, etc.). If you're seeking help for your game, please ask a question on the forums. Thanks!


You actually can get xcode on Windows. It takes a couple of hours but you don't have to do any coding and if you just follow the steps as told you will have xcode on your new "Mac". Well watch the video on how to download VirtualBox, at this link www.youtube.com/watch?v=LGUfa2HIx0E . Then you open your new Mac, and download xcode in the Mac Store. How does this process work? Virtualbox is an emulator software that lets you animate other devices on your device.
0 7 months, 5 days ago
Your mobile optimization article linked to this page stating we would learn how to watch memory usage and see how to reduce it. This article doesn't contain any info on the subject.
0 1 year, 2 months ago
The first time I see "compiling", I hit CTRL-S for save, and it finishes that operation quickly. Then when I ask it to compile again it is much more cooperative.
0 1 year, 5 months ago

Sign In to Comment