Quick Terms
- attribute setter: the behavior block that lets you assign a value to an attribute. Found under Attribute >> Setters.
- console: a display where Stencyl prints information such as scene changes and errors to. Can be brought up using the ~ key (near the top left of your keyboard). This is also where print blocks in behaviors and events post to.
- fps: frames per second.
* * * * *
We probably have all been there. The framerate in our Stencyl game begins to slowly drop until everything is moving at turtle speed… unless your main character is a turtle, in which case he might be moving at snail speed now.
These issues come up a lot, but often the problems are easily fixable. This quick reference guide is meant to help you discover your problem fast so you can get back to chugging away at the rest of your game. So let’s get to it.
1.) Does your game suddenly shoot you an error message?
Look in the first line of that error message for the phrase “null object reference”, as in my experience this is the most typical error message you get. It means some actor doesn’t “exist” or was killed, and now elsewhere something is still trying to get information from it. Some potential situations:
- Your player actor died and enemies are still trying to access its information (like where the player is).
- An actor inside a “Do Every X Seconds” or “Do After X Seconds” event died, and the event is still running and trying to get the actor’s information (timed events can still be running after an actor dies).
- An actor never actually got the reference to an actor it needed, and now its trying to access information from a null actor reference.
The fix? Whenever you have any situation that involves (A) timed events getting actor information or (B) another actor referencing another actor, before that actor goes to reference that actor’s information, enclose the code in question in a “If (actor is alive)” if statement; you can find the “Actor is Alive” boolean block in the behavior palette under Actor >> Properties. Also, if there is any doubt that code may not locate an actor when using the attribute setter, you can also use the “If attribute has value” boolean block under Attributes >> Functions (with “Actor is Alive”, not in place of it). Make sure you place it before the “Actor is Alive” boolean though.
GOTCHA: Real quick, if you are trying to set an actor attribute in the “When Created” section of your code, its possible the actor you are looking for doesn’t exist yet! In other words, it may still need to be created too. This can happen with actors placed in the scene editor and being created together at the beginning of a scene. My solution is to enclose the attribute setter in a “Do After .001 Seconds” timed events. That small delay may not look like much, but if my understanding is correct, it gets put “behind” all the other “When Created” codes that may be initializing the actors you need.
2.) Does your game use a lot of actors?
Simply put, you could be taxing Stencyl a little too much. Look for ways to decrease the actor count if at all possible. If your game involves a lot of actors, find a way to strategically manage how many actors are “alive” at any given point.
3.) Do you have actors exiting the screen on a frequent basis?
An example might be where a cannon is shooting cannonballs, and some cannonballs roll or fly off screen. If so, its possible all those (cannonball) actors are piling up off screen, and over time your actor count slowly increases and hurts your fps. For such situations, you can use the pre-packaged behavior “Kill upon Leaving Screen” for such (cannonball) actors, or whatever behavior is appropriate. Also, you may need to make them “always active” too, so they don’t stop processing off screen and fail to kill themselves.
4.) Does your game use any loops?
The “Repeat Until” loop is the primary suspect of a game freezing. Its caused by the loop’s condition never being met. The issue can be any number of things, so you will probably have to review the code yourself or ask for help in the forums.
The main thing to remember though is this: NOTHING happens outside of that “Repeat Until” until the loop condition is satisfied! For instance, if part of the loop code moves your actor to a different position, you can’t do things like check to see if the actor collided with something. Your collision code is waiting… waiting for the “Repeat Until” code to finish! But your “Repeat Until” may not finish… perhaps because its condition is to check for a collision (for example, through a boolean attribute like “Did Collide?”)! In such situations, you have to figure out a different way to watch for such conditions to become true instead of using a “Repeat Until”.
5.) Does your game seem to “randomly” slow down?
Other than what I mentioned above, hit the ~ key to check your console for error messages. Particularly look to see if “null object reference” errors are popping up (see #1 above if this is the case). I am not exactly sure why, but it doesn’t always shoot you the blatant game-crashing error screen for this error all the time.
Also look to see if you saw anything else being posted to the console. If you have print blocks (see Quick Terms above), they can slow down your game if they are posting to the console on a frequent basis or in spurts. Print blocks should normally be used only for debugging purposes, and unless you are confident you know what you are doing, they should be removed in your final product.
NOTE: Bear in mind that having the console up can also slowdown framerate, so the fps may not quite match what normal fps is without the console up.
6.) Does your game use pausing?
Its possible you paused the game and nothing ever unpaused it. Make sure there is a way to unpause the game. Yes, I know that sounds pretty obvious; what may not be so obvious is that an actor cannot unpause a game if said actor is paused itself. Have some sort of “unpausable” actor that can unpause your game for you. The ability to set whether an actor is pausable or not is within the Physics tab of the actor customization screen.
* * * *
Happy Stencyling!
Photon Game Development 
For the GOTCHA: Real quick… That’s because Stencyl goes through behaviors in some sort of order. The Do After… block really reads like: Skip this behavior and move ahead. If it has been (time) since I started this block, continue, otherwise skip this behavior and move ahead.