Upgrading to Stencyl 3.0
by Jon (Updated on 2015-10-23)
- How to Upgrade to 3.0
- Upgrading your Games
- New Platforms: Android, Native Desktop
- Haxe - Unified Programming Language
- Simple Physics
Changes to iOS
- Better Workflow
- Universal Apps & Scaling
- Handling Touch Input
- 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.
- Back up your existing games. The simplest way is to ZIP up your games folder.
- Uninstall Stencyl.
- Download Stencyl 3.0.
- 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!
How to Upgrade your Games
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.
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.
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).
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.
Haxe - Unified Programming Language
If you’re a programmer and are interested in coding in Haxe, read the transition guide for details.
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.
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.
Changes to iOS Publishing
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.
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.
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.
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.
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.
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.
Stencyl-made desktop apps are fully ready to be published to major app stores, including the Mac App Store.
Full Screen Mode
Desktop apps can be run in full-screen mode and make use of high-resolution graphics for a crisper display.
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.