New Game Slides

Contact: Sean Middleditch – Producer
cell: (206) 451-7124
email: sean@sonargame.com

SONAR HTML5/WEBGL PUZZLE GAME NOW AVAILABLE IN CHROME WEB STORE

REDMOND WA, SEPTEMBER 5th – SONAR is now available in the Chrome Web Store. SONAR is a casual action AI-based puzzle game. The game features an engaging papercraft art style and a charming sense of humor, mixed with casual puzzle game play. Players are tasked with outsmarting enemy guards using a sound generation device and the Sound Vision Goggles. SONAR is available at http://sonargame.com/ for all users of the Chrome web browser.

SONAR is one of the first commercial WebGL games written from the ground up in JavaScript, and is an innovative product that has pushed the limits of what a browser can do with games. SONAR is free to play and also contains paid for add-on content. Additional content and the content creation tools are planned for a future release.

The game is based on Subsonic, the innovative DigiPen Institute of Technology student game and IGC 2011 Finalist. The core development team is comprised of four DigiPen undergraduate students, Sean Middleditch, Jason Meisel, Nick Paavo, and Shawn Pearce. The art team is comprised of two DigiPen graduates, Megan Noble and Amanda Lien. The project was completed in just three months during the summer of 2011.

For more information, or to schedule an interview, please contact Sean Middleditch at (206) 451-7124 or sean@sonargame.com.

The talk will cover the technical challenges we overcame, the new technologies we worked with, the small business and startup hurdles we jumped, and the design and approach we took to building the engine and components.

More information will be available closer to the conference date.

There's no documentation involved just yet, but there's not much to say about the API really. To parse a TAR file, simply create a new instance of the TarReader object and then call either the loadHeaders() or load() method on it, each of which take a string representing the file's raw data.

Note that if you're loading a binary data file like this, you will need to be sure that you are loading the strings as binary data and not as regular UNICODE strings. If you're using the FileReader facility, you can use the readAsBinaryString() method. If you're loading a file via XHR, be sure to either use the overrideMimeType('text/plain; charset=x-user-defined') trick or set the responseType to 'blob' (and then use FileReader) to get a binary string of the file.

The TarReader object supports two callbacks, onentry and onload. onentry is called for each file in the archive, and includes the fields detailed below. onload is called after the entire file has been loaded. The TarReader object has the fields files which is an Object mapping file names to entry objects and list which is an Array of entry objects. Note that if the TAR file has multiple entries with the same name, only the last one will be present in the files field but both will be present in the list field.

The entry objects have several fields. The most interesting ones are name (the file name), contents (the contents of the file, as a binary string), size (the size of the contents in bytes, which is most useful when you're just reading the headers), and type. Type can be one of TarReader.FILE, TarReader.DIR, TarReader.SYMLINK, TarReader.HARDLINK, TarReader.CHAR, and TarReader.BLOCK. There are a few other fields on the entry object such as uid, gui, mode, lastModified, and a few others, but I don't make any guarantees that I'm actually parsing those values correctly at this time, as we do not have a use for them in SONAR.

A good use of this library is to download large sets of files in a single go (such as game assets) which can then be cached in a FileSystem for later use. Using progress events you can more easily display loading progress than you can with loose files where you don't know the sizes, nor the number of files if you're chain-loading resources.

As the code is MIT licensed, feel free to use for any purpose, fork the code, or send me pull requests on GitHub with fixes, features, tests, or documentation.

glMatrix Basics

The first thing to know about glMatrix is that it is not an object-oriented library. The API is entirely procedural. It should feel very familiar to users of C-based vector libraries or developers who primarily work in Java or certain other high-level languages that lack operator overloading, but may feel very clunky to C++ developers.

Aspiring JavaScript graphics developers should thus first get accustomed to the procedural nature of glMatrix. In order to use a glMatrix vector, you first have to create a vector to operate on. This is done using the vec3.create() function:

Fairly straight forward. At this point, you can perform operations on the vector by passing it to one of the functions in the vec3 "namespace" like so:

That's also pretty simple. An important point to be aware of is that the vec3 operations take an optional destination parameter for most functions. This parameter (always the last one) is a vector to store the result in. If this is not given, most functions will treat the first parameter as the destination. So the commands above could be written (equivalently) as:

That functionality is important for optimizing your code. In many cases you will need to take a vector and perform some operations on it to get a new vector, all without modifying the original one.

Note, however, that the destination vector must already exist. That is, you must call vec3.create() to allocate a vector before passing it to any of the other vec3 functions.

References

By far the biggest problem that most developers will run into while simply trying to use the glMatrix library is that all of the vectors are technically objects, and hence are passed and returned by reference rather than by value. So the following function will have a side-effect on its parameter:

The code is simply, but it will modify the line vector parameter ('b' in the example above). The result then is that reflect() modifies its second parameter to be the reflected vector. Furthermore, in the code above, b and c will reference the same vector at the end.

That's really annoying. And there's not much you can do about it. Don't think to fault glMatrix for this behavior, either; it's pretty much a given in JavaScript (and, in fact, almost every other single language in common use, including Python, Java, and Ruby). Most languages do not allow developers to create user-defined types the way that C++ does, and so all custom types end up being fully heap-allocated objects that are always passed by reference.

It's just something you need to be aware of and to deal with.

A first hack at fixing the above problem might be code like this:

That does indeed solve the reference problem. Neither of the parameters to reflect are modified now, and the test variable c will reference a unique vector rather than being an alias of b.

Unfortunately, this introduces a second problem. Each call to reflect will now create a new vector object. This leads us into our next section on garbage collection.

Garbage Collection

Most modern languages feature automatic garbage collection of some form, and JavaScript is no exception. This little marvel is what allows developers to not have to care about memory allocated and deallocation, taking care of everything for you. Unfortunately, a slightly more cynical (and for our purposes, accurate) way of looking at garbage collection is that it does everything behind your back without your approval.

With a library like glMatrix (or any of its alternatives), each vector is a JavaScript object. That means it is allocated on the heap and needs to be freed when it is no longer in use. And that means that the garbage collector has to do all kinds of work to find and free the object. It also means that the more vectors you create, the more memory will be used until the garbage collector is triggered. And thus, a tight loop performing some heavy math can trigger a garbage collection run, and that in turn can be deadly for a game's performance if there are a lot of little wasteful objects (like vectors!) floating around. Even the best collector in the world today can and will impose a noticeable bit of latency in any kind of intense real-time application, like a game or other interactive simulation.

It turns out that you just can't escape the need for a developer to understand and maintain tight control over memory usage, allocation, and deallocation, no matter how high level of a language the developer is working in. A garbage collector in our case is hurting more than it's helping, but thankfully we can do quite a bit to work around it.

What we need is to drastically reduce the number of vectors we create. That in turn means being very, very stingy about how often our code is ever allowed to call vec3.create(), or to use any array literal constructs (like [1, 1, 1] in the code above, which creates a new Array object every time it is executed).

Our sample reflect function above has a problem. Every time it is called, it creates a new vector. If we were to be using reflect in a loop operating over a few thousand rays, we'd end up creating a few thousand short-lived garbage vectors every time the loop is run. That's not good.

We can take a page right out glMatrix's own book to fix this, however.

What we've done there is to add a third out parameter to the reflect function. We're not responsible for creating a vector to pass in, as the example test code does. At first blush this doesn't look like much of an improvement; all we've done is move the call to vec3.create() from one place to another.

However, let's say we were calling reflect in a loop:

That new reflect_all function didn't require any new allocations to made at all. Assuming your data structures are designed with this requirement in mind, you can easily write quite a bit of useful code in a similar fashion. In other cases, you won't be storing all of your calculations, and you may just need a temporary vector or two. This can be done by creating these temporaries at the top of the function, outside of any loop, and then reusing those temporaries inside the loop, overwriting their previous values each time. You can reduce your vector allocations from dozens, hundreds, or thousands down to just several for each such loop.

Extreme Ninja-like Avoidance of Allocations

Sometimes you've got to have a few temporaries in a function, and sometimes that function is itself going to be called hundreds or thousands of times. Those temporaries continue to be a problem that need to be thwarted. What to do?

One option is to make the temporary variables globals, that are allocated once when your application starts up and never again. If you're using a module system like node.js's, this isn't too hard. If you're just using plain JavaScript source files, globals will "pollute" the global namespace and can be a real problem. You might want to name your temporaries something easy and simple, like tmpv1 and tmpv2, but then you'll easily get conflicts with other source files that create their own same-named temporaries. You can't easily just share temporaries between different modules, either, because you can't be sure of the scope of a global.

The scope problem is a big issue if you use global at all, so I'm going to cover that in a bit more detail. Let's say you have a function foo() that calls a function bar(). If both of these functions try to use the same global variable as a temporary value, something bad will happen: bar() will overwrite whatever value foo() had stored in that global. What this means is that any function using any particular temporary value cannot call or be called by any other function using those same variables. So globals just aren't safe.

There is a solution, however. It's to my thinking a little bit of a hack, but others may well consider it a beautiful exposition of the power of JavaScript. The trick is to create your functions as closures that bind their own temporary values.

Here's an example:

That code essentially gives the my_function() function its own private "global" variable, with semantics similar to what you'd have with a statically allocated variable in a language like C++. It allows each function to have the temporaries it needs, allocated once and once only, without any risk of collision with other functions.

Strongly note that there is still a scope problem that can arise in with this trick! These functions are not re-entrant, which means that they cannot be used for recursive algorithms at all. This means that if my_function() calls itself -- or calls into another function that eventually calls into my_function() -- then the outer invocation's data stored in its tmp variable will be clobbered by the inner invocation's data. This trick can thus only be used for functions that do pure computations, and not for any functions that invoke any kind of callback or further processing which might ever call the function again. In practice, this has not been a problem for any of our own code, but it's something to be very aware of should you choose to use this performance optimization.

When Nothing Else Works

Sometimes there's just no getting around the need to create a temporary. If this is in some outer function that's called a few times at most per frame, that's not much of an issue. If it's a bit of code that's going to be called many times, though, it's a huge problem.

In these cases, you just have to accept that you can't use glMatrix at all and use hand-rolled code. In a simple example, you might have to change this code:

into this code:

It's a lot uglier, and passing those kinds of "vectors" around as parameters is painful, and you really want to avoid doing this if you can, but sometimes you just don't have a choice.

Do note that there are very few alternatives to the ugly code above when you're in this situation. In particular, do not simply try to create an array or object of your own as a temporary. Any kind of value other than a boolean, number, or null is going to create a garbage-collected object, and you'd just be doing extra work for absolutely no gain over just using glMatrix directly.

Other Considerations Besides Vectors

The last paragraph of the previous section brings up an important point: every single array and object you create will eventually be garbage collected. Possibly even worse, every array or object you create has to be scanned by the garbage collector (in most implementations) just to see if any other objects are garbage or not. You want to keep your total object count reasonably low, and not create a lot of garbage objects.

A pattern we initially used in a few too many places in SONAR was to use an object as a way of passing optional parameters to a function. These functions often had a large number of optional parameters. Without the params object parameter, their callers looked like this:

That's hard to read (impossible to read if you don't know what the parameters do, in fact) and just as hard to write. Were JavaScript to offer proper named parameter support, this problem would go away quite nicely. Unfortunately, JavaScript lacks that capability, so we are stuck improvising.

Ignoring that we don't know what foo() actually does, that is quite a bit clearer. The boolean parameters have a lot clearer meaning, and when we wanted to just pass in that final parameter we didn't have to remember to pass in exactly four nulls first.

Unfortunately, this just doesn't fly for a game in a frequently-called code. See, now each call to foo() is creating a new temporary object to pass in for its parameters. We're back to garbage collection problems.

I called out this example because they can be almost invisible to many programmers. It can be sometimes hard to remember that the object (and array!) literals syntax in JavaScript create a new object each time the relevant line of code is executed.

There aren't many work-arounds. Simply be aware of the problem, and avoid trying to make short-cuts (even ones that really make the code cleaner) in performance-sensitive code. Also, help raise awareness in the general Web community as to why having a proper named parameter facility is super important even if the language supports "easy hacks" to simulate them; HTML5 game developers will thank you!

(And while you're at it, help everyone understand why having user-defined stack-allocated pass-by-value types for things like vectors is so critically important, too!)

XMLHttpRequest

The first problem to solve is how to actually load our files into the browser with JavaScript. We obviously don't have simple File I/O APIs for requesting data from remote sites, and even the newer file storage APIs only work for files we've already saved with those same APIs. To load an arbitrary file from an arbitrary URL, we've got pretty much just one option: XMLHttpRequest.

The problem is, XMLHttpRequest was really designed for loading (you guessed it) XML. It also supports plain text quite easily. Getting arbitrary binary data into it is a bit trickier. There's a lot of bad or just out-dated advice floating around the Internet, including the use of custom MIME overrides ('text/plain; charset=x-user-defined') and the like. Thankfully, the newer browsers instead give us a neat work around. We can explicitly tell our XMLHttpRequest object what response type to use, and we can set this to 'arraybuffer' to get the file loaded up into an ArrayBuffer object.

Now we've got the binary file loaded up into an ArrayBuffer. Unfortunately, we're not done quite yet.

Typed Array Views

In theory, we can access parts of our binary file using typed array views, e.g. Float32Array or Uint8Array. Unfortunately, some browsers are (at the time of writing) suffering from a few bugs with these newer JavaScript APIs. The one we've run into specifically is that a typed array cannot use a backing ArrayBuffer that isn't sized to a multiple of the typed array element size. Normally this would be a non-issue when using the proper typed array constructor, but due to the bug a work-around is necessary.

To explain the issue a bit better, say we have a binary 3D mesh file, which consists of a list of vertices (3 floats each) followed by a list of faces (3 Uint16 indices each), and the file also has a header consisting of two Uint16 values (the vertex count and the face count). To read the data, we might do something like this:

However, due to the aforementioned bug, we can get a RangeError exception in this code if the mesh_buffer length is not a multiple of 4, due to the Float32Array constructor essentially ignoring the length parameter (the third parameter).

Our work-around originally was to pad out the ArrayBuffer after reading it in. This was a bit hairy, however, as there is no way to resize an ArrayBuffer nor is there a particular straight-forward way to copy one ArrayBuffer into another.

What we settled on was to actually to make our mesh exporter plugin for Blender pad the files out as necessary. Aside from being ever so slightly simpler to implement than padding the buffer in JavaScript, this also means that the overhead (however negligable) of padding out the buffer is performed once offline rather than during asset loading by every player of our game.

Resource Management

Now that we've got the bits of code to load an individual file and parse its contents, we have a bigger problem to solve: how do we load and keep track of all these resources?

The first part of the answer is a simple ResourceManager object that tracks resources we've loaded as well as providing a "load filter" mechanism. The load filter is a means of registering a function for a specific file type/extension that will process the raw binary (or JSON or XML or plain text) files and return an appropriate object that our engine expects. The mesh loader for instance will parse the binary files, create an object with the vertex_count and face_count properties and arrays for the data, and allocate a WebGL vertex buffer with the data pre-loaded (and indexed).

The resource manager itself just has a simple table of resource names to data files.

That's a pretty simplified version of what we use, but it covers the main bases. The one exercise I'll leave to the reader is how to handle unloading of resources, which is important when a resource might have a handler to a WebGL buffer (as with our mesh resources, for example).

That let's us query loaded files and insert data we already have on hand, but that doesn't solve the problem of actually getting the resources into the engine. This is where things start to get a bit trickier.

Batch Loading

In an ideal world, we'd be loading a packed file with all our assets in it in one go. This is what the Big Boys do, it's what Flash does, and best of all this is even possible in JavaScript (with a bit of work). However, this is not particularly convenient during development. We want to be able to easily swap in and update new assets without needing to run any pack utilities. Additionally, sometimes you might want multiple pack files, so you can run into the same problems you have when you don't have pack files at all.

The primary problem is loading a list of files using JavaScript's asynchronous APIs and then signaling to the engine that all requested resources have been loaded. The secondary problem -- and a slightly harder one in some ways -- is making sure this signal is only sent when all dependent resources are loaded. For instance, an animated character may have several resources required, such as the skinned mesh, animations, and textures. Going with a nicely data-driven approach, these resource names will not be hard-coded into the engine, but instead will be specified by another reason. The blueprints file will specify an animated character resource, which in turn specifies the mesh and textures and so on.

What we need then is a system that can take a list of resources, load them, process those files for any dependent resources, and continue loading files until the queue is empty. Then and only then should the engine be signaled that all resources have been loaded.

Furthermore, actually loading resources can be a bit tricky in places. For loading most file types, there is only XMLHttpRequest. For loading unpacked images there is also a regular Image object. When using XMLHttpRequest, the actual data may be in one of several different properties of the XHR object, including response, responseText, or responseXML.

I'm going to keep things simple for this bit of the article and only cover JSON files. Extending it to handle binary files (including images), XML, and other formats is not terribly difficult once the core is written.

Our strategy is to build a BatchLoad object that encompasses a queue of resource URLs to load and a callback function. As each resources loads (or errors out) a modified version of the filter function specified above is run on the loaded data; this modified filter also takes a reference to the BatchLoad object so that it can add additional files to the batch. After the filter is run, if the queue is empty then the batch is considered complete and callback is invoked.

Using this is relatively simple. Our core engine has a few files it depends on. The object manager loads up our blueprints.json file, our graphics system has dependencies on world tiles, the UI system has dependencies on an layout XML file, and the campaign manager has a dependency on our campaign.json. Almost everything else is loaded as a dependency of one of those files.

The core engine creates a BatchLoad object and passes it off to each system component of the engine. Then it calls the run() method, and the callback is what starts up the engine's main loop (via the requestAnimationFrame() function).

We have filters set up for our character file format, for our blueprints file, and for a few other key assets. The blueprints filter doesn't actually change the blueprints JSON file any, but instead it scans the defined blueprints and their components and passes the component data off to a preLoad(batch) method on related component constructor. This method can then use its knowledge of the component field data to add files to the batch. For example, the "mesh3d" component's preLoad() method knows that the the "texture" property value should be queued up as a request for assets/textures/[texture].png.

Here I mocked up some simple low-poly models I sketched and rigged in Blender.  The purpose of this was to get all necessary animations mocked up so that only the file would need to be replaced as I made new ones.  In other programs, it is also simpler to edit the mesh on the rig and replace the weights.  Not so in Blender.  It's definitely good to know there is going to be a hiccup so that you can plan around it, which is why working on multiple art assets can be quite useful.

rough 3d sketches

The down side is that it can look quite unfinished and ugly.   There is another upside, which is being able to make changes as you go along, and discover whole new possibilities as you work.  I find this to be much more fun than trying to make everything fit to a single idea.  Of course, the artist always has to keep in mind the overall visual style, and there is a stopping point, which we are quick approaching.

ugly but effective

Here's an example of testing assets before you get to the final product.

painting over the real thing

And then exploring to see how we really want this to look.

The current sprint will see finalized character models and well close to done animations and UI.  In order to be able to finish both 2D and 3D assets by the deadline, we've pulled in another artist with strong 2D and UI skills.  A lot of work has gone into finalizing concepts for the look of the game.  The next few images are some of the best ideas from those pages.

As we both work furiously on getting final designs, colors, tiles, backgrounds, animations, models and all other things that are art related done, there is very little time to dilly-dally.  We  look forward to being able to take you through the entire process in the next blog post at the end of this sprint.

When developing SONAR's art pipeline, we had a few things to consider:

• We're a very small development team. We have 2 artists, 3 programmers, and 1 designer. This means there is very little barrier to communication.
• We have very little time to go from nothing to a fully featured game. Thus, we can't spend a lot (or, really, any) time polishing the engine or pipeline any more than critically necessary.
• WebGL is a very new and very limited platform. We needed to keep everything as simple as possible in order to ensure a smooth, integrated pipeline.

Blender

After weighing our options, we decided to use Blender as our core 3D tool. Blender is capable of both modelling and animation, I was personally familiar with it from previous projects, and it gives Python scripts access to all the data we would need. Whether or not we'd use Blender in retrospect... is not the purpose of this blog post. However, the first thing we would need is to get meshes from Blender into the game engine.

The first thing I realized is that Blender 2.5 has very little documentation when it comes to its Python interface. The official documentation is definitely useful to see what exists, but the data Blender offers is very cumbersome to correctly utilize. Luckily for you, I'm going to explain how. Another resource that you should have ready is the built-in Unreal Engine exporter, which you can find in <blender>/2.57/scripts/addons/io_export_unreal_psk_psa.py.

Scripting

This code assumes you have the mesh you want to export selected. It then converts any quads in the mesh to tris (which is necessary for our in-engine format, which we'll discuss later). Finally, it captures the mesh after applying modifiers (that True parameter).

Now, I just get references to the vertices, faces, and uv data from the mesh. This will fail if the mesh doesn't have UVs (in which case, just skip that). Each face is a list of indices into the vertices list. The UVs are slightly more complicated: the index into faces can be used to index faces_uvs to get a similar list of UVs for each vertex, using the same index as vertices. I simplify access with a function similar to getUV.

Next, I make an empty Vertex class that I use to store each vertex's data in a format closer to the one I will then output to file. I also create a dictionary to store these vertices in. I would use a list, but a dictionary using the vertex index as a key will ensure the vertices are all unique.

Then, I iterate through each vertex in each face. I create the Vertex object, store the data about that vertex, and add it to the dictionary. Pretty simple.

Mesh Format

From there, it's about outputting this data to a file. I have created both JSON and binary exporters, and honestly JSON is the better way to go. It's significantly simpler to get into a Javascript game engine (binary file loading will be a future blog post). It's also easier to read and write (it's such a simple format, there's no need for specialized tools). Really, it's just the way to go.

Specifically, I simply store this data as one giant Array of floats. This Array is structured the same exact way as the Float32Array I end up binding to an ArrayBuffer in WebGL in the engine. Simple. Simple simple simple.

Animation, Into the Engine, and More!

Obviously, this is just step 1 of many in our pipeline. Future blog posts will almost certainly focus on: skinned meshes, animation systems, binary file loading, resource loading, resource management, and oh so much more. If you have any suggestions for future articles or any questions about what I've talked about here, post about it in the comments!

Traditional Inheritance

The traditional inheritance model used in many OOP projects stems from a deep misunderstanding of the purpose of objects and interfaces. Classical examples of how inheritance works are taught in schools that illustrate relationships like "a dog is a mammal is an animal" which implies a hierarchy of relationships between types. Programmers will implement a model that includes three classes, one for Animal, one for Mammal, and one for Dog. Another branch of the tree might be Gecko which inherits from Reptile which inherits from Animal. This works okay-ish in a small project with a few classes, but then the programmer eventually needs to add Platypus to the project and the entire hierarchy becomes a huge design problem. Methods and data members that originally could be confined to a particular branch the tree (like LayEgg in Reptile) ends up moving into the base Animal class (because now one of the Mammals needs it, too). Eventually that base class becomes full of dozens of methods and members that only a tiny fraction of its derived classes ever need but which simply cannot be put anywhere.

The problem in such an example is not that classical OOP facilities are bad but rather that they have been used incorrectly. Real-world relationships and objects were modeled in code rather than modeling the abstract behaviors and interfaces that the real-world objects are built from. Programmers are taught to "write to the abstraction" everywhere else, and that's exactly what makes sense for objects as well. Instead of having a subclass of Animal called Reptile that adds a LayEgg method, and a Mammel subclass that has a LiveBirth method, it makes more sense to add a new Reproduction interface with a single Reproduce method and to then write egg-based and non-egg-based implementations of that interface.

With the inheritance model, however, we're still stuck wondering where exactly to put these interface implementation objects. Each animal instance needs one and only one. The specific implementation chosen is dependent on the type of animal. We could come up with a complex system of virtual methods and multiple-inheritance to fix this, or we can use compositions.

Compositions

The compositional model solves the above problem by simply allowing the base object class to contain a list of other objects that implement various bits of functionality. In our above case, we'd have a single Animal object, and it would not have any derived classes. It also wouldn't implement much functionality at all, either. Instead, each Animal contains a list of objects that implement the IComposition interface (any likely some other interface as well) each of which for satisfies an individual behavioral requirement. For each real-world animal we wish to model we would simply create an Animal object and add all of the necessary components to it that the animal needs to function. Each Animal might have a single component that implements ILocomotion, which could be any one of Bipedal, Quadrupedal, Snakelike, etc.

Notably, as there are no derived classes from the core base object, that means that we don't have an object constructor to create specific objects. There is no Dog class that could create all of the necessary components at initialization time. We can make up for this by simply creating some functions (or special factory objects) for creating each specific type of object, of course, but that would cause us to lose the second huge advantage of compositions: data-driven object building.

Unlike the inheritance model, compositional objects can be created by designers and editors rather than only by coders. Let's replace our animal metaphor with something more game relevant. We're going to have a base GameObject class and components for PhysicsBody, DrawableMesh, Gun, TargettingAI, ChasingAI, etc. We are making a game where the player can build units to defend an area: an RTS or a tower defense game of some kind.

The designer asks for a unit that has a Gun and shoots to the right and a tank that can chase enemies and shoot at them. This is very easy to accomplish by simply giving each of these units the proper components. Both units would need a Gun component, but only the tank needs the ChasingAI component and TargettingAI component. This can all be specified in a data-driven approach without any coder needing to be involved.

The structure of the units could also be build easily with inheritance, of course, right up until the designer asks for a tower that targets enemies. Now all the TargettingAI that would be in the Tank class (which might derive from a MobileUnit class that derives from BaseUnit) also needs to be in TargettingTower (which is derived from TowerUnit that derives from BaseUnit), so it ends up being moved into the BaseUnit. Which must be done by a coder. Composition avoids both of those problems, the first by allowing TargettingAI to be added to any game object and the second by allowing the designer to just add the TargettingAI component to the unit definitions in the game editor rather than needing to request a programmer to do so.

Archetypes

Archetypes (also commonly known as prototypes, but we'll avoid that term as JavaScript already has a different idea of what a prototype is; I personally also like to call them blueprints) are the definition of a spawnable game object, including it's components and their default properties. In the above example, we might have archetypes like "tank", "simple_tower", and "targetting_tower". These are loaded from a data file, and can be easily edited by designers, either by hand or with a friendly graphical tool.

With JavaScript, it's easy to define an archetype using JSON. Our file that describes all our known archetypes looks something like the following (an excerpt from SONAR's archetypes.json file):

That example defines two archetypes, one for slow_enemy and one for player. The data inside specifies the components of the archetype (the keys) and the component parameters (the value). Components that have no parameters to specify just have an empty object as data.

Being data driven, this lets our designer add new enemy types or tweak existing ones very easily. If the slow_guard speed turns out to be too slow during a play test session, for instance, the designer can just bump that value up and carry on without needing to dig in code or ask a coder to make the change. (In a traditional C/C++ engine, this also saves the need to recompile!)

Level Files

There's an additional benefit to having a system that parses a JSON file to load components and values, too, which is making it amazingly easy to customize individual units in our level files. We merge object definitions from our level files with the archetypes they "inherit" from to create a single game object definition that we pass into our game object factory.

Let's take a look at a level file fragment:

The definition for each object includes an archetype name and a list of components and properties, just like the archetype definition file. Essentially all we do during level initialization is look up the archetype for each of these objects, merge the archetype definition and the object definition from the level file, and then pass that object to the game object factory.

The most basic use of this is for specifying position in our level editor. The editor can override the default position of the Transform component (which specifies position, rotation, and scale) with the position the object should spawn at. With a few exceptions this is about all we do in our particular game; as a puzzle game, we need a high amount of conformity between enemies and objects to make the puzzles understandable and predictable. In a more action-oriented game, however, it may be interesting to be able to specify equipment or weapon systems or other stats on a per-object basis.

The Code

In a C/C++ engine, there'd be an awful lot of boilerplate to make all this happen. In JavaScript, it's all pretty simple. Let's just jump on in with a sample game object and component type that we might use in a simple game engine. The following code is a simplified example, but illustrates the basic concepts of what we're doing in SONAR.

It's not too bad at all.

The GameObject type handles construction of the components on the game object. We have a factory function on the GameObject constructor (rather than a per-instance method) that takes the object data loaded from our level file. It looks up the archetype's base component definitions, and merges those with the individual object definition. This is passed to the GameObject constructor to create all our components and initialize them.

The event method is a simple thing that gives our game components a way of processing game logic events. The GameObject handler simply forwards its events to the components.

Various components handle different events as they see fit. Components like the TransformComponent doesn't process any events, as it's simply a data holder that is used by other components. The Physics component will respond to several events, notably the update event, which is sent to every game object once per frame with the frame time; the physics component would do integration in response to this event.