Menu

How Do I Organise Files in A Phaser.js Project?

Among newer JavaScript developers, the manner and order in which JavaScript code is executed is often a source of confusion. Not quite grasping how your code is "seen" by the JavaScript interpreter can make it quite hard to organise your game's source files in a convenient and orderly manner, and can also cause unexpected behaviour in your code.

The official phaser examples are very helpful as quick proof-of-concepts on how to implement certain common game features with Phaser, but judging by the comments left on some of these examples many newer developers take them as gospel-truth, structure their game's source code in a similar way, and run into problems because their code then doesn't work as they expected.

In this article I'll attempt to illustrate a better way to organise your game's JavaScript source files than the basic method illustrated in the Phaser examples.

JavaScript Compared to Other Languages

If you're familiar with using strongly-typed, compiled languages such as C# and Java, you'll know that in these languages a certain amount of structure is inferred upon the program's source code by the needs of the compiler. For instance, with the necessity of the main method or with the use of import or include statements.

In JavaScript, however, code is executed from top to bottom. Code is executed in the order it is encountered by the JavaScript interpreter (your browser or the JavaScript runtime you're using). There is no entry point to the application (a main method)

The First Deadly Sin

When using <script> tags in a HTML page, many new JavaScript developers mistakenly include the <script> tags referencing their libraries in the wrong order (for instance, by adding their reference to Phaser after the reference to their source code). This would result in their game's code executing, but not knowing about Phaser yet. The code will break and throw an error similar to Phaser is not defined in the console.

The Second Deadly Sin

Another common source of unexpected behaviour in JavaScript is the unwitting declaration of variables in the global scope.

What is "scope"? The "scope" of a variable is the place in the code that variable can be accessed. Variables in JavaScript are function-scoped, which means that variables are private to the executing function and functions declared within it.

Scope in JavaScript is quite easy to understand. Here are two examples that will help you out.

The output is There are 99 bottles of non-alcoholic carbonated beverage on the wall. That's because the numberOfBottles variable is declared in the parent scope of the HowManyBottles() function. Therefore, the HowManyBottles() function can happily access and set the numberOfBottles variable.

There are 1337 bottles of non-alcoholic carbonated beverage on the wall
There are 99 bottles of non-alcoholic carbonated beverage on the wall

This is because the HowManyBottles() function is now using it's own local numberOfBottles variable with is set to 1337 within the function. Therefore, the global numberOfBottles variable isn't re-set to 1337 inside the function and stays as 99.

The thing to notice here is the use of the var keyword. The use of the var keyword allowed us to re-use the numberOfBottles variable inside the function and not affect the world outsite the function.

You do not want to unwittingly pollute your global scope with all of your variables. If you add something to the global scope, it should be because you explicitly wanted it that way, not by accident.

This is how stop scope being a problem in your code:

Always use the var keyword to declare variables.

Always surround logically-seperate blocks of code in an anonymous function.

This is how you would use an anonymous function to separate logically-distinct blocks of code: