Forums » Code » ScreenFader: A screen fading plugin!

Make your game screen fade to black (or any other color you choose) with this simple yet versatile screen fading plugin.

ig.ScreenFader is a class that represents a fade operation. Its constructor takes an object that has the options for the fade, but also has default options that do a fade-to-black type of fade.

It is up to the game code to call draw on an instance of ig.ScreenFader. Every time draw is called, the fade is progressed and the fade effect is applied to the screen by either drawing a semi-transparent rectangle over the entire screen, or by using an image to draw semi-transparent tiles.

It is safe to call draw inside of your game's draw method because the ig.ScreenFader class is designed so that it is non-intrusive when a game is playing and fast as possible when executing the fade effect. It is faster and easier to use the color option rather than using tiled images. The default behavior is to use the default color of solid black.

/* inside a Game subclass */

init: function() {
   this.screenFader = new ig.ScreenFader( {  /* options go here */ } );
},

draw: function() {
	this.parent();
	if (this.screenFader) {
	   this.screenFader.draw();
	}
}

Options:

fade - the type of fade, can be either 'out' or 'in', default is 'in'. Fading in means the color or image starts from invisible and goes to fully solid. Fading out means it starts fully solid and goes to invisible.

speed - The rate of speed that this fade runs at. It is multiplied against the game time, so a value of 1.0 is normal, and 2.0 is twice as fast. The default is 1.0.

color - An object that stores a color in an "RGB" (Red, Green, Blue) format. The lowercase letter r = Red, g = Green, b = Blue. Values can range from 0 - 255. A value for "a" is optional and it can be used for a transparent color, but "a" is not required. Default value is { r: 0, g: 0, b: 0, a: 1 }

screenWidth - Width of the screen used for tiling an image. Default is ig.system.width

screenHeight - Height of the screen used for tiling an image. Default is ig.system.height

tileImagePath - Location of an image to use to tile the screen with. Not required. Example: 'media/screen-tile.png'

tileWidth - Required Width of the tile only if tileImagePath is being used to tile an image

tileHeight - Required Height of the tile only if tileImagePath is being used to tile an image

callback - A function to call when the fade is finished

context - The value of "this" in the callback. The default is the current ig.game being played. If you would rather it be the current ig.ScreenFader instance, change the global setting ig.ScreenFader.globalGameIsContext to a false value because the default is true

waitUntilLoaded - A boolean that indicates to wait for the image at tileImagePath to finish loading, only used if tileImagePath is set and the default is true

visible - A boolean that can be set to false to not draw or progress a fade. It makes it frozen and invisible when it is false, so its default is true

delayBefore - A time expressed in seconds to wait before starting the fade effect. Default is 0, no wait.

delayAfter - A time exressed in seconds to wait after the fade has completed before calling the callback function. If you want the screen to stay black for a certain number of seconds and then call the callback, set this value. The default is 0, no wait.

Note that delayBefore and delayAfter are seconds of game time. They use ig.Timer to measure time. If they are zero, then no timer is created.

View the source

Looks great. Could this be adapted to "tween" the alpha or x,y of entities?

I should add an "entity" property to this. Maybe even an "entities" property. This code fades an animation already when a tiled image is used, so if the entity (or array of entities) all have a currentAnim, then this plugin could just point to their currentAnim instead of the this._anim that it currently changes the alpha for.

Here's the original code (no entity support yet) with a demo I just threw together from Jump'n'Run. It runs the screen fader when the level loads.

ScreenFader and DrawCounter JumpnRun Demo

Great plugin!

I've got a fade to black happening in my game. When it's done animating, how do I carry on from the black screen? I'm guessing it involves using the callback. I'm just learning, so I don't know how to make use of it. Thanks!

Simple advice, if you’re fading to black, fade from black afterwards :)

Thanks for your response, Hareesun.
I guess what I wanted to know (and still do) is how to know when the fade-to-black animation is done. Then I could start my fade-from-black based on that.
My round-about solution involved using timers instead, which seems superfluous for such a simple need.

The callback function allows you to do just that.

example of a callback being used:

ig.game.screenFader = new ig.ScreenFader({ fade: 'in', speed: 2.0 ,callback: functionName });

BOOM ^ :P

I’ve not actually had the time to touch Impact in quite a while, just like to browse the forums every once and a while :)

Thanks TylerAppmobi. Just wondering, where would you define the 'functionName' function? And does this mean the screenFader would perform it immediately after the fade?

Hareesun, I appreciate your help! You were the only one who responded initially. I welcome any help or advice I can get being a JavaScript novice. I'm learning a lot! :)

You could set your callback function in the index.html.

Callback functions are typically fired after the initial function is complete. So in this case, after the fade is fully complete it'll fire the callback function.

example of function ( instead of functionName I'm using fadeOut as the callback function).

function fadeOut(){
		ig.game.screenFader = new ig.ScreenFader({ fade: 'out', speed: 2.0 });
}

Definitely helpful. Thanks again.

this is cool. would you mind perhaps throwing some license text somewhere?

Just trying out this plugin and cannot seem to get the callback to work. I have this:

this.screenFader = new ig.ScreenFader({ callback: doStart });

I get an error stating doStart is not defined. If I change to a string like so:

this.screenFader = new ig.ScreenFader({ callback: 'doStart' });

then I get no error, but the function is not called.

If I set the function inline it works:

this.screenFader = new ig.ScreenFader({ speed: 5, callback: function () { ig.system.setGame(LevelOneDrop); }});

But I'd rather not do that for aesthetic reasons.

Quote from dmen
Just trying out this plugin and cannot seem to get the callback to work. I have this:

this.screenFader = new ig.ScreenFader({ callback: doStart });

I get an error stating doStart is not defined. If I change to a string like so:

this.screenFader = new ig.ScreenFader({ callback: 'doStart' });

then I get no error, but the function is not called.

Most likely your doStart is not on the global scope. Hence doStart is indeed not defined.

MyGame = ig.Game.extend({  

    ...

    someMethod: function() {
        this.screenFade = new ig.ScreenFade({ callback: this.doStart });
    },

    doStart: function() {
        //some code
    }

    ...

});

Thanks. It was that I was missing the this in the callback definition. However I ditched this plugin as it doesn't work properly with my other code. I set zIndexes on some entities and that seems to be an issue with this one. I just made my own fader with an entity and it works great.