In the past, I’ve discussed the importance of using version control and also ways for structuring your subversion repository. Today, I’d like to cover an important best practices with version control whether you are a lone wolf developer or you frequently travel in a pack.

After you’ve wrapped your head around version control (and I’ll be honest, it baffled me the first time I was forced to use it), there’s only a couple more best practices you need to be aware of to get the most out it.

Don’t Commit Conflict Bait

Conflict Bait is basically something that’s going to generate conflicts pretty much any time a team member updates from the repository. A good example of Conflict Bait is the swf file that your project generates when you build, or intermediate build files that your IDE might generate. Don’t put these in the repository, because you will publicly mocked by your more senior team members when they are forced to remove them.

Exceptions: This one isn’t such a big deal if you’re the only person working on a particular project. When you are rocking it solo, it can sometimes be useful (read: lazy) to let version control track your builds so can look up old versions without checking out a fresh copy of the whole repository.

Write Comments In Your Commit Message

This one is a bit of a “Duh, really?” When you’re going back over a log of 1,000 commits, you’re going to be sorry you didn’t leave the breadcrumbs to help you track down that bug in that feature you haven’t tested in over 3 months.

Only Commit Verified Builds

Don’t commit code that breaks trunk. If you do, you will be shot and beaten. Resist the urge to commit that untested feature right before you sign off for the day. This is the absolutely WRONG thing to do. Perhaps your fellow coders were planning a code binge that night and your last minute tweak sends them on a 4 hour bug hunt instead. Don’t do this to your teammates.

Exceptions: This again is more applicable in a team environment.

Close Your Open Files Before Updating

Sure, Flash Develop or Flex Builder will usually warn you when a file has been externally updated and ask you if you want to reload. Usually. In my life, I’ve wasted at least 2 day’s work undoing the damage caused by accidental overwrites after the IDE failed to recognize an update changed a file. Close your open files, then update. Don’t be that guy, really.

Make Your Commit As Small As Possible

You might think you’re awesome by making monolithic commits, but you’re really just overcompensating. The best commits are ones that are as granular as possible. This is a good practice for numerous reasons, and one that helps support many of the other best practices already mentioned.

1. It keeps your project manager informed of your progress. If you’re making commits every 5 days, it doesn’t matter how big they are, you still look like you are not pulling your weight when your project manager gets his daily commit log and your name isn’t on it.
2. Your commit becomes easy to refer to because of its unique revision ID. It becomes an entity that can be referred to, entered into bug databases, etc.
3. When you’re digging through logs that have one succinct change applied to a single file, it is far more useful than a commit log that is 9 pages long and involved 30 files, which may or may not be related to your current search.
4. Your commit becomes easy to undo. Let’s say you really screwed things up and totally broke a feature (and then went to bed for the night). Your team members can see quickly from your commit log that revision 324 was a granular commit related to that feature and is likely the source of the issue. They can roll back the change and move forward while just cursing you briefly.

I’ve been using version control in a team environment for about a decade now. Hopefully this helps you benefit from some of that experience.

One case where you might be tempted to copy/paste code is when you’re performing some logic on a group of related objects. In the following example, we test the neighbors of our tile to see if we are surrounded by sea. This technique can be applied effectively to many other scenarios, however, like initializing a set of buttons, or aligning a bunch of logos.

var isSurroundedBySea : Boolean = false;

var leftTile : Tile = map.getTile( m_currentX - 1, m_currentY );
if( leftTile != null && !leftTile.isSea() )
{
    isSurroundedBySea = false;
}

var rightTile : Tile = map.getTile( m_currentX + 1, m_currentY );
if( rightTile != null && !rightTile.isSea() )
{
    isSurroundedBySea = false;
}

var upTile : Tile = map.getTile( m_currentX, m_currentY - 1 );
if( upTile != null && !upTile.isSea() )
{
    isSurroundedBySea = false;
}

var downTile : Tile = map.getTile( m_currentX, m_currentY + 1 );
if( downTile != null && !downTile.isSea() )
{
    isSurroundedBySea = false;
}

Copy/pasting has bloated the size of the code and made it incredibly brittle. If we need to modify the basic logic of the query (like perhaps testing for a modifier called “Sea” instead), we have to hope we remember to do it in all 4 places, and to do it correctly.

Never fear, though, Mr. For-Loop is here to save us. What I like to do in this particular case is plug all the objects into an array and then use a for-loop to make sure the code is written only once:

var isSurroundedBySea : Boolean = false;

var neighbors : Array = [
    map.getTile( m_currentX - 1, m_currentY ),
    map.getTile( m_currentX + 1, m_currentY ),
    map.getTile( m_currentX, m_currentY + 1),
    map.getTile( m_currentX, m_currentY - 1 ) ];

for( var n : int = 0; n < neighbors.length; n++ )
{
    var neighbor : Tile = neighbors[ n ];
    if( neighbor != null && !neighbor.isSea() )
    {
        isSurroundedBySea = false;
        break;
    }
 }

Not only is it faster to write this code than it is to copy/paste all that junk up there, the code is significantly more robust because we’ve converted 4 potential sources of failure into (basically) one.

You have to be able to write bug free for-loops to use this trick effectively. But I’m pretty sure you can handle that.

There are a few Open Source Actionscript projects that Urbansquall relies on for most of its games. Here’s an overview of the three open source tools that we’ve found essential to Flash game development.

BulkLoader

For any project where we need to load external files, we’ve come to rely on BulkLoader. If you’ve ever tried to load a few hundred files at once with AS3, you know that at some point Flash will fail fairly silently and just refuse to load the data you require. That’s where BulkLoader fits in. When you try to load something with BulkLoader, if its there it will arrive. No exceptions.

Box2D

Box2D is quickly becoming our de facto solution for anything related to 2D collision detection and resolution. There’s not much to say about Box2D except that it was the first Flash physics engine that did it right, and it quickly destroyed all the competition. We <3 Box2D.

Tweener

I feel dirty every time I use Tweener, but its ease of use and raw power makes it the most common open source actionscript we rely on here at Urbansquall. Even the most stale UI can be made to pop after a few hours in bed with Tweener.

Others?

There are plenty of open source Actionscript projects out there, here are some we hope we get to play with sometime in the future:

• Papervision3d – 3D Engine
• SPAS – UI framework
• AsWing – Another UI framework
• FAR – zip support

Of course we rely on the gamepoetry open source resources more than anything else.

The article has some great suggestions (like stealing poses from existing sprite sheets), but I can’t help but feel the author is discounting his natural artistic talent. Either way, it’s worth tackling the full article.

Every now and then you come across a solution to a problem you never knew existed. Squize over at Gaming Your Way blew my mind this week when he posted a quick overview of how he supports the concept of state machines in his code. The solution is so simple and quick that I couldn’t help but just say “Wow!” when I read it.

You can learn about his implementation here. There are a number of things I like about this solution:

1. It uses built-in language functionality. This means you don’t have to do any fancy imports or copy paste code from old projects because there are no external dependencies. This can help make your code more maintainable and portable.
2. It can be incorporated into existing code with minimal effort.
3. It is simple to understand and discuss.

The biggest draw back I have with this particular implementation is there is no concise way to manage state-specific data. For example, if you have two entity states, idle and attack, the attack state would need a target but the idle would not. In a more engineered solution (which doesn’t necessarily make it better), each state would track and manage its data, so that the idle functionality didn’t share logical space with the attack functionality, which has this distinct target data. It’s not a deal breaker by any means, and I think that for all but the most complicated state machine functionality, even with this drawback, this solution wins out because of the reasons stated above.

Thanks Squize and Gaming Your Way!

As I mentioned before, Subversion is critical to daily development at Urbansquall. Subversion has a lot of really fancy features that can help make development a lot less stressful even for a lone developer. Today I’m going to go over one of the features that we’ve found particularly useful working in a team, and that is the concept of Trunks, Tags and Branches in a repository.

The simplest way to use Subversion is simply to dump everything into some sort of structure in your repository and then to go about your business. The reality is that this is more than sufficient for a lot of projects. But, particularly for projects that will be evolving as they are reused over several years, like a networking library for example, or a larger game that is being worked on by 4 people at any given time, the concept of Trunks, Tags and Branches can make it a little easier to keep people from stepping on each other’s toes as they are going about their business.

Trunks

Trunks is the easiest part of the TTB paradigm to understand. The Trunk is basically equivalent to what your repository would have been without using TTB. Trunk represents the active state of development shared by the majority of the team, and is assumed to be a non-official release that is in a buildable state.

Tags

Tags are most useful when you want to flag a specific state of the Trunk. Let’s say you’ve officially hit 1.0 and you are ready to do a public release. You might Tag trunk at 1.0 as you do the release, and then start development on some 1.5 features that you want to include. In this case, a user might find a bug in 1.0. You can’t patch your pre-1.5 version trunk because your 1.5 features are incomplete and shouldn’t be released. Because you tagged 1.0, you can check out that specific tag, make your bug fix, and then cut a 1.0.1 build that fixes that bug but doesn’t introduce any of the messiness of your partially implemented 1.5 features.

Tags are essentially a stamp for a noteworthy state of the Trunk that might be useful to return to in the future.

Branches

Branches are the trickiest part of the TTB paradigm, but they are probably the most useful. Branches come into play when we are considering actions that would disturb the Trunk or make the Trunk otherwise unbuildable. A good example we had recently on a project was that we had to recode the vast majority of the networking layer that a game was using. The game was working fine with the current networking layer, but the new networking layer would deal with a lot of the lag issues we were experiencing. The problem was that this networking layer rewrite was going to take weeks and would affect at least as much as 40 source files in the game engine itself. We used branching here for the following reasons:

1. The rewrite was complicated and would require many iterations, and we wanted the benefit provided by SVN in terms of being able to revert or inspect the revision history.
2. The game was undergoing active development from other developers at the same time the engine rewrite was occurring. We needed to make sure that all these updates would be merged into our rewrite so that no work was lost and also that we didn’t prevent these other developers from working while the networking engine was in a half-working state.
3. We weren’t sure that the rewrite would even work, so we wanted to be able to throw it away if failed.

So, we branched the code, rewrote the networking engine, and made sure we updated against Trunk frequently to keep up with everyone else’s commits. When the new networking engine was stable enough to replace the old networking engine, we could simply merge the Branch back into the Trunk without affecting the other developers who had been working on the project.

Structure

It’s easiest to put TTB into your project at the start. SVN actually makes this almost stupidly easy. At the root of your repository, just create three directories: trunk, branches, tags. Leave branches and tags empty and then put everything (source code, docs, art, etc.) into trunk like you would have done before. When you do your checkout, instead of doing “url.com/my_repository” you would now just checkout “url.com/my_repository/trunk” and you can forget about it until you find you need it one day. That’s pretty much it, if you find you need to do a Tag or a Branch in the future, you simply right-click on your Trunk folder (assuming you are using TortoiseSVN), and choose Tag or Branch as appropriate.

The specifics of Branching can get a little more complicated, so I suggest you do a little more in depth reading into the topic when you think you might need it just so you can make sure you do it correctly. It’s not complicated but there are some gotchas that you will want to understand first.

Conclusion

The TTB paradigm is not a complicated one. It stays out of your way until you need it, and it only requires a moment of effort to set up when you are first getting a project going. If you think you may have some use for it, it might be worth doing a little more reading on the subject, as SVN supports TTB quite well. It is very efficient at storing Tags and Branches, and you can typically do both while adding only a fractional increase to the size of the stored repository because SVN is smart about storing only the changes between the Trunk and the Tags or Branches (rather than an actual deep copy).

API Design

As a Flash game developer, you’ll find yourself interacting with all sorts of APIs designed and implemented by third parties. Because most libraries aspire to being popular, they generally strive to include as many features as possible, and support all manner of possible interactions with their API. Few API designers take the time to consider what primary motivation drives the user of their API. Programmers are elitist snobs. Generally speaking, the only time we are willing to consider dirtying our pretty code with someone else’s, is if its going to save us time (and therefore money).

When I began this article, I intended to point to some specific APIs that I use regularly whose designers failed to take this into account. Being that I still use these APIs on a regular basis, I decided it was best not to ruffle any feathers and instead just talk about how to apply this strategy instead. For fun, though, I’ll post some DirectX code here that I’ve always thought was a particularly heinous trespasser in this regard.

void initInput(HINSTANCE hInstance, HWND hWnd)
{
    DirectInput8Create(hInstance,
                       DIRECTINPUT_VERSION,
                       IID_IDirectInput8,
                       (void**)&din,
                       NULL);

    din->CreateDevice(GUID_SysKeyboard,
                      &dinkeyboard,
                      NULL);

    dinkeyboard->SetDataFormat(&c_dfDIKeyboard);

    dinkeyboard->SetCooperativeLevel(hWnd,
                                     DISCL_NONEXCLUSIVE | DISCL_BACKGROUND);

      return;
}

Note: I’m not saying this code is necessarily bad. Instead I’m trying to illustrate that there really is no good reason to require an application to specify much more than a single line of code that requests an initialized keyboard object. Sure I might sometimes care about all that other crap, but why make me bother with it every time I want keyboard controls? Also, Hungarian notation! So much fun!

A reasonable rule of thumb when approaching your API’s design is this: If I am trying to accomplish a single task, give me an opportunity to do that with one action, or at most two if reasonable technical restraints require it (like an asynchronous interaction). As soon as you want me to create 15 different interrelated objects that all require special customization, listeners and handlers, just to accomplish a single task, you’ve just eaten into the main reason I decided to use your API in the first place, and that is to get where I want to go quicker.

Because flexibility is so important to most API designs, I don’t want to suggest that we can get away with simple APIs. Instead, I want to suggest that the API assume that the defaults are sufficient unless the client code specifies otherwise.

To further illustrate the point, here are some basic examples of where we might want to make assumptions to simplify our API:

1. Assume that I want the mass of my physics shape to be proportional to its size, unless I say otherwise.
2. Assume that I want to connect using the most efficient protocol possible, unless I say otherwise.
3. Assume that I don’t care about being notified about the completion of an event, unless I say otherwise.
4. Assume I don’t care about hidden files, unless I say otherwise.
5. Assume I want you to save the file when I write to it, unless I say otherwise.
6. Assume that I’d rather use the file system to manage my assets than some convoluted proprietary library, unless I say otherwise.

What I’m trying to get at here, is that by making assumptions and providing smart default choices for our API, we eliminate the number of things the user needs to learn (and just as often relearn) when working with our code. We are qualified to make the smart choice for our user because we know what we’re doing, which is why we built this API to begin with. Sure, the user is entitled to override our default choices with something that’s more specifically tuned to his application. But our defaults are invisible to the user. We can potentially eliminate one more thing the user needs to learn for every part of the application where we can put in a smart default choice rather than relying on the user to get involved.

API Design Trumps

There are really so many trumping situations here that it is not worth getting into. The reality is that each API is going to be drastically different, and that certain APIs are going to lend themselves to utilizing this mantra more than others. At the end of the day, though, as you’re designing your API, you need to ask yourself, how often will the user need to customize this? If its every application, then its not a candidate. If the majority of applications can use a suitable default and be fine, then there is no good reason to require the user to explicitly choose that option. The default smart choice is there to make his life easier so that he can go about getting his work done.

Conclusion

That concludes the series “Make the Smart Choice So That Your User Doesn’t Have To”. Don’t forget to read Part 1 which deals with Preferences and Part 2 that deals with User Interfaces.

Credit

I have to credit this wonderful insight to the chapter Avoid Preferences in 37 Signal’s awesome book Getting Real. The whole book is worth (several) readings, and I can’t recommend it enough.

Preferences

Some developers pride themselves on all the customization options they offer their players. They let them adjust everything from graphical quality to which key combination fires a particular action. Who is better qualified to make these decisions? You or the player? Generally speaking, you have the skills and ability to make better decisions about player preferences than they can make themselves, so instead of delegating the choice to the player, make the right decision so that they don’t have to. I’m not against exposing the ability to let the player override this default choice, but your goal as a developer is to create the game your players want to play, not the game they need to customize to enjoy.

Case 1: Controls

Look inversion in First Person Shooters is a topic as divisive as some of today’s hottest political issues. Up until very recently, a game would make a decision, either inverted or not inverted, and (hopefully), players would be forced to dig through a bunch of settings to if their personal preference did not match that of the developer.

Recently though, several FPSes, like Bungie’s Halo for example, have started using gameplay to determine your inversion preferences. During the first few seconds of play, the game asks you to look at an object in the world. Based on how you interact with the controls to achieve this objective, the game makes assumptions about your control preferences. It even gives you the opportunity to correct it if it guesses wrong. Is that better than forcing your player to spend the important first few seconds of your game digging through menus to find a look inversion setting? Immersion wins when your players aren’t reminded that they are simply playing a game.

Case 2: Playback Quality

I am as guilty of this than any other veteran Flash developer out there. In a graphically intensive Flash game it is very tempting to give the player the opportunity to play the game in low quality rendering mode in order to squeeze maximum performance out of the Flash Player. If you think about it, that is completely unforgivable. Using a timer and some basic computations, we can make some quick estimates about the hardware capabilities of player’s machine and make the right decision far more accurately than the player. How are they supposed to know if they want 3 levels of parallax instead of just 1? The reality is we’re hard pressed for time so we opt for the easy choice rather than the right choice. In a future article I will tackle a utility class that will handle this computation on our behalf so that we don’t have any excuse to do this again.

Preference Trumps

Sound Muting

Every good rule has its exceptions. An important trump to the preferences aspect of this rule, in regards to Flash games, relates specifically to sound. There are certain standards that have been established in Flash game design, and typically these are around for good reason. When it comes to muting sound and music in Flash games, we have to understand the context, which why this rule is more of a “Best Practice” than it is a real trumping exception. Flash games weren’t popularized by people who traditionally play PC and console games. Flash games were popularized by people who were supposed to be working or otherwise being productive on their computer. People want to play your Flash game without being fired. If they can’t turn off the music and sound in your game with the click of a button at any instant, chances are they’re not going to be able to enjoy your game that much, if they even play it at all.

As I discovered in a recent game release, it is not sufficient to bury this capability in an options menu. On any screen where there is music or sound playing, you must give the player the ability to quickly and effortlessly turn off any and all sounds with a single action.

Follow Ups

Next up we will be discussing how this rule applies to user interface design, and then we will wrap it up with how this rule can make your API easier to use.