Phaser function order, reserved names and special uses

[rich]

This is quite an important post that I didn't want you to have to wait until the docs are ready to find out about.

 

Phaser has a number of special "reserved" functions that are executed at specific points in the game, and should contain different sorts of code. Here's a list of them:

 

preload

 

This function is called first. It should contain code to handle the loading of assets needed by your game. I.e. game.load.image(), etc. Note: while 'preload' is running the game doesn't call the update or render functions, instead it calls 2 special functions (if they exist): loadUpdate and loadRender.

 

You don't have to put just loader specific code in the preload function. You could also do things like set the stage background color or scale modes. However to keep it clean and logical I would suggest you do limit it to just loading assets.

 

Note that you don't need to tell Phaser to start the load, it happens automatically.

 

loadUpdate

 

This is a special-case function that is only called while assets are preloading (as the standard update function is not). You could use it to do something like update a progress bar.

 

loadRender

 

Most likely not needed (especially not for WebGL games) but this is an optional special-case function that is called after update and should contain render specific code.

 

create

 

The create function is called automatically once the preload has finished. Equally if you don't actually load any assets at all or don't have a preload function then create is the first function called by Phaser. In here you can safely create sprites, particles and anything else you need that may use assets the preload will now have loaded for you. Typically this function would contain the bulk of your set-up code, creating game objects and the like.

 

update

 

The update (and render) functions are called every frame. So on a desktop that'd be around 60 time per second. In update this is where you'd do things like poll for input to move a player, check for object collision, etc. It's the heart of your game really.

 

render

 

The render function is called AFTER the WebGL/canvas render has taken place, so consider it the place to apply post-render effects or extra debug overlays. For example when building a game I will often put the game into CANVAS mode only and then use the render function to draw lots of debug info over the top of my game.

 

Once render has completed the frame is over and it returns to update again.

 

resize

 

Introduced in Phaser 2.1.0 this method is called only if your game is running under the RESIZE scale mode, and only when the game container changes scale (be that the browser or the dom element your game is within). It is passed two variables, the new width and height. You can use this method to re-align responsive game elements.

 

shutdown

 

This method is called when the State is shutdown (i.e. you switch to another state from this one).

 

Note that you cannot use any of the above function names in your game other than for the use they were intended above. What I mean by that is you should consider them as being 'reserved' as game system only functions.

 

As well as the above methods there are a set of default properties that are always created in your State objects. They are as follows:

/*** @property {Phaser.Game} game - This is a reference to the currently running Game.*/this.game = null;/*** @property {Phaser.GameObjectFactory} add - A reference to the GameObjectFactory which can be used to add new objects to the World.*/this.add = null;/*** @property {Phaser.GameObjectCreator} make - A reference to the GameObjectCreator which can be used to make new objects.*/this.make = null;/*** @property {Phaser.Camera} camera - A handy reference to World.camera.*/this.camera = null;/*** @property {Phaser.Cache} cache - A reference to the game cache which contains any loaded or generated assets, such as images, sound and more.*/this.cache = null;/*** @property {Phaser.Input} input - A reference to the Input Manager.*/this.input = null;/*** @property {Phaser.Loader} load - A reference to the Loader, which you mostly use in the preload method of your state to load external assets.*/this.load = null;/*** @property {Phaser.Math} math - A reference to Math class with lots of helpful functions.*/this.math = null;/*** @property {Phaser.SoundManager} sound - A reference to the Sound Manager which can create, play and stop sounds, as well as adjust global volume.*/this.sound = null;/*** @property {Phaser.ScaleManager} scale - A reference to the Scale Manager which controls the way the game scales on different displays.*/this.scale = null;/*** @property {Phaser.Stage} stage - A reference to the Stage.*/this.stage = null;/*** @property {Phaser.Time} time - A reference to the game clock and timed events system.*/this.time = null;/*** @property {Phaser.TweenManager} tweens - A reference to the tween manager.*/this.tweens = null;/*** @property {Phaser.World} world - A reference to the game world. All objects live in the Game World and its size is not bound by the display resolution.*/this.world = null;/*** @property {Phaser.Particles} particles - The Particle Manager. It is called during the core gameloop and updates any Particle Emitters it has created.*/this.particles = null;/*** @property {Phaser.Physics} physics - A reference to the physics manager which looks after the different physics systems available within Phaser.*/this.physics = null;/*** @property {Phaser.RandomDataGenerator} rnd - A reference to the seeded and repeatable random data generator.*/this.rnd = null;

Again consider the above as 'reserved variables'. You CAN over-write and replace them if you like, but it's probably easier not to.

Edited September 14, 2014 by rich
Added resize method to the list

[ema99]

thank you very much rich, as I can get the percentage of downloaded resources from loadUpdate function?

[rich]

There are a couple of ways to get the download percentage:

game.load.progress

This property contains the current load progress, a value between 0 and 100. You could poll this in your loadUpdate loop if you like.

 

Alternatively what I tend to do is this:

function preload () {    // lots of game.load.XXX calls here, then add this on:    game.load.onFileComplete.add(updateProgressBar, this);}function updateProgressBar () {    // Another file has just loaded, so update the size of my progress bar graphic here}

The onFileComplete callback is pretty powerful, every time a file loads it gets called and passes in the following values:

progress, cache ID, success, files loaded, total files

progress is the same as game.load.progress, so a value between 0 and 100.

 

cacheID is the string you used when adding a file with game.load.image('cacheID')

 

success is a boolean, true if the file loaded, false if it errored.

 

files loaded are how many files have been loaded so far, out of ...

 

total files is how many were in the loader in total.

[earok]

Just a (probably dumb) question, I've noticed that loadUpdate and loadRender are not part of the Phaser.State.prototype, even though the others appear to be. Is there a reason for this? I'm mainly just curious.

[rich]

They were probably added after the State had been created. I've added both now.

[mariogarranz]

Just a note on the onFileComplete callback, the 4th parameter doesn't seem to be "files remaining", but "files already loaded" instead.

 

Had to debug the data I was recieving because it wasn't working as expected and found that.

[rich]

Good catch, I've edited the post to reflect this.

[king]

There are a couple of ways to get the download percentage:

game.load.progress

This property contains the current load progress, a value between 0 and 100. You could poll this in your loadUpdate loop if you like.

 

Alternatively what I tend to do is this:

function preload () {    // lots of game.load.XXX calls here, then add this on:    game.load.onFileComplete.add(updateProgressBar, this);}function updateProgressBar () {    // Another file has just loaded, so update the size of my progress bar graphic here}

The onFileComplete callback is pretty powerful, every time a file loads it gets called and passes in the following values:

progress, cache ID, success, files loaded, total files

progress is the same as game.load.progress, so a value between 0 and 100.

 

cacheID is the string you used when adding a file with game.load.image('cacheID')

 

success is a boolean, true if the file loaded, false if it errored.

 

files loaded are how many files have been loaded so far, out of ...

 

total files is how many were in the loader in total.

Just what I need,thank you very much

[beeglebug]

Note that you cannot use any of the above function names in your game other than for the use they were intended above. What I mean by that is you should consider them as being 'reserved' as game system only functions.

 

Can you just clarify, does that mean that they are always called in the global scope? I thought they were stored as methods of the current State?

[rich]

They are stored as methods in all States. So if you were to create a function called 'input' for example in your current State it would overwrite the Phaser input handler reference.

[beeglebug]

Ah, I understand now. Perhaps you should edit the post to be a little clearer that you mean within a given State object? It read to me as if you were saying that you cannot use any of those function names anywhere, which made me think that you were calling them globally somewhere. Panic over 

[DWboutin]

My game.load.progress get stucked at 98%, but all is fully loaded. Do you know what can cause this?

 

And how can i access these attributes (progress, cache ID, success, files loaded, total files) in my onFileComplete function?

 

Thank you

[rich]

Not without seeing seeing the game itself really.

 

Those properties are sent as parameters:

this.onFileComplete.dispatch(this.progress, this._fileList[previousIndex].key, success, this.totalLoadedFiles(), this._fileList.length);

So in the function you set-up, just add them in:

function fileLoaded(progress, key, success, totalLoaded, totalFiles) { // do stuff}

[Arlefreak]

I got a question about the template on the github repo, is more a JS practice question.

this.game;		//	a reference to the currently running game    this.add;		//	used to add sprites, text, groups, etc    this.camera;	//	a reference to the game camera    this.cache;		//	the game cache    this.input;		//	the global input manager (you can access this.input.keyboard, this.input.mouse, as well from it)    this.load;		//	for preloading assets    this.math;		//	lots of useful common math operations    this.sound;		//	the sound manager - add a sound, play one, set-up markers, etc    this.stage;		//	the game stage    this.time;		//	the clock    this.tweens;	//	the tween manager    this.world;		//	the game world    this.particles;	//	the particle manager    this.physics;	//	the physics manager    this.rnd;		//	the repeatable random number generator

I always add this lines as the template suggest, at first I thought it would make that instead of using: 

this.game.add.sprite(x,y, ' '); 

I could use:

game.add.sprite(x,y,' ');or add.sprite(x,y,' '); 

But it wasn't the case so I started wondering why do we declare all those variables, so I removed them and my game still works.

 So my question is what does declaring the variables for phaser really do, are they necessary or just a reference?. 

Thanks in advance

[rich]

Think of them as a 'reminder' or list of 'reserved variables'. When the State is swapped to it creates all of those vars above. If they already exist then it just sets them as a reference to the game systems. If they don't exist it creates them as new vars, then sets them as a reference. So it's the same end result really. Feel free to not specify them if you prefer

[panovsky]

Thank you!

Can you make a tutorial about preloader and add it to dosc.phaser.io or phaser/example? =)

It will be very helpful for new users

[jerome]

preloader : http://www.html5gamedevs.com/topic/1372-phaser-function-order-reserved-names-and-special-uses/#entry9139

state example : http://www.html5gamedevs.com/topic/1813-the-monthly-phaser-examples-contest/?p=24420

state doc : https://github.com/photonstorm/phaser/wiki/Phaser-General-Documentation-:-States

[ChubbRck]

Another dumb question: I can't seem to get loadUpdate() to fire in my single-state app. Am I missing something obvious?

 

Thanks - 

 

Nick

[justGoscha]

Is it better to put the GUI in the update or the render function?