As of late 2021, we are in the process of updating Stencylpedia and fixing up outdated & broken content. Thanks for your patience!







Upgrading to Stencyl 3.0

by Jon (Updated on 2015-10-23)

Note: Stencyl 3.4 (and now, even later versions) is now the current version of Stencyl. We'll be taking this article down in the future.


  • Introduction
  • How to Upgrade to 3.0
  • Upgrading your Games
  • Major Features
    • New Platforms: Android, Native Desktop
    • Haxe - Unified Programming Language
    • Simple Physics
    • Extensions
  • Changes to iOS
    • Better Workflow
    • Universal Apps & Scaling
    • Handling Touch Input
    • Atlases
    • Drawing Text
    • Events for Purchases, Ads & Game Center
  • Changes to Desktop
    • Native, Hardware-Accelerated Apps
    • Store-Ready Apps
    • Full Screen Mode
    • Changes to Sound Playback


Stencyl 3.0 brings Stencyl fully into the modern landscape of cross-platform game creation, through the support of every major platform, including iOS, Android, Flash, Windows, Mac and Linux.

Stencyl 3.0 is more than going cross-platform, though, it introduces a bevy of improvements to mobile, web and desktop publishing as well as some changes for existing developers to note.


How to Upgrade to 3.0

To upgrade to Stencyl 3.0 and beyond, you must download it in full from our site. For best results, do the following.

  1. Back up your existing games. The simplest way is to ZIP up your games folder.
  2. Uninstall Stencyl.
  3. Download Stencyl 3.0.
  4. Install Stencyl 3.0.

After upgrading to Stencyl 3.0, upgrading involves redownloading the app in full each time. This may not be as convenient as our prior patch-based solution, but it makes it significantly easier for us to deliver automated, regular, timely updates and in the long run, is a win-win for all. Thanks for your understanding!

Note: It is OK to have both 2.0 and 3.0 installed. It is not OK to have them open simultaneously. It is also not OK to open a game in 3.0 and then reopen it in 2.0.


How to Upgrade your Games

Note: All sample games that we shipped with 2.0 are incompatible with 3.0. Grab the new ones from here.

1) Recommended - Back up your game first.
2) Open your game in Stencyl 3.0.
3) Save your game.

Beyond that, you may run into some issues when attempting to run the game for the first time in 3.0. The following is a checklist of things to consider when bringing your 2.x based game to 3.0.


FAQ: My game never runs and shows "Compiling" forever.
See this article on how to deal with this. Your game is not compiling forever.


Clean your project.
Select Run > Clean Project from the main menu before running your game in 3.0 for the first time. This will remove legacy output that can sometimes trip up Stencyl.


Does your project include ActionScript code?
If your project includes code, you'll have to port it from AS3 to Haxe. Likewise, if you used any Flixel-specific classes (references to FlxG for example), you'll need to figure out what to do on your own. If you don't know how to code, you'll either have to seek help on the forums or drop the behavior in question.


Building for mobile or desktop? Import OGG copies of your sound.
Due to the technology change, Stencyl now requires OGG format sounds for all non-Flash games. The Sound Editor now includes a second import field that accepts OGG.


Update your Pre-Shipped Behaviors.
If you used any Pre-Shipped Behaviors, we recommend updating all of them. Since Pre-Shipped Behaviors are *copied* to a project upon use, you have to manually remove them from the game and reattach them to the desired Actors and Scenes.


Block Changes
Some blocks have changed or have been removed. For example, Single-Touch blocks are now deprecated in favor of using our regular mouse blocks. Stencyl converts these blocks to the new form, but it helps to double-check that that's the case if something seems off.


Common Gotcha - Handling Collisions
When working with the “Collision Group for colliding shape” block, be sure to compare groups directly, rather than comparing the textual name of the Group, which can lead to bugs and crashes.

(This is the right way)

(This is the wrong way, don’t do this!)



This isn't the extent of what you may have to do, but it is a list of the most common pitfalls in the process.

If you get stuck at any time in the upgrade process, please post on the forums and provide logs.

One last tip - if your game is giving you lots of trouble, you may want to consider removing all behaviors from it and, using a second computer with Stencyl + the game open, rebuilding that portion in 3.0. You may spend less time doing that than trying to struggle the other way.


Other Changes to Watch For

  • StencylForge, for compatibility reasons, does not list some resources in Stencyl 3.0 that were built for 2.0.
  • The Flixel console no longer exists in-game. It's moved to the Log Viewer, a window you can activate from the main menu (View > Log Viewer).


Note: Our coverage of the upgrade process ends here. Everything below covers the changes between 1.x/2.x and Stencyl 3.0.

Major Features

New Platforms: Android, Native Desktop

Stencyl has officially gone cross-platform and now supports 5 commercially important platforms including iOS, Android, Mac, Windows and Flash.

Publishing for Android 
Publishing to the Mac App Store
Publishing a Desktop app

Haxe - Unified Programming Language

Stencyl had adopted Haxe as its official programming language. Haxe is similar in syntax to ActionScript and JavaScript. It converts to Flash, C++ and JavaScript, enabling native apps for all major targets.

If you’re a programmer and are interested in coding in Haxe, read the transition guide for details.


Simple Physics

In order to support a broader array of games that don’t require physics, Stencyl 3.0 introduces a “simple physics” mode that provides enhanced performance and box-only collisions as an alternative to Box2D physics.

Read our Simple Physics guide for details


Stencyl 3.0 supports user-built extensions to the engine. These extensions can augment the engine’s functionality, import external libraries and hook in native functionality for mobile devices.

Browse the Extensions Collection
Make your own extension


Changes to iOS Publishing

Better Workflow

Testing on a Mac has been simplified. Apps run directly on a device without going through Xcode, and there is no longer a MAC address requirement to run on a device.

Universal Apps & Scaling

Deploying an app that looks and runs great on all iOS and Android devices is simpler.

Stencyl’s engine will select an appropriate “scale” for the game to run at depending on the device, and you have control how the frame is shown via a rescaling mode, after that scale is picked.

Read our App Scaling guide for details


Handling Touch Input

Stencyl 3.0 simplifies touch detection. In the past, you had to detect touch using a separate set of touch blocks. In 3.0, you just use the mouse blocks instead.

Read our Touch Input guide for details


Atlases were somewhat of a pain to work with in past releases. That is now a thing of the past in 3.0, where the size restrictions are gone as well as the hardcoded limit on how many you could make.

Drawing Text

In past releases, we discouraged using the “draw text” block to draw text on mobile apps due to performance reasons. This is no longer the case in 3.0.

However, if you prefer the old way, labels remain available through a pre-installed extension that you can enable.

Read our Labels guide for details.

Events for Purchases, Ads & Game Center

We’ve added Events for In-App Purchases, Ads, and Game Center. Particularly for purchases, these are essential pieces of the puzzle that are finally in place.

iOS Purchases Guide
iAds Guide
Game Center Guide


Changes to Desktop Publishing

Native, Hardware-Accelerated Apps

Stencyl 2.0 introduced desktop publishing through the use of Adobe’s technologies. Stencyl 3.0 changes that around by going the native route.

Apps are truly native (cross-compiled to C++) and use hardware-accelerated graphics. They run significantly faster than their web and mobile counterparts.

Store-Ready Apps

Stencyl-made desktop apps are fully ready to be published to major app stores, including the Mac App Store.

Read our Standalone App guide for setup details

Full Screen Mode

Desktop apps can be run in full-screen mode and make use of high-resolution graphics for a crisper display.

Read our Full Screen Mode guide to learn more

OGG Sounds are Required

One notable change is that if you intend to export a desktop or mobile app, you must provide an OGG copy of every sound in your game due to some peculiarities in the underlying technology.

Read our Sound Playback guide for details.

Disclaimer: 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!


0 9 years, 8 months ago
Yay! ^^
1 10 years, 1 month ago
I've added a note about sample games from 2.0 being incompatible with 3.0 and how to grab the new ones.
3 10 years, 2 months ago
Yes, that statement is incorrect. The entire article is being redone and that will be corrected.
0 10 years, 4 months ago

Ironically, you can make an android app on the iOS. But you can't make an iOs app on windows.

0 11 years, 1 month ago

Possible incorrect statement, "Windows developers can test on iOS directly from their PCs (but we highly recommend testing on Android instead!)"

Is the Android supposed to be iOS?


0 11 years, 1 month ago

Sign In to Comment