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







Optimizing Actor Performance

by Jon (Updated on 2015-10-17)


One of the most important ways to ensure fast, smooth game performance is by making sure you're using actors in your game efficiently. The following tips can help you do this.

Don't create too many actors. Use Images instead.

Stencyl is based on Box2D, an industry standard physics engine that provides convincing collision detection out of the box. The numerous calculations required to run it can be taxing, so it's best to use fewer actors rather than more. There's no hard number which is "bad" since this can vary widely depending on the device and the game.

If you must have many objects on-screen, consider using Images in place of full actors.

Images are quasi-actors that do not make use of the physics engine - this improves performance if you don't need them to register collisions. Examples of such actors include decorations and special effects.

Remove Actors when they're no longer needed

There are many times when you should remove an actor from your game because they are temporary in nature. Examples include bullets, temporary power ups, certain enemies, and more.

Generally speaking, if an actor is only encountered once by the player, it should be removed as soon as possible. The conditions for removal will differ from game to game.

The following examples demonstrate a few common scenarios and pitfalls to watch out for.

Actor collides with another actor

Remove an actor

Warning: If actor A collides with actor B, there are no guarantees about which collision event runs first (since two will be dispatched - one for actor A and one for actor B). Do not make assumptions about which one will run first.

Actor leaves the screen

Leaving Screen

Explanation: In this case, the boolean attribute called Actor On Screen? ensures that the actor isn't removed before it has a chance to appear on screen. You'd set Actor On Screen? to true once that actor appears on screen. Then, when the actor leaves the screen again, it will be killed.

Now it's your turn. Share your tips.

What have you found, in your experiences, boosts performance of your games when you're in a bind? Use the comments area below to share your stories.

Print Article Edit Article How to Edit an Article
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!


The recycle functionality is not completely bug free. That's why it isn't the default yet.

Creating new actors on the fly is expensive in Box2D. We found substantial, very substantial performance improvements using recycled vs. not.

1 12 years, 2 months ago
Yes I also wonder about the difference between recycled and non-recycled actors. If recycled actors improve performance, why not use them all the time? Why would you ever have to avoid it and use a regular actor instead?
0 12 years, 3 months ago
Why all that complication with the recycled actors? In my opinion it severely complicates design and can lead to bugs. Is garbage collecting not good enough to do its work (it does it anyway, for all the rest)?
-1 12 years, 3 months ago

Sign In to Comment