Getting Started with iOS

by Jon (Updated on 2014-12-07)



  • System Requirements
  • Step 1: Install Xcode
  • Step 2: Install Xcode Additions
  • Step 3: Test a Game in the iOS Simulator
  • Step 4: Test a Game on your iOS Device
  • Next: Set up Certificates
  • How to Get Help
  • Troubleshooting

System Requirements (as of 2015)

  • Stencyl 3.2 or later
  • iOS Developer License from Apple
  • Mac OS X Mavericks (10.9) or later
  • Xcode 6.x or later
  • An iOS device with iOS 8 or later

You must have a Mac to test and publish iOS games. Although your iOS device must have iOS 8 or later, you can push your app to older devices by exporting an IPA and installing the app through iTunes on those other devices.

Note: Some users have succeeded in testing on iOS devices with older versions directly from their computer. Your mileage may vary.


Step 1: Install Xcode

We recommend installing Xcode directly from the Mac App Store. This guarantees the latest version and simple, in-place updates.


Alternatively, you can grab it from Apple's Developer Site.


Warning: Do not install Developer Previews of Xcode. We do not support them. If you insist on using them, make sure that the folder in which the install resides is called "Xcode" rather than "Xcode-DP-XXX".


Step 2: Install Xcode Additions

After installing Xcode, launch it. Then, do the following.

  1. Open up Preferences (Xcode > Preferences).
  2. Flip to the Downloads page.
  3. Under Components, install Command Line Tools and any iOS Simulators that show up.


After they finish downloading, close Xcode.

Tip: If this is your very first time developing games on iOS, you should add your device to Apple's registry. To do this, open up Window > Organizer. Select your device from the DEVICES section of the left pane. Click Add to Member Center (wording may change between versions).


Step 3: Test in the iOS Simulator

Now, launch Stencyl and create a brand new game with a blank scene. The game's name and details don't matter -- you'll just be testing that the iOS Simulator works.

  1. Launch Stencyl.
  2. Click Create a New Game.
  3. Pick Blank Game. Click Next.
  4. Provide a name. Leave everything else as-is. Click Create.
  5. The game now opens up to the Scenes listing. Click Create New (the green button).
  6. Provide a name for the scene. Click Create.
  7. Save the game.
  8. Switch the Platform dropdown's value to iPhone Simulator (3.5" Retina).
  9. Enable the Log Viewer from the menu (View > Log Viewer).
  10. Click Test Game.

Now, the app will build for a while, depending on how fast your computer is. With the Log Viewer, you can see new lines continually appear, assuring you that progress is being made.

Tip: If you notice that lines stop appearing, the build process may have errored out. Consult our Troubleshooting guide for help.

At the end of the process, the iOS simulator will automatically launch the game.


Explained: Why does it take so long to build the app the first time?

Stencyl is based around Haxe. In order to build native iOS apps, Haxe is translated to C++ which in turn is compiled to machine code. Although the Stencyl engine is compact, the Haxe code it depends on is large and has to be re-compiled for each new game. We don't think this is optimal, but that's how it is right now. Mercifully, this is only the case the first time you run a game on a given platform (where iOS Simulator and iOS Device are considered separate platforms). Second runs and onwards are much faster. Flash games are not affected by this quirk.


Step 4: Test on an iOS Device

Now, let's do the same thing except on an iOS Device. Using the same game, do the following.

  1. Plug in your iOS device to your computer.
  2. Switch the Platform dropdown's value to iOS Device.
  3. Click Test Game.

Again, it will go through a lengthy build process like explained above.

At the end of the process, the app will auto-launch on your iOS Device.


Next: Set up Certificates

Read our comprehensive guide on how to set up certificates, so that you can publish your game to your friend's devices and the App Store.


How to get Help

Our official documentation. Stencylpedia provides articles and videos covering the essentials.

Public and subscriber-only forums. This is the official way to seek support.

Billing / Account Support
If you have problems with your account, or run into any billing-related issues, contact us.



We've devoted an entire article to troubleshooting common issues with iOS, Xcode and Certificates.

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!


In reply to the last comment by "sp3416".

I only have the stencyl indie package at the time of writing this comment and can still test apps, but not publish them.

0 1 week, 2 days ago
Just to be clear, if you only want to test the game, you still have to have Stencyl pro to be able to do that?
0 1 month, 1 week ago
Step 2
With Xcode 5.1.1 you can install only iOS 6.0 and 6.1 simulator… I can't find the iOS 5.1 simulator, I think it is not available anymore. Is it?

1 1 year, 3 months ago
When I compile I got the following error at the log viewer:

[LOG] Reason: image not found
[LOG] Finished building for iOS (or errored out): 1

How can I solve this?

2 1 year, 6 months ago
This article will be completely rewritten to bring it up to 3.0 compliance.
0 1 year, 8 months ago
@Leaufai You must be fun at parties.
0 1 year, 10 months ago
the snow leopord link takes you to the general xcode page where it lets you download for lion. Could you update the link please ? thanks in advance
0 2 years, 10 months ago
How to games get published?

should be either be:

How do games get published?


How to get games published?

1 3 years, 3 weeks ago
I agree with hephaistos. I would like to be able to make an MMORPG.
0 3 years, 1 month ago
Location services, notifications, social stuff pretty please~
0 3 years, 3 months ago

Sign In to Comment