A Brief Exercise in Profiling JavaScript

I recently had to track down a memory leak while reviewing a video course–a series of videos broken up into 8 sections consisting of 5 videos each–that demonstrated the development of a couple of games with HTML5 technologies.  This is a brief recap of how I approached uncovering the leak with the hope it can provide others with a hands-on exercise using Google Chrome’s profiling capabilities.

The course primarily involved JavaScript coding utilizing the EaselJS library to interface with the canvas element.  I had just completed the sixth in the series of videos provided at which point the code had placed the game into a loop.  That is, as soon as the hero in the game died, the game immediately started over again.  Letting the game loop through a few times I noticed the game started to get sluggish.  A natural assumption would be we have a memory leak.

Here is the code in exactly this state (view leak in browser and download archive of code).

Of course, thinking as any developer would, I figured it couldn’t be my fault.  The course must have instructed me to do something wrong and introduce the leak.  The course came with code representing where you should be after each video, so to test my assumption the course was at fault I ran the code the course provided, and it did not become sluggish.  So I was left pondering what I had done to get the game into this state.

At this point the code included 9 JavaScript files I had written consisting of about 400 lines of code.  There was also a dependency on the EaselJS library.  Naturally, I downloaded the latest and greatest version of EaselJS–0.7.1–while the course used an earlier version: 0.5.0.  Between the two versions some significant changes have been made to the library, and the minified file was 79 kb.  So this wasn’t going to be as simple as commenting out a few suspect lines here and there to narrow down the origin of the leak.

Enter the profiling tools in Google Chrome.  At this point you may want to open up my code in Google Chrome, open Chrome’s dev tools (F12 in Windows, Cmd+Opt+I on Mac), and click on the “Profiles” tab.  Make sure “Record Heap Allocations” is selected, and click “Start.”  This will give us an object allocation graph on a timeline (in gray) as well as indicating the time of events (in blue).  Do this for a while and then stop the profiling by clicking the red circle.

There are a few events that you will notice occur naturally.  Our hero, who at this stage in development is a green rectangle, can collide with a yellow rectangle (a “coin”) and collect it.  Our hero can also trigger a game restart in a couple of ways: by colliding with a red rectangle (an obstacle), or by falling off a black rectangle (a platform).  You can also trigger an event as a player by clicking on the canvas, which causes the hero to jump.

So back to our initial profiling.  Looking at the time line we took, you will notice the object allocation increasing over time in a saw tooth pattern, which confirms we have a leak.  You will also notice that at each jump in object allocation we have a blue line indicating an event occurred.  If you watched the game play in parallel with watching the timeline being recorded, you should have noticed that this jump in object allocation occurred immediately after our hero died, either by colliding with an object or falling off a platform.

 

Heap Timeline - notice sawtooth pattern with increasing object allocation being triggered by events (our hero dying)

Heap Timeline – notice sawtooth pattern with increasing object allocation being triggered by events (our hero dying)

So we’ve now confirmed we have a leak, as well as identified the event that is feeding the leak.  The next step is to identify the objects that are being created by the event.

Back to the “Profiles” tab in the dev tools.  But instead of selecting “Record Heap Allocations,” we instead are going to select “Take Heap Snapshot.”  The plan is we’re going to take a snapshot of the objects on the heap before the event occurs, and then a second snapshot after the event occurs.  We’ll then examine the difference between the two snapshots to see if we can identify any specific types of objects that increase in number.

So after starting your game, click the button to take a snapshot (it’s OK if you don’t take it before the first death of our hero, he will die plenty of times).  Now wait until our hero dies one or two or more times, and then take another snapshot by clicking the gray disc above the listing containing the first snapshot.  You should now have “Snapshot 1” and “Snapshot 2” listed.  Then from the “Summary” dropdown, select “Comparison” (see screenshot, immediately below).

After taking snapshots before and after the event, select "Comparison" from the dropdown.

After taking snapshots before and after the event, select “Comparison” from the dropdown.

To provide some context for what we’re about to see, here’s a little background on how some of the code is structured.  The game is made up of “GameObjects” whose constructor function’s prototype object is an instance of an EaselJS Container (createjs.Container).  If you look at the code for this, you will also notice that GameObject.prototype.initialize calls p.Container_initialize (which is a reference to the initialize method initially created when the prototype object was instantiated).

Derived from GameObject, using the same same prototypal inheritance pattern, are Coin, Obstacle, Platform, and MoveableGameObject.  Hero is then derived from MoveableGameObject.  When a new game is initialized, a single hero is instantiated, as are 10 Platforms.  Upon the first Platform a Coin in instantiated, and for the last 9 Platforms either a Coin or Obstacle is instantiated (via a 50% decision made via Math.random). These objects are all added to the game’s “camera” property as children, where the “camera” is an instance of an createjs.Container.  This camera is a child of the stage, which is the createjs wrapper object around the canvas the game is played on.

As mentioned earlier, the game ends and restarts (loops) when the hero either runs into an obstacle, or falls off a platform.

So, with this background, you should notice something quite interesting by looking at the comparison of the two snapshots taken with the profiler (see image, below).

Look at the Constructors list to see if we see any object numbers building up.  See anything interesting?

Look at the Constructors list to see if we see any object numbers building up. See anything interesting?

Between my snapshots, the hero died three times.  Given this, and what you know of the object model for this game, three items should stand out in the constructor list.

For starters, we see 30 new Platforms were created, and 0 deleted.  As mentioned above, with each game restart 10 Platforms are created, and with 3 restarts, we see the Platforms being created, but we’re not seeing the old ones being GC’d.  And we also see 16 Coins and 14 Obstacles created, but none are cleaned up.  So we now know when the game ends, we’re either not deleting the old objects, or more likely we’re maintaining a reference to them that is preventing them from being cleaned up by the garbage collector.

So the next step I would take is examining the code that is called after our hero dies, which presumably cleans up the game objects before starting over again.  Looking in rush-game.js, and specifically RushGame.prototype.resetGame, we see the call that should clean up these objects (ie, this.camera.removeAllChildren):


var p = RushGame.prototype;

p.resetGame = function() {
  this.camera.removeAllChildren();
  this.camera.x = 0;

  createjs.Ticker.removeAllEventListeners();
  createjs.Ticker.addEventListener('tick', (function() { this.tick(); }).bind(this));
};

And if we look at RushGame.prototype.initGame, we see that Platforms, Coins and Obstacles are added as children to the camera, so presumably we’re doing everything right.  So what’s going on with this.camera.removeAllChildren?

If you use the debugger and place a break point at the call of removeAllChildren, and then upon hitting it, examine what this method is in the console, you will see this:

leak-removeAllChildren

So we see it pops each child (Platform or Coin or Obstacle) off the camera’s children array, and then set’s the child’s parent property to null.  Presumably the parent is the camera, and these objects should be free to be cleaned up by the garbage collector.  So… More digging…  Let’s start with the Platform constructor function in rush-platform.js.


rush.Platform = (function() {
  function Platform(width) {
    this.initialize(width);
  }

  var p = Platform.prototype = new rush.GameObject();

  p.category = 'platform';

  p.GameObject_initialize = p.initialize;

  p.initialize = function(width) {
    this.width = width || 120;
    this.height = 12;

    var shape = rush.CommonShapes.rectangle({
      width: this.width,
      height: this.height
    });

    this.addChild(shape);
  };

  return Platform;
}());

We see it’s prototype object is an instance of a GameObject, and the constructor function itself calls initilialize, which is defined on the prototype object and adds a shape via a call to addChild, which it presumably accesses via the prototype chain.  But more interesting is what is happening just above the definition of initialize, we see GameObject_initialize being set to the prototype object’s initialize method, and then nothing further is done with it.

Now if you were to surmise at this point that GameObject_initialize should be called in initialize, and tried this and then repeated the profiling exercise, you will find you have discovered the issue in code causing the leak, as you would be seeing the Platform objects now being deleted in your snapshot diff.  And if you look at the code in rush-coin.js, and rush-obstacle.js, you would see the same mistake, which I introduced through copying and pasting the Platform code.  So at this point you could simply fix your code by calling GameObject_initialize in all three initialize definitions, and the leak is taken care of.

But for the sake of academic completeness, let’s dig into the code a little deeper and understand why this caused a leak.  Back to Platform, we know it’s prototype object is a GameObject, and we know we don’t call the GameObject’s initialize method.  So what do we see in rush-gameobject.js?


rush.GameObject = (function() {
  function GameObject() {
    this.initialize();
  }

  var p = GameObject.prototype = new createjs.Container();

  p.category = 'object';

  p.width = 0;
  p.height = 0;

  p.Container_initialize = p.initialize;

  p.initialize = function() {
    this.Container_initialize();
  }

  p.hitPoint = function(point) {
    if (point.x >= 0 && point.x <= this.width &&
        point.y >= 0 && point.y <= this.height) {
      return true;
    }
    return false;
  };
  return GameObject;
}());

So we see that GameObject’s prototype object is an instance of a createjs.Container, and that GameObject’s initialize method does call the Container’s initialize method.  But since the GameObject’s initialize method is not being called when the Platforms are being initialized, then the Container’s initialize method is not being called, either.  We can also note that addChild is not defined in GameObject, so the addChild being called in Platform.prototype.initialize is coming from further up the prototype chain.  And if we go up the prototype chain we also find addChild defined on createjs.Container.prototype.

Even though I only have the minified version of the EaselJS library, it is still apparent what is going on if we look a the code for the two attributes off the Container’s prototype object.

createjs.Container.prototype.initialize


function (){this.DisplayObject_initialize(),this.children=[]}

createjs.Container.prototype.addChild


function (a){
  if(null==a)return a;
  var b=arguments.length;
  if(b>1){for(var c=0;b>c;c++)this.addChild(arguments[c]);return arguments[b-1]}
  return a.parent&&a.parent.removeChild(a),a.parent=this,this.children.push(a),a
}

createjs.Container.prototype.initialize creates an array–children–in the this scope. However, remember that Platform (and Coin and Obstacle) don’t call GameObject.prototype.initialize, which is what calls this, so we don’t have a children array created on these objects. But all of the constructor functions for Platform, Coin and Obstacle have an instance of GameObject defined as their prototype object. So when we see this.children being referenced by addChild, it is Platform.prototype.children having an element being pushed on it (or Coin.prototype.children, or Obstacle.prototype.children), and since the constructor functions Platform, Coin and Obstacle never go out of scope, the elements of the children array off their prortype objects’ never go out of scope and don’t get GC’d.  And since these children elements reference the instances of Platform|Coin|Obstacle as their parent (this.parent, see addChild), those objects don’t get GC’d even though they are no longer elements in the camera.children array.

I realize there’s a lot in that last paragraph, and you may have to go back to the code (in the debugger, no less) to fit all the pieces together, but there you have it: the origin of the memory leak.  It even becomes more apparent if you do this: instead of calling this this.GameObject_initialize in the initialize method of the prototype object for Platfor|Coin|Obstacle, instead simply add the line “this.children = [];” in each initialize method, and the run and profile the code.  You will see the memory leak is gone.

All questions, comments and expressions of confusion welcome.

Advertisements

Video Course Review: HTML5 Game Development (Packt Publishing)

I have done numerous courses online, from college courses with proctored exams, to continuing education online (e.g., ed2go), to the free Aquent Gymnasium courses (which are very well done), to courses I paid for that were not so good.  I generally find that online courses provide a convenient means of receiving instruction, while enforcing a structured approach to your learning, if they are done well.

So I was quite pleased to take on the opportunity to review the Packt Publishing video course HTML5 Game Development  by Makzan.  Though I have developed a Windows 8 game with HTML5, I don’t consider myself  a game developer and I very much looked forward to finding out what I could learn from this course.  (As a disclaimer, I received the course for free from Packt in return for this review).

The course, which as of this writing can be downloaded for $33.99 from the Packt website, comes in the form of an archive that contains two more zip files.  The first zip file contains the video files–40 in total which make up 8 lessons of 5 sections each–as well as a brief user guide (9 pages, pdf format) which explains the contents of the course and how to navigate it, a briefer pdf (1 page) that explains how to provide feedback to Packt, and some web pages that allow you to browse the course.  The second zip file contains the source code in the state it should be after each video (i.e., 40 folders of source code).

 

With other courses I’ve taken, I’ve found those courses that deal with a specific technology are less likely to become dated quickly than those that deal with a number of technologies and have dependencies on others, such as browsers. This course would fall into the latter.

And of course it goes without saying you get out of a course what you put into it.  It takes effort, and a good course will motivate you to make that effort.

So, to start, let’s deal with some of the up front claims in the marketing literature, and set realistic expectations.  If you read the Packt download page or the course overview that comes with the course, you will see the claim “Build two HTML5 games in two hours with these fast-paced beginner-friendly videos.”  The 40 videos themselves have a total running time of two hours, so it is more accurate to say you can watch someone explain how they built two games over two hours.  I coded along with the course and I found that each of the 8 individual sections easily took me over two hours a piece to complete, and depending on issues I came across, it could be twice that or longer.  The five individual videos that make up each section tended to be in the 2 to 3 minute range each (with a few over 4 minutes and some under 2 minutes), which are nice little chunks to work on at any one time.  The Packt website does provide a sample video (Section 5, Video 4) that is a fair representation of what you can expect from the videos that make up the course:

And in terms of “beginner-friendly” I suppose it depends on what you are a “beginner” of.  If you read further on in the overview it states “Some basic knowledge of HTML, JavaScript, and CSS would be useful.”  Personally, I think you probably need more than some basic knowledge of these technologies to get something substantive from the course, or else I suspect you’d be just copying quite a bit of code without any real understanding as to what is going on.  At a minimum, I would recommend you have a good understanding of CSS specificity, the box model and positioning; as well as an understanding of the JavaScript module pattern and prototypal inheritance. Understanding how to use your browser’s dev tools–especially the debugger and console–will also prove extremely helpful in debugging the inevitable typos and errors you introduce into your code.  And at one point I even had to use the profiling tools to determine the origin of a memory leak, but hopefully you’ll be spared that.  So, I would say, if you have solid web dev skills and are a “beginner” to HTML5 game development, then you could find this course “friendly.”

In terms of HTML5 game development, the focus of this course is developing games on the canvas element using the EaselJS library.  In the video, the IDE you see being used is Sublime Text 2, and the browser is Safari on a Mac.  If you want to keep things simple and run into as few problems as possible, then I recommend you use Safari and version 0.5.0 of EaselJS (you can find this in the source code folders that come with the course).

If you are more adventurous, like I was, then you may want to download the latest version of EaselJS (0.7.1 at the time of this writing) and use the browser of your choice, which I suspect would be Chrome for many of you.  Now be forewarned, some of the EaselJS code written in the videos no longer works with the latest version of EaselJS. So if you are adventurous, make the EaselJS documentation your friend.  Also, I came across some cases where code that works in Safari has some slightly different results, or in one case doesn’t work, in other browsers.  More on that later.

To deal with issues like these, one thing I’ve seen useful for students in the ed2go and Aquent Gymnasium courses are discussion areas focused on each lesson, where students help one another work their way through the inevitable pain points. If Packt were to provide such discussion boards I believe they may find it enhances the learning experience for their customers.

The course, itself, teaches by example by showing the development of a couple games: in the first three sections you develop a simple card game where you win by clicking randomly placed cards in numbered order, and in sections four through eight you develop a more adventurous 1980’s arcade-style game in which you jump from platform to platform collecting coins while avoiding rotating saws.  Any guesses as to which one is cooler?

You are not provided any additional exercises, reading material, quizzes, or exams to reinforce your learning.

You can see the full course syllabus, here: http://www.packtpub.com/html5-game-development/video (click on “Course Contents”).

Basically, it’s like learning with pair programming, except your partner won’t respond to any questions.  And she does a lot of pasting of code chunks.  (Where did she copy those from?  We never do find out).  Though you can make her repeat her statements at will via rewind, and pause the video to take the time to read those pasted code chunks.

You can see the two games I built with my paired video partner here and here.  If you want to be motivated, focus a bit more on the second game, which I admit was a cool experience to build.

So yes, I did manage to successfully build the games taught in the course in spite of all I noted I ran into.  And please don’t get me wrong, I did get a lot out of this course.  I feel it was worth my while and I’m pleased with what I got out of the effort I put into the course.  Though, and I repeat, you will have to put effort into the course to get a lot out of it.

What do I feel good about that I learned?

  • the pre-loading graphics pattern shown
  • the structure taught for modeling objects for a game
  • collisions and gravity were introduced
  • how running and a “camera” that follows the runner is implemented was cool to learn
  • what’s involved in building sprite sheets for animations
  • building a progress bar for pre-loading the games resources

There are also many topics just briefly touched on that the course did not go into a lot of depth.  For example, getting your first game ready for mobile only really involved quickly coding the meta viewport tag, which is fine if this is all you find you have to do to make your game mobile ready (sorry to say not all mobile devices are going to have the same aspect ratio).  At least you have a starting place from which to investigate more.

Later on in the course we are shown how to create sprite sheets from a Flash animation (swf) by utilizing the Zoë tool.  Unfortunately, the course does not include the swf files, so we cannot try creating the sprite sheets, ourselves.

Some gotchas I’ll also warn you about, in case you do decide to do the course, so you have less to work through than I did (this is beyond the differences between EaselJS o.5.0 and 0.7.1):

  • in section two, one line of code sets the “innerText” of an element.  Of course, this doesn’t work in Firefox.  You’ll be fine if you stick with “innerHTML”.
  • in section 3, the call to createjs.Bitmap() will result in a same origin security issue if you are developing with Chrome and not hosting your work on a web server.  I got around this by restarting Chrome with that protection disabled.
  • I also found in section 3 with Chrome, Firefox and IE I could not get the background images for the tiles to display reliably when then the game first loads.  They would appear when I clicked on the first tile, though the issue went away once I put the game on a web server (except for mobile IE, where I still see it).
  • again in section 3, I downloaded a font from the exact same location done in the video.  And tried to convert it into a web font on fontsquirrel, as was done in the video.  And fontsquirrel complained the font file was corrupted.  I ended up finding a similar font, elsewhere on the web, that fontsquirrel didn’t complain about.
  • in section 4, video 3, there is a line of code that is needed that is not shown in the video for method updateView().  If you go to the code for the course, you’ll find it (or you can probably figure it out with the debugger, as I did).
  • also, in section 4, when the code is shown in the video for building the platform, you will see that p.GameObject_initialize is not called in the definition of p.initialize (see below screen shot).   Do this and you’re in for an ugly surprise come section 6.  In section 6, the game code is written to loop back to the beginning once your player dies.  After a few loops you will notice the game starting to get sluggish.  This is even more pronouncedwithEaselJS version 0.5.0 than with the versionofEaselJS I used.  I did a quick heap allocation profile and saw the allocation of objects increasing over time with noticeable jumps when the game restarted.  Memory leak!  It took a bit of investigation for me to nail down just what was causing this.  (I’ll save what I did during that investigation for the subject matter of another blog post).

    this.GameObject_initialize()

    Do you see p.GameObject_initialize() being called in p.initialize()?

Beyond that, there are a number of differences between the current version of EaselJS and the version used in this course.  I’d be happy to share my notes on these differences with anyone interested in those.

So, how should I summarize all this?  I would say if you are someone who has solid knowledge/experience with web technologies, especially JavaScript and CSS, and little experience developing games for the canvas element, and you are willing to put in some effort, you will get your money’s worth from this course.  You won’t pick this stuff up in a couple hours, short of having mastered osmosis.  If you have basic JavaScript and CSS abilities, my suspicions are you will pick up some knowledge, but for a lot of the stuff you code you won’t really understand what is going on, and you may get very frustrated if you miss a line of code or make a typo and your debugging skills are not up to snuff.  Or even if you do pinpoint the origin of the error, will you understand the issue?  Or, I suppose if you are really motivated, you could learn how to use the dev tools, and dig into these technologies, in parallel with the course.  Obviously some extra effort, but you got to learn that stuff at some point.

As for the issues I ran into, well, I can assure you that you will run into these issues in other courses that involve multiple interdependent technologies that are changing rapidly.  That is where things like discussions boards and folks helping one another out come in handy, and would make a fine compliment for Packt to offer with their courses.

On the Amazon scale: 4 out of 5 stars