Building Aukera Part 2: The Foundations

With the little intro out of the way, it’s time to get into the actual nitty- gritty of how Aukera works. I’m not going to start right in on any one part of the library yet, since there’s still some groundwork to do. This post is going to talk about the decisions and structures that permeate through every facet of the code. These are things you’ll see in every file I talk about, so it’s probably best to just get them out of the way now.

Before I begin, however, there’s been a change in plans. I said I was going to alternate between posts about the thought process and the code to avoid confusion, but I found the thought without the code was actually more confusing. To make things easier I’ve released the Aukera library as open source. The entire repo can be found as aukera-library on GitHub. In each post I’ll link to the specific version of each file I’m talking about.

While I’m not dealing with any specific script this time, everything I’m talking about can be see in scripts/Game.js.

The Project Structure

The Aukera library needs to be modular. I want someone who’s using it to be able to swap bits in and out and not have to worry to much about it. Javascript is actually really good for this. The prototypical model that it uses for objects (as opposed to that oh-so-rigid classical model) means that a constructor can be created in one place, and it’s protoype can be edited by another script. This means that a new bit of game-wide functionality can be dropped in, and all the existing objects can automatically gain the abilities to use it.

To accomplish something like this in a classical system would involve creating new classes that extend/inherit from the original objects, and replacing the existing objects with instances of those classes, meaning adding new game-wide features would take a good chunk of work. You’d have to add the new script, and then rewrite the actual custom game code to use the new classes instead. In Javascript, a lot can be accomplished just by adding the new script. For example, as soon as Aukera’s ajax component is added to a page, the game object’s resource loading functions start making ajax calls with no extra configuration, even though nothing in the core Game object is ajax-aware. No other edits are needed, the ajax component can just augment the Game constructor’s prototype to make this work.

Aukera is designed to leverage this capability of javascript as much as possible. While many projects like this split code up into a file for each object, Aukera splits the code up into components. A component is not just another object, but a self-contained layer of functionality for the library. Sometimes that does translate to “just another object”, in which case the component is named for the constructor (including capitalizing the first letter), but other times a component might be some helper functions and a bunch of additions to prototypes and the like.

Namespacing

As I stated in the last post, I want all the code for this library to exist under a single namespace. I eventually adopted the pattern from this answer on stack overflow and the linked articles. As a result, all the javascript files in the library start out like this:

(function (auk) {

	"use strict";

	// All the actual code goes here

}(window.auk = window.auk || {}));

This allows all the scripts to be loaded in any order. If the auk namespace is already defined, it will be added to. If it hasn’t been then the first script that needs it will create it. By wrapping everything in an IIFE, as long as var is used properly (and jslint complains if it’s not) then auk should be the only thing that winds up in the global namespace. Any functions that need to be accessed outside of the file they’re created in need to be attached to the auk object, or attached to something that’s attached to it.

Comments

I wanted to make sure to completely comment all the code in this library. To that end I used something kind of like JavaDoc comments. Mostly it’s a habit I’ve picked up from a year of working with Drupal every day, but the fact that eclipse highlights this style doesn’t hurt either. That being said, I don’t really know JavaDoc that well, so I’m just shooting for consistency. Feel free to call me out on any mistakes in the comments, or better yet, open an issue.

Object Patterns

There seems to be a lot of patterns out there for creating objects - and simulating classes - in Javascript. I’ll admit that every time I’ve seen a bunch of these patterns in one place I get a bit lost, especially since some seem to differ only aesthetically. So I’m not sure what the actual name of pattern I used is, but this is what seemed the most straightforward to me: I create a constructor function as a method of auk, and then I add to it’s prototype. No attempts are made to encapsulate it so it looks like a “proper” class or anything. I just looks like this:

auk.Game = function (display, grid, startroom) {
	// Code goes here!
};

auk.Game.prototype.update = function() {
	// Code goes here!
}

I stick with the convention of capitalizing constructor function names, and only constructor function names, and it all seems to work out fine. Constructors do not get their own closures, aside from what is provided by the namespacing setup. An interesting side effect of this is that it’s not actually possibly to give “classes” private variables, but it is possible to give them to components.

Moving On

With all that fun stuff out out the way, it’s time to move on to some actual code. As I said at the start, I’m abandoning the alternating process/code posts because that was confusing. In the next post I’m going to walk through the building of the core Aukera file. If I’m being unclear at any point, by all means comment, and if you see any code you don’t feel is up to snuff comment or open an issue so I can fix it.