by Jon (Updated on 2015-10-15)

October 2015 - (We're now redoing this article from scratch. The interface for it has completely changed.)


  • Introduction
  • Creating/Editing Atlases
  • Assigning Graphics to an Atlas
  • Reducing Memory Usage
  • Tips
  • FAQ
  • Challenge: Mobile Preloader



Games made for use with mobile devices use atlases to store graphical game assets. An atlas is a large image that combines lots of smaller images into a single unit. Atlases are also sometimes called sprite sheets.


Stencyl uses atlases as a way of grouping similar graphics together, so that a game can operate efficiently without exceeding its memory limit. This is achieved by loading atlases you'll use and disposing of atlases you no longer need between scenes.

Creating / Editing Atlases

Atlases are managed from the Atlas page inside the Settings dialog.


Accessing the Atlases Page

1) Click the Settings button to open the dialog.

Settings Button

2) Next, click the Atlases button, as shown below. This is where you can configure atlas settings.

Atlas Settings


Atlas Options

ID: Identifier you'll use when loading/unloading atlases. This is not editable.

Name: The name of the atlas. This is just for your reference.

Load initially? Whether or not to load the given atlas when the game starts. Loading it at the game’s start will require more memory and incur some loading time.

Assigning Graphics to an Atlas

What kind of resources can be assigned to an atlas?

  • Actors
  • Fonts
  • Tilesets
  • Backgrounds


How to Assign a Resource to an Atlas

  1. Open the resource.
  2. Flip to the Properties page for that resource.
  3. Assign it to an atlas using the Atlas dropdown at the bottom. By default, every resource defaults to the Main Atlas.



Loading/Unloading Atlases

Use the load/unload atlas block to perform that operation. This block is located under Flow > Advanced.

When you use this block, Stencyl will load and unload the specified atlases for the NEXT scene, not the current scene. (If you are reloading a scene, that counts as the next scene for the sake of atlases.)

(In this particular example, we will load atlas 1 and unload atlas 2 for the next scene.)

You specify the atlas to load/unload by its ID. An atlas’ ID is displayed in the atlas' own page.



Reducing Memory Usage using Atlases

Now that we've described how to create, load and unload atlases, what exactly are you supposed to do?

The goal is to minimize your game's memory footprint. You do this by only loading in what you need. Given that, here are some best practices.


Store Core Graphics in the Main Atlas
Put the most common graphics in the main atlas. This will be initially loaded and never unloaded.


Combine Related Graphics Together into Atlases
You'll load these atlases in before scenes that use them and unload them after you leave the scene.


Add a Loading Scene
Sometimes, you'll find that atlas loading can take some time. In order to prevent an awkward pause with a black screen, consider switching to an intermediate scene with a "loading" graphic and then switching to the desired scene after that.


Don't Make Too Many Atlases
Don't create so many atlases that you overcomplicate your game and lose track of what contains what.


Watch Your Memory Usage
Take note of how much memory rises (in the FPS Monitor) when you load a particular atlas in. Generally speaking, you should try not to exceed 24 MB, which is equivalent to 6 loaded atlases (about 6000 x 6000 in total pixel area).



Can I unload the main atlas?
No, don't do that. If you need to "unload" the main atlas, move those assets to a secondary atlas.

Are atlases actually stored in one big, combined image?
Not anymore. They were in the past but that no longer is the case.

Is there a limit to how many graphics can go into an atlas?

Is there a performance penalty for having too many atlases?
No. The only disadvantage is that it becomes harder for you (the creator) to keep track.

Is there a way to load/unload an atlas during a scene?

Are you planning to support sounds/music in atlases?
Yes, in the future.

Do atlases only apply to iOS/Android?
Yes, only those two.


Challenge: Making a Mobile Preloader

At the time of writing, Stencyl doesn't support preloaders on mobile platforms. For some games, this may generate an awkward pause at the start. Let's create a preloader from scratch using what we know.

  • Tell all atlases not to initially load besides the main atlas.
  • Make the first scene show a loading graphic of your choice (bonus points if it's animated or moves across the screen to give the semblance of progress).
  • Load the atlases you need.
  • Then, switch to the "real" first scene.

That will get you a basic preloader, albeit one without a progress bar. Now, here's the second part of the challenge - add an accurate loading bar, using just the basic facilities described in this article.

Hint: Load your game, one atlas at a time. Preferably make it so you have one master loading scene rather than many.
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!


Hopefully you guys finish soon redoing this article,

best regards.

0 2 months, 1 week ago
may be time has come for rewrite that?? ))
5 10 months, 3 weeks ago
Yes, would be nice to get this section updated. It seems that Atlas handling is quite important to get big apps up and running properly on phones.
1 1 year, 2 months ago
Just to prevent anyone else wasting time getting confused by the above as I have.

it is totally different in later versions of Stencyl. There is no Atlas control on the Actor properties. It seems it is all done from within Game Settings which look quite different from the above screen shots. I think it's an improvement but it is very different.

0 1 year, 4 months ago
Atlas are limited to 16 and not 32 as is written (...which is currently 32)
0 4 years, 1 month ago

Sign In to Comment