At the Develop Conference in 2011, Sean Murray of Hello Games was the keynote speaker for the Indie Dev Day. One key point he made was that we hear a lot about the successful indie developers, but barely ever hear from those who failed in the pursuit of their dream. This is my story.

In April 2011, I left Lionhead Studios after 3½ years working on the Fable franchise. I’d been a programmer in the games industry for nearly 11 years at this point and felt a burning desire to build a game on my own, rather than being part of a large team. A few of my friends had made the switch from AAA to indie with some success so I felt with my experience I had a decent chance. With not much money in reserve, I formed Razorblade Games and began work on a (still untitled) game.

My fellow indie friends advised me I should start small, perhaps making a puzzle game for iOS/Android using Unity and building the company from there. Arrogant as I was, I completely ignored this advice and set about building a game of my own on PC, on the basis that I already owned a PC and a copy of Visual Studio, so there would be no initial outlay of money to get started. I believed at the time that I would have a shippable game by around September that year.

When I say I started building a game, this isn’t strictly true – what I actually built was a graphics engine. The game design gradually formed as I was working over the first couple of months. I knew that my art skills were greatly lacking, so I had a vision of a stark first person sci-fi setting, with simple geometry, small rooms and no human characters – the game mechanic based on switching between alternate universes and changing the direction of gravity in order to solve puzzles. If this sounds a little like Portal, you’re right – that game was a huge inspiration for the project.

Things went well. I was writing a lot of code, new engine features were being added daily and I was learning to use Blender to build the game levels. I was highly motivated, happy to be free from employment and getting a lot of satisfaction from the work I was doing. I was writing AltDevBlogADay articles about how awesome it all was. In July I went to the Develop conference in Brighton,  taking a build of my fledgling game to show to people – a small, single level showing the core alternative universe switching and gravity manipulation mechanics. I talked with people about my vision of what the game would (eventually) become, I talked about how I’d built the game engine from scratch – the physically based lighting, HDR, motion blur, FXAA, etc. People seemed impressed. I was on a high.

However, there was huge elephant in the room – money. I was living off savings and my wife’s income, but with a mortgage and two children, this was running out fast. I needed external funding to keep going. Looking back I’m not completely sure why I didn’t try talking to a publisher or venture capitalist – I guess I was paralysed by a fear of rejection. Instead I thought crowdfunding was the answer. Kickstarter was becoming popular, though unfortunately was not available for UK based projects at the time, so I used the now closed 8bitfunding.com. This site had the “advantage” that you got your pledge money straight away, rather than having to hit a funding target first. I was initially amazed by the interest people showed and money was starting to come in. I wrote emails to every gaming website I could think of, with a link to a short (silent) YouTube video of the game, trying to get some press to promote the campaign. Only one gaming blog wrote an article about my game, and one other wrote back saying they’d be interested if there was more content. They were right – it was a pretty amateur attempt at announcing a game.

The income quickly stopped, most of which had come from friends, Facebook and Twitter associates. I had created the crowdfunding campaign asking for $10,000. In total I made enough to pay the mortgage on our house for just two weeks – clearly not nearly enough to sustain development. I did a some paid work for Digital Foundry, as a writer and consultant on a few technical gamedev articles, but again this was small change in the grand scheme of things.

Eventually, something had to give, so I started looking for a paid job. At the end of October, the lovely people at Relentless Software offered me a four month contract working on Kinect Nat Geo TV. I fully expected to save a bunch of money and start again with Razorblade Games after this time, but I ended up staying at Relentless for a full (and fun) year and ended with very little cash in reserve (commuting to Brighton on a daily basis was more expensive than I had estimated!). I continued to work on my own game on a laptop on the train journeys to and from work, redesigning the game to focus on the gravity manipulation as the prototype showed that the alternative universe switching just wasn’t that good as a game mechanic.

However, I didn’t do anywhere near as much work as I had done in six months working alone at home. I found it hard to mentally switch from working on one codebase during the working day and my own outside of this time, so ended up focussing my efforts on the paid work at Relentless.

Today, I’m working for Pitbull Studio in Guildford, working with Epic Games on Unreal Engine 4. This is satisfying and fun work, but there’s still the niggling desire in the back of my head to get back to writing my own game(s). I just don’t know when (if ever) this will happen – I haven’t done any significant work on it for a long time.

To the people who sent me money in my crowdfunding campaign, I’m eternally grateful for your (perhaps misguided) belief in me and the game I was building – I still owe you all a game!

To summarise, these are the major lessons I learned…

1. I vastly underestimated the money needed to pay for the project. You need a good source of funding, or a lot of savings to make the indie adventure work. Relying on a crowdfunding campaign is a huge gamble that’s unlikely to pay off unless you can get a lot of press and/or are already well known.
2. I was way too ambitious with the game I was trying to build. I was trying to build something the size and complexity of Portal all on my own, when I really should have listened to people and built something small and simple.
3. Building my own engine, whilst fun and a great learning experience, was an expensive mistake. For six months’ work all I had to show for it was a short proof of concept demo. I should have used UDK, Unity or one of the other available game engines and got on with building a game, but my pride as an experienced game engine programmer didn’t let me!
4. I was sorely missing an artist or level designer – I struggled with Blender and it took me an awfully long time to build the demo level I had. Also, having someone work with me would have been a great way to get feedback on what I was doing.
5. I vastly underestimated the time it would take to build the game. My prediction of shipping my first game in September 2011 was, in hindsight, laughable. I actively avoided any detailed scheduling and management of the project, preferring to just get my head down and write code – this was a mistake, particularly given the slim funds I had at my disposal. In fact, I had no real business plan at all – Make game, ???, PROFIT was about as detailed as it got.

Whilst an expensive “failure”, I still count the six months I spent on Razorblade Games as one of the happiest and satisfying times of my life. I learned a huge amount in this time and would (will?) definitely do it again!

Imagine a situation where you have just been employed by a game development company with a large code base. You might setup your computer, adjust your chair, get some coffee and then start synchronizing your source code repositories. This might take a long while so you decide to take a look at the company documentation while your downloading. So you roll up your sleeves and start digging. You dig and you dig, but you just can’t seem to find anything useful. Puzzled you go to ask either the CTO or the technical director whether they would have some information as to were the documentation is lurking. So you enter the room of either person and candidly ask your question, only to be met with a blunt answer stating that there is none.

You return to your desk, shoulders slumped, and sip some of that now cold coffee. You decide to wait for the source code update to finish. It now seems that you have to rely on code commenting to figure out how the system works.

Finally the update finishes and you start digging the source code. To your amazement and horror you notice that not only is there no separate documentation on the system but there’s also no documentation to be found in the code either!

Let us push that nightmare aside for a while and discuss what is going on in here. The situation is common not only in game development but in other kind of software development as well. It comes down to company culture in many cases. The companies I have worked for expect you to develop quality features sometimes in a tight schedule. Leaders are often focused on implementing features themselves and don’t necessarily oversee things such as code quality. Those are implicitly expected of all skilled developers.

In addition to code quality we have the issue of documentation. A lot of my colleagues of past and present might shift uneasily at their desks now. Let’s face it, most developers do not like writing documentation. Even Scrum has built into it the idea of only producing the minimal amount of documentation possible. While this does mean minimal in that it should still serve its purpose, it’s easily taken as a reason not to write documentation at all. You have code changing all the time anyway, so why should you write documentation that will be outdated the next day?

Why should we document?

The story I told is not uncommon by any means. It’s been a relatively constant topic of discussion for the whole of my working life, in fact. Why I think it’s so important is that you have people coming in and going out over the lifespan of a company. You could say it’s the people that make up the company but it’s code that is left behind by those people that forges the future of the company. This is because you can’t do a rewrite of the whole product every time you have people leaving or joining the company. So the company is stuck with what the person did before leaving.

Every time you write a single line of code you do it with a plan inside your head. You have an idea of what constructs are required and how they relate to one another. You basically form a whole imaginary world inside your head. This world is then projected into text using the programming language grammar.

Such descriptions using a programming language often becomes quite complicated. This is why you should use methods and well named variables to break down the individual expressions and constructs into understandable bits. For instance, you could write the whole simulation code of a car as a single block but it would make more sense to split it into smaller methods, each of which define a single step in the algorithm.

Such well structured code that is split into sensible bite sized portions that are labeled in a coherent manner can be called clean code. I like to think of you having to understand the main points of what the code does on the first read through.

However, clean code is not always enough. If you were making modifications to the code then clean code will help you considerably, but often you are just using the code in some way. This is especially evident when using a 3rd party library that has a specific set of entry points and data structures. You might not even have the code for it. You have no practical way of finding out what the system does without having samples on every single possible thing you can do with it or having comprehensive documentation.

The same goes for internal technology that is used in a 3rd party like manner. This is the case when using an internal engine, for instance. Documentation allows for people without deep knowledge of the engine internals to just dive in and start using it. Without documentation you could hope someone else already has an answer to your question or you could just start trying things out. I have also noticed that often the methods and classes really can be used in the way that feels intuitive, but you’re never really sure. This tends to create a lot of stress. Another thing that is made more difficult by missing documentation is feature design and work estimation. For every feature, you have to wade through the code trying to find the correct classes and methods to use.

As I explained above, you project your mental image of the system using the grammar of a programming language. The programming language is good at expression what is being done but what it’s not so good at is explaining why. Often you make choices that might not seem to make sense to the reader of the code. This might even result in the person “fixing” the code. Having the reasoning of that choice documented in some way can be very important.

We also often tend to forget about documentation having the ability to aggregate information and make it simpler to read. It’s often not just about whether the code is documented but also about how fast you can find the information you need. Say, for instance, you are in the situation I described above. You are a newcomer and you want to start doing something productive. The thing you could do is either go find some documentation, which is often scarce, or you could find someone who knows about how the system works. In the second option this person might then explain you the main architecture of the code and the guidelines for you to follow when developing or using the code, if that was what you asked. You feel satisfied and start working. Then a new guy comes in and does the same thing…

What I think is worth remembering here is that most people will ask the same questions, if that piece of information is missing. Being asked questions often means the required information is cumbersome to find or it does not exist at all. In this case you are using about X times the time you would have spent writing down the information you are being asked for, where X is the number of people asking.

Different types of documentation

You should not write documentation just for the sake of documentation. A piece of documentation has to always have a reader, otherwise it is useless. I like to categorize documentation into two groups: architecture and detailed. Note that we are talking about documentation targeted to the developer and not documentation like tool manuals and marketing material.

I would classify architecture documentation as the most important one because it describes the shape language for the code: the different sub-systems, coding conventions, threading rules, testing guidelines, patterns to use, non-functional requirements, etc. Overall, it works both as an introduction to the system as well as a guideline to using and modifying it. Architecture documentation is high level documentation used for controlling the overall direction of the project. It forms the boundaries, if you will, within which development is done. This is precisely why I think it’s the most important piece of documentation: How can you be sure people go in the right direction if there is no direction defined?

Whether you require detail documentation is a bit more complicated. This includes documentation about individual classes, methods and sometimes algorithms too. My view on this is that you should not overshoot but neither should you neglect it.

Whether or not you require detail documentation depends on the type of code you are writing. If you are modifying an algorithm and you can be expected to understand its inner workings and you are able to understand the algorithm by reading the code, then you do not necessarily need additional documentation. Algorithms are usually contained in some manner and have few entry points. Some times, as was mentioned above, however, you might have made a choice when implementing the algorithm that might not initially make sense to the reader. This is where detailed documentation is important, to explain the “why” of those choices.

Now, if you are accessing an entry point of an algorithm and you have to understand the algorithm to know how to use the entry point then either you don’t have clean code or you are missing documentation. To determine which is the case you should analyze whether it is possible to re-factor the entry point so that it is self explaining. It this proves too difficult, the entry point is missing documentation. There might also be some simple methods that get or set data whose names would become too complicated in which case documentation is also in order.

I have also personally heard comments about code documentation requiring too much discipline to work. It’s just something that comes in your way when you implementing something and you have no time for anything extra. What is often forgotten, however, is that code is most of often shared property and multiple people are going to work on the code you have written. Implementing a new system requires design and implementation. Working on an existing one means understanding how it works, then designing and implementing the modification. Let me put that into two equations:

X + Y = time

X + Y + Z = time

The second equation is the one for modifying an existing feature and is very much impacted by the component Z that describes the time you have to use to learn the system. The more technical debt you leave behind the bigger Z will be for the next person coming to work on your code.

If we now break down Z into components Z1 and Z2. Z1 stands for the time used to learn what the actual code you are modifying does while Z2 describes the time you need to study related APIs. Clean code is the best way to minimize Z1 but Z2 might come from re-usable APIs like core engine code that you are incorporating into the existing code. To minimize Z2 you have to minimize the time it takes to learn what those APIs do.

The documentation process

Documentation is best written in small pieces. The difficulty in writing good documentation comes from the fact that you as the implementer are most likely not going to spot where there is information missing. This is where we come to the concept of code review.

Code reviews are the best method for finding places where documentations is required as the person reviewing the code should be able to understand what he/she is reading. If that is not the case, additional documentation or code cleanup is required. Personally I think both peer review and reviews done by the lead programmer are in order. In peer review you also share knowledge minimizing silent information, where some people know something others have no clue of.

There are multiple tools for technically performing code review. I have experience using a product called Review Board, which I can generally recommend. Regardless of the tools you use, code review should be built into the company culture. Choosing the tools is easy, getting the process running is the hard part.

Another thing that is a clear indicator of missing information is different people asking you the same questions time and time again. Documenting your answers will both save you the time of answering the same questions multiple times but also makes it possible for people to get to that information even when you are out of reach.

How should documentation be done, then? Personally I like wikis and code commenting. Wikis are good for documenting software architecture but code commenting is good for detailed information like API documentation. Also, you should exhibit some discipline. Documentation should be built into your way of working. Every feature should be reviewed and missing information should be incorporated either by cleaning the code, commenting the code or writing about it in the architecture documentation. The order is important. You should first consider cleaning and only do commenting if it proves too cumbersome and defeats the purpose. If the information is missing on a larger scale (which systems take part in managing the game world, for instance) then the architecture documentation should be updated.

Conclusions

Documentation requires discipline, but so does programming itself. It is indicated by the very process of using a well structured programming language to describe a system that is to work in a deterministic fashion to perform a certain set of tasks. Documentation should not be thought of as a necessary evil that is to be defeated by forcing everyone to write silly amounts of it. It should contain information that is difficult to describe otherwise, information that people need in order to be effective at what they do.

In my view, there is no single right way to perform documentation. Some people say it should all be incorporated into the code, some say there should be no commenting at all and clean code is enough while others like to have the whole set. My tip is that you should do what works best for you as a company. The bottom line being that documentation is about improving the efficiency of everyone in the company, it should not be there just for your nuisance.

If you work with a big company, chances are you’ll have to deal with a ticket tracking system. They’ve become a critical part of IT helpdesk operations, of scrum and agile teams, of collaborating with remote teams, and pretty much everything. But tickets can lead to development paralysis, especially when they’re used to drive a Scrum/Agile team – so let’s talk about ways to deal with ticket overload.

A good ticket system can be an asset for managers and developers alike. Managers like ticket systems because they provide great reporting and supervision tools for a big development project. Developers like checklists, they like having lots of ideas floating around, and many of us really prefer receiving tickets via email rather than phonecalls from users requesting development work.

But sooner or later, most developers wind up feeling like Kirk here, drowning in tickets and ticket management work. Why is that?

Ticket systems introduce a number of competing pressures on your development staff. Your users learn rapidly that they need to submit tickets if their ideas or needs are to be heard. The more tickets you submit, the more influence you can have on the development process.

Your managers learn to build reports on ticket backlogs, estimate accuracy, close rates, and so on. By filtering tickets and handing out task lists, they gain an easy way to supervise the programming team. And developers often get the short end of the stick: a backlog of thousands of tasks, constant progress reports, and little freedom to pick and choose their work.

Naturally, a program designed “by ticket” can wind up a Frankenstein creature. And the biggest kicker is that all of this stuff happens naturally, without any effort on your part. Tickets make managing developers seem so easy – so let’s look at the problems that can crop up in your ticket backlog.

• Anyone can write a ticket. This is a blessing and a curse. Every single person in your organization has valid, useful ideas and they deserve to be heard; but it’s easy for someone to write a ticket with no detail, or a ticket request that contradicts your system’s design principles. It’s also easy to get IT tickets or operational tickets that aren’t about software development at all!
• Tickets often include suggested resolutions, which may not be the right ones. A common mistake when writing tickets is to detail what feature a user wants, not what problem you want to solve. An end user might write, “I need a button here to send the report via email,” but what’s really needed may be an approval workflow or a daily notification list.
• Clever users can scheme the system. Many years ago, one user I knew took advantage of a policy that increased priority for bugs. He rewrote all his feature requests as “Bug – Steps to reproduce: Go to form X. Expected result: There should be a button to do Y. Actual result: No button exists.” In general, if your users are crying out like this for more features, maybe it’s a sign for the business to invest more in software development!
• A large backlog discourages proper maintenance. When your users have a thousand requests in the queue, your manager is going to demand justification when you want to do something not in that list. It’s not always obvious to management why there are 500 tickets that can’t move forward, when the programmers really want to redevelop a badly malfunctioning queuing system.
• Tickets aren’t prioritized in development order. Your managers don’t understand the architecture of the code. They look at the business value of the ticket, the title of the person who wrote the ticket, and maybe the expected development hours. Instead, as a developer, you should focus on finding a bundle of related tickets in the system that you can execute all at once.
• Ticket metrics are easy to generate. Because tickets are generally managed in a central database, any manager can write a few reports and put together a presentation on the development team’s progress. And since these metrics are so easy to see, when you make a mistake categorizing a ticket, you’ll be explaining to a manager why your metrics look wrong.
• Metrics can, and will, be gamed. If management indicates that a particular statistic matters, the team can find ways to optimize that one statistic. Without a broad view of the business, a mischievous team member can show progress in one metric when the project is actually falling behind.
• Ticket estimates often don’t include time to research the problem. Your senior people usually get the toughest tickets, or the ones that don’t make sense. Often it will take them lots of time to just set up a test, or interview all the people involved, in order to figure out what the real problem is, and that time doesn’t show up well on ticket management metrics.
• Architecture improvements are hard to compare against user requests. This one is just fundamental. When a user of your system says “It’ll save me ten minutes a day if you rewrite this dialog box,” your manager knows exactly how much that task will benefit the company. Can you guess how much time you’d save by writing a scripting language for tests? Probably not.

So is it hopeless? Not really. Most of the problems with tickets can be addressed if you approach them with a healthy skepticism. The fact is this: a ticket can be changed. If you can keep your ticket process fluid, if you can maintain some freedom you can find ways to use tickets for good.

Ticket Taming Techniques

Start off by having – or selecting – a visionary who has the role of an architect or team lead. This person has the job of saying “no” to some requests and helping to develop others into useful tasks. There was a great dilbert cartoon that is unfortunately lost to the mists of the pre-Internet age, where Dilbert illustrated that the difference between a company with a strategy and a company without one was the ability to say no. Learn to say no to some ideas.

The architect should look at each ticket as it arrives, weigh its value and difficulty, and help get rid of tickets that aren’t likely to have a positive effect overall. If the architect knows that component X is going to be redesigned soon, the architect should put on hold all tickets related to that component until the rewrite is complete. If the architect sees a bunch of overlapping tickets, he or she needs the authority to consolidate them into a more focused feature.

Keep in mind that architects burn out if you keep them on the same project too long. If you don’t change architects regularly, you should! New eyeballs and a fresh perspective can often inject enthusiasm into a moribund project. If you haven’t tried it already, consider rotating your team leads yearly, and give each one an opportunity to eliminate the worst mistakes of their predecessor, as well as to add their own flair to a project.

Problem: The Ticket Treadmill

When your ticket backlog gets too great, your developers find themselves constantly rushed and stressed. They rush tickets out the door and the result is even more tickets. Yikes! How can you break the cycle?

The answer is to slow down the team. Instead of solving a task as fast as possible, reinterpret the ticket: what is the underlying problem that caused this ticket to go to you? Is there a better way to do this? Make sure your developers understand the problem thoroughly, then:

• Schedule 15 minutes of time to update tickets at the end of the day. A developer who is constantly bouncing back and forth between their code and their ticket tracking system is probably too distracted to deliver really awesome software. Tell your team to focus on the work. Ticket maintenance should always be a valuable secondary activity. Let them know it is okay to put it off until the end of the day, but don’t let them skip doing it.
• Resist the pressure to provide low time estimates. This is tough, since we all have a competitive instinct and we all like to show off how fast we can get things done. But our goal is to make the system better! Constantly rushing to try to match tight estimates can make even great developers churn out bad code. Be cautious and give yourself lots of leeway; that extra time makes it possible to…
• Fix more than just the problem. If you get a lot of tickets for “adding an email link to this page,” develop a bigger solution that adds email links to all pages. If you get tickets that say “Remember the size of this window when I reopen it,” write a tool that remembers the size of all windows. If someone sends you lots of tickets to “Fix problem Y for file X,” develop a tool to identify and fix the problem, document it, and deliver it to the end users. Eliminate all tickets of that type, not just that one ticket.
• Discuss tickets with your users in person. Or over screencasts. Take the time to talk to them when it’s not clear how to best solve a problem. You’ll be surprised how often something becomes obvious when you see the problem firsthand. And, if you need more experience, try walking a mile in your user’s shoes – ask them if you can try working their tasks for a few hours. Suddenly you may realize why they keep sending you problematic tickets.

Problem: Time Crisis

Sometimes you find that there isn’t enough time in the day to actually accomplish your work. This is common, but often represents a problem outside of your ticket system. Your ticket system has really good statistics, but there are no statistics for “time spent in meeting rooms.”

So how can you get your developers back to productive work?

• Create “activity” tickets for time consuming activities. Do your developers have to spend 30 minutes per day preparing reports? Monitoring servers? Talking to customers? Every week or so, give your developers a ticket with a time estimate that indicates how much time you want them to spend on these activities. Tell the developer to bill time to this ticket rather than pretending that the time just vanished. Your managers need to know that this stuff is happening, since it affects everyone’s productivity.
• Use the backlog to bring on board new developers. A junior developer can often surprise you by developing inventive solutions to age-old bugs other developers won’t touch.

Problem: Too Much Tracking

It’s easy to get overwhelmed with detail. When you have a ticket tracking system that works, managers can ask for lots of reports. They can ask for statistics to update daily. They can ask that each ticket be categorized in a dozen different ways.

A healthy ticket system doesn’t overwhelm team members with busywork, it should help the team by providing a framework to track and demonstrate their progress.

• Ask your management which metrics matter. Don’t be shy! They want you to succeed just like you want to be seen succeeding. If they really care about meeting deadlines, focus on those statistics that will give them predictable deadlines. If they want to see the backlog decrease, focus on fixing lots of little tickets and de-duplicating tickets that refer to similar tasks. But bring them around to…
• Encourage the broad view. If the team focuses too much on “tickets completed per sprint,” remind them that the application’s latency is improving, or the UI is getting better. Emphasize the reduced maintenance work spent by the IT team. Show everyone that ticket statistics are only one part of the whole.

After all, the real goal of a ticket system is to help make the great work you do visible to everyone. Don’t let your ticket system become counterproductive; be aware of its limitations and you can help drive it in a positive direction.

As mentioned previously, I’ve started fleshing out the backend for the server that I’m looking to build for my ongoing experiments.

Let’s recap the key points:

The first 2 elements to our server design can be broken nicely into:

• Static Content (Metadata)
• Dynamic Content (Player data)

Metadata

You can consider metadata to be anything static in your game that doesn’t change from player to player. This could be an inventory of all the weapons in your game, or a list of all the level names, all the dialog text in the game, and so on. I would highly recommend that you store all of this static information server-side so that it is easy modified and updated after launch. Yes all of it. I’m not kidding in the slightest. Every weapon, every item in your massive RPG, every character’s details, the story of your game. Store all of it on the server and query it dynamically (well, mostly dynamically, we’ll go through how we can cache this and allow offline play etc later). Yes I did say ‘offline play’ – almost nothing about what I’m proposing here would necessarily prevent offline play, but that’s up to you to decide for your particular title.

Player Data

The dynamic content in your game is the player-specific user data that gets stored as they start the game and progress through the adventure. This could include their progression through the tech tree in your game, their inventory, unlocked levels, etc. It could also include a more complex save game system that stores microstates of each object in a scene if you like. All of this information gets pushed to the server and pulled down dynamically when the player first launches the game / effectively ‘syncing’ their game state. Every MMO that you have played does this kind of thing, and probably a number of other games that you have played in the past 3-5 years as well. Unfortunately not nearly enough do this kind of cloud-saving (in my opinion).

So now that we know what we are trying to do, let’s discuss a bit about how we might achieve this.

As a caveat, I’ll definitely say that my approach is likely going to be far from typical, however the underlying principles are based on many years of experience working with similar systems, both from the web-development standpoint as well as from the game development side of things.  My career has floated almost equally on both sides of the fence.  Years ago this seemed a bit strange to me, but they have effectively merged with this new approach, and I find the end-result so much easier to maintain.

My primary goal in this experiment is to reuse existing code and libraries where possible to maximize how much I can get done with the minimal amount of code.  As a single-person (at the moment anyways) indie developer, there are far greater challenges and tasks on my plate than writing a full-fledged content management system to handle both the static and dynamic aspects of my project, and realistically, there is probably someone who has already written the majority of what I’m hoping to achieve already.

Before I dive into the particulars of the separate systems, lets take a look at a higher level set of functionality that I’m looking for with my Static AND Dynamic systems to see if there is a few common threads that might help me narrow down an approach.

1. Runs on the standard LAMP stack (LAMP being Linux / Apache / MySQL / PHP, although the apache element might get swapped out with a more efficient web server before I’m done).  This makes hosting & scaling the system a ‘known quantity’ that doesn’t require esoteric / specialized knowledge to achieve.
2. Reuse / provide as much functionality out of the box without requiring a massive code rewrite or repurpose.
3. Provides me with a web-based interface for editing the game data (either static metadata or player game data).  For this reason alone, writing a custom PHP / MySQL app is less appealing.  Building a nice easy to use interface for a database app can often take longer than the core functionality itself, so I’m hoping for an existing solution that will solve this problem.
4. Be easily scaleable – either as an existing ‘appliance’ that I can plug into amazon or rightscale or something similarly easy to deploy into a cloud-based system.  I don’t believe that cloud systems are the end-all-be-all for scaling an app, but they do provide a starting point for a solution, and having something that I can quickly deploy if need be is crucial.  Last thing you want is for an app to become popular and not have a plan for scaling the app ;}
5. Provide a JSON interface (or easy access to data so that I can build my custom JSON API for the server communication layer).  I’ve been working with JSON based server API’s for the past year and have really enjoyed how easy they are to work with.  This plus the fact that PHP has very powerful built-in support for JSON serialization and parsing gives me a head-start building the server communication layer.  I’ll go into this probably next time as we get closer to the client / front end design.

That pretty much covers my high-level requirements for the system.  Let’s dive into some details.

Static Content Management (Metadata) 

For any game, there is a large amount of static content, what I’m dubbing Metadata, required for the game.  Think of this as the look up values for everything from the number of levels in the game, how many enemies a particular wave should contain, details about how strong a particular enemy should be, all the way down to how many XP a particular game event should grant the player.

For a traditional single player game, this data was either hard-coded in the game code (or hopefully a text config file at a minimum).  With tools like Unity, the metadata can be thought of as the public interface for your class that Unity exposes in the editor at design time.  This isn’t necessarily a hard & fast rule, but it’s a good rough starting point for us to begin working from.

To provide a more specific example, let’s break down one potential class in our theoretical game and figure out what kind of metadata you might want to poll the server for.

Lets assume that our game has a variety of enemies that the player must fight.  These enemies probably have Health, Movement speed, Damage (and/or Damage per Second), firing range, and other similar properties.  These variables are a perfect candidate for grabbing from the server.  If we have them hard-coded in the client, then after our game launches, we will never be able to update or modify these values without pushing out a new client update / patch.  If our game isn’t perfectly balanced at launch (and let’s be honest, very few are), we will be stuck with these values until we can get an update / patch for our game out the door.  However, if we are polling this metadata from the server at runtime, updating & modifying these values are all of a server-side tweak away.  This is exactly the type of thing that every game should be looking into using.

This same method can be applied to just about every aspect of our game.  What missions are available in our game, what enemies (and how many) get spawned for each level, etc can and should be retrieved from the server at runtime to allow for the maximum flexibility in our codebase.

Most programmers have heard of ‘data-driven design’.  The traditional description of this is to separate the data that drives an application from the code / logic that makes things come to life.  What this mean in many apps is having a local database

What I am expressing here is a relatively straightforward extension of this methodology.

Now that everyone understands this (hopefully) approach to the overall design to the client & server, next up we’ll start to design the json server api that we will be using to pass information back and forth and start building up our client/server communication stack.  The fun begins ;}

Until next time…

In visiting with various companies over the past few months I’ve been struck by the common occurrence of certain leadership flaws. I won’t whitewash them…these aren’t “tendencies” or “styles” or any easy-to-swallow aphorism. They threaten the stability of your studio, the happiness of your team, and they’re so common that I wanted to bring them to light here, describe the damage they’ll do if allowed to run loose, and talk about what to do about them. Odds are they’ve already risen up out of a sea near you, so let’s talk about awareness and solutions before they make landfall and threaten to eat your Asian metropolis.

Territories

The catchphrase here – be it spoken or implied – is, “These are my people and I’ll manage them as I see fit!” I pretend no understanding of the psychology behind such a mindset (not enough hugs as a kid? I don’t know) but the actions of this type of manager are bent on control at all costs. If the studio leadership want to try a new task tracking tool or a new development methodology, too bad. This person won’t allow it on their team.

The downsides to this behavior are fairly clear. The authority of senior leadership is undermined. Peers of the Territorialist are left wondering why they should have to play by the rules when he doesn’t have to. The needs of a single ego are taking precedence over the needs of the company and the team. Often the team members themselves can be caught in the middle, suffering unfairly in an authority battle between “Mom vs. Dad”. When I was a studio developer that happened to me during one spectacularly awful period of senior mismanagement. I can tell you it seriously degrades morale and performance.

I’ve stated elsewhere my opinion that no single person is of such irreplaceable value to your studio that they deserve special treatment. Just as you would with a frontline contributor intent on bucking authority, have the immediate supervisor of this recalcitrant manager step in. Describe the issues, explain that communication is encouraged in light of a clear difference of opinion, but that the decisions of senior leadership aren’t optional. Provide opportunities for mentoring. After all of that, though, hold this person accountable and be prepared to take action if they don’t show improvement. Open disruption in the leadership of your team isn’t something to be taken lightly.

Double Agent

This type of manager shows preferential treatment to team members. He listens to the input of specific peers but not others. To a certain extent this is expected and understandable. Not every idea that’s brought forth will be a good one, and sometimes less-experienced voices won’t carry the weight of those more tenured. But in this particular case we’re talking about a manager who discounts someone’s feedback simply because of who they are, without giving their thoughts due examination. In a highly creative and innovative environment you just can’t afford to have any team member’s communication wantonly tossed out, else why did you even hire them?

What negative effect does this behavior have on your team? Favoritism breeds disengagement. Why should I even try to put thought into my work when I know my input won’t be appreciated? I’ll just do exactly as I’m told. That attitude produces lackluster results, erodes morale, and creates Us vs. Them factions in the workplace. Additionally, the odds are that some good ideas are going to be missed, and most of us have seen the enormous benefits that have been garnered by the addition of that one great piece of input at the right time.

Another point worth mentioning is that absence of trust may be playing more of a role than outright favoritism. Maybe this manager isn’t going to listen to the new coworker because there’s no level of trust between them. To this I would say that propagation of trust as a global aspect of running your studio is the responsibility of everyone in leadership from the top down. If you find someone in your company – such as the flawed manager under discussion – who as a matter of course exhibits lack of trust in one or more team members, you need to do two things: stress with the manager that in this company we trust our coworkers, and make darned sure your hiring process is only allowing the introduction of employees who are trustworthy. If you’ve got someone in house who truly can’t be trusted, either get them some mentoring or help them find a better fit at another company. You can’t afford to not trust each other.

Lock and Key

Be it caused by insecurity or narcissism, there are those who refuse to relinquish the slightest bit of power once it’s acquired. I saw a fair amount of this during my time at Raven Software, particularly as we came to realize the importance of project management in the form of producers. Largely – I believe – as a result of power mongering, the producer was instantiated as lower than the apex of the team pyramid and not even truly on par with department leads on the next level down.

One of the worst results of a situation like this is when someone afraid of subdividing his fiefdom doles out responsibility without power. Half-baked attempts at delegation such as this leave others in a position of being accountable for the performance of team members but without the means to solve problems or empower those team members. In my case as a producer, I was initially “responsible” for the scheduling and communication between art and level design but I had no power to enforce timeliness of deliverables or to modify processes to improve speed or quality. This situation led to many arguments and much passive aggressive behavior that could have been avoided. As a bit of a mea culpa, it didn’t help that I was young and brash, without a mentor, and given no project management training, but those are certainly topics for another time.

How to fix it? Make sure all leaders understand the requirements of their position and get consistent, frequent feedback on their performance. They need to know what’s expected of them and they need to hear how they’re doing to avoid giving rise to insecurity about “losing their power”. Their immediate supervisor needs to be purposefully involved in mentoring and developing. Avoid the trap of thinking leaders don’t need support in their professional growth and behavior. Just because someone’s been put in a position of power doesn’t make them perfect at what they do.

As an additional point on the topic, when assigning new responsibilities or creating new roles on a team, be very open in communicating with the affected parties – both the leadership and frontline contributors. Be clear in stating who’s responsible for what, and ensure that each responsibility brings with it the empowerment to effect change. Don’t make someone accountable for something over which they have no control.

Although there are definitely other common leadership flaws worth mentioning (without trying too hard I came up with an even dozen), these three stand out because I’ve recently seen them at multiple companies. If I’m seeing them this often you probably are, too. Now you’ve got an idea of what to look for and what can be done to address these problems, so make sure you’re taking action to improve the leadership at your studio.

previous article was a deep dive into my own personal experience of burnout and depression and what it took me to regain my own health, vitality, and enthusiasm for the work that we all do. In this final article, I take a look at conditions of the work environment, share some practical things that I do to conserve willpower throughout the day, talk a bit about how I get quality sleep, and tie up some loose ends with the series.

Environment

When it comes to being creative and productive, I think that setting the conditions to succeed are important:

A solid work day

I’ve worked at numerous studios that did not respect my time. My commitment to anyone who works at our studio – put in a solid eight hour day and I won’t ask any more from you. Our policy: I will come in anytime between 8-9am and leave between 5-6pm. If I am running late, then I will email the team as part of being accountable to myself and my other team members. By sending an email as soon as I know I will be late, it allows me to reflect on why I can’t get in to work on time. The email is not meant to shame me in any way. I simply make up the time either that day or the next. What doesn’t work with this policy – long lunches, inefficient meetings, catching up on personal email, stepping away for personal calls, and/or hour-long Halo breaks. While the policy is clear, life is not always simple and it is understood that sometimes it is necessary to take care of things in order to focus on work.

Leave the laptop (and work) at work

We all have laptops for the off-chance that one of us needs the flexibility to work at home and in the event that we are all at a conference that requires us to be mobile. I found that when I first started working in our new office I was lugging the laptop back and forth between home and work. When I was a freelance contractor prior to starting the company, I didn’t have clear boundaries for work. So, naturally, I continued that behavior for part of the first year after we moved into our office (even though I did not expect this of employees). I have since changed this behavior to be balanced: I focus on getting my work done at work and leave it there.

Sit in a good chair

When I was working out of the home office, I went through a few cheap chairs that all seemed to cause back problems. When I hired the first employee, I knew that it was time to respect both my own well-being and that of others who would be sitting for most of the day. I researched chairs for more than two weeks, visited many different high-end stores, and sat in many different chairs (including ones that were way out of our price range at the time). Unfortunately, I can’t recommend to you “The Best Chair”. We currently have a bunch of Steelcase Amias, but I think the Leap would have been a better choice. My suggestion is to try out different ones or have your team try out ones until you find one that works for everyone. If you’re just staffing up and don’t know what people will want, then it’s good to find one that has adjustable lumbar support, a sliding seat pan to accommodate different leg lengths, and adjustable height at the very least. Having a good chair is one of the best investments you’ll make.

Other ergonomic / hardware requests
At some of the prior companies I’ve worked, hardware or other ergonomic requests were not easy to come by. What’s odd to me as a business owner is why there is any hesitation. While it might seem like a lot to spend $1000 more for better computer hardware or $300 on a keyboard or $100 on computer vision glasses or $80 on a special type of mouse, these are all fixed costs. On the balance sheet, these costs will be miniscule compared to the recurring costs of payroll or office space. I do realize that across a large studio these costs can add up. However, I think it speaks a lot to the people who work with you to see that you care about their well-being in the office.

Amazon Prime / Costco / Safeway / etc.

This might seem like an odd one to put in this list, but it goes in part with the previous condition immediately above. I was a latecomer to Amazon Prime for personal purchases. Then, upon suggestion from an employee, I decided to set up a company account. We would have, once a month, a collection of all the snacks/items people wanted to have in the office by having each employee login with the company account and add things to a wish list. Then, I’d confirm the purchase and submit the final order. Finally, we reached a point where it made no sense to wait to put together a big order and my co-founder and I decided to give a trial run to make it available for any employee to order/reorder anything that they wanted. So far this works well and doesn’t seem to get abused. This comes down primarily to trusting the people you work with. If you don’t, then why are they at the company?

No crunch periods

Just as I found out firsthand the lasting effects that crunch had on my personal health, I also think that it translates to the team as well. If you crunch at your studio, then know that whatever you get out of the team comes at a cost. My advice: don’t do it. For one, I think it creates an unhealthy environment of competing for the Workhorse Award. I think it’s better to reward working smarter rather than working longer. Secondly, it reinforces poor scheduling instead of sobering up to the reality of the actual time it takes to make a high-quality game. If anything, it has been my co-founder and I who have worked a few weekends here and there (we’re both software engineers by trade) from our miscalculations instead of passing that on to our employees. If we’re habitually missing our own deadlines, then it is a sign that we are not estimating as well as we could be or scoping the work properly.

Willpower

willpower. In an effort to conserve my own willpower, here are some of the things that I do:

Do the most important thing first; in the morning
This one is challenging to me because it’s easier to spend all of my energy trying to reduce my inbox to zero or catching up on industry news or watching recorded talks from the last industry conference that just passed. So, if that is how I spend my morning and I finally get around to that something important at 3pm in the afternoon, assuming no further distractions come, then what is left in the tank? Yeah, not much. So, I schedule one important thing to do daily, do it as early as I can, and avoid disruptions. I leave the afternoon stresses that naturally come to get what is left over. In short, I think I do my best work in the morning, so I choose where that goes.

Don’t check work email outside of work hours
I use to have push email to my phone, getting that ding every other minute. Then, I switched to pull to avoid the Pavlovian response. However, I’d still check my work email constantly even after going home for the day or on the weekend. And you know what? I’d get that distressed email from one of our clients about a project we were working on. I’d get all worked up about things that I knew I couldn’t deal with until Monday morning when we could all get on a conference call. Then, it dawned on me – leave the work email at work. I know that I’ll deal with whatever comes up when I’m at work because I work a solid day when I’m there. So, until then why not give myself a break? I consciously choose to not check my work email when I’m sitting on a bus, idle (my bicycle got stolen recently). I’ll deal with all of whatever is waiting in my inbox when I get to work. This rule is not a hard and fast rule though. Sometimes I get bored and can’t help it, but at least I’m conscious about it.

Shift meetings to the afternoon
So, if I do my best work in the morning, then why not schedule meetings in the afternoon? Otherwise, I’ll be in conflict between starting that something important and picking off smaller tasks in an effort to not get into a flow before I get interrupted for a morning meeting. Additionally, I try and push meetings either to directly after lunch or the end of the day. Otherwise, I’ll be in the same dilemma as before. However, this rule is not hard-and-fast as it is possible that the most important thing for the day is the meeting.

Better meetings; courtesy of Google
Google Ventures recently released a session online: Meetings that Don’t Suck. Some of the nuggets of wisdom I extracted were: to not have a meeting if we don’t have a decision to be made, have the decision to be made clear and specific, know who to have at the meeting, know who is the decision maker, schedule the meeting for the right amount of time, try leaving the laptop at the desk, and leave a day for everyone where no meetings are scheduled. In practice, this has been challenging to unlearn the ways we have been having meetings up until now, but we’re trying!

Sleep

This one is a no-brainer and yet I managed for many, many years to not get enough sleep, cover it with coffee, and continue to not get enough sleep. This one is important enough that it deserves a separate mention from the rest of the conditions to succeed.

Shift to an earlier schedule
When I started my journey towards better health, I was still working at home. As part of eating regular, energy-packed meals it was easy to stop and cook a meal at any point. However, I hadn’t reeled in my sleep schedule and was still working late. Once we moved into to an office and hired our first employee, I realized that getting to and from work would require me getting up earlier. So, I had to shift my hours forward.

Give time to rest my overstimulated brain
Shifting to an earlier sleep schedule was and is sometimes still challenging because it’s easy to stay entertained with Netflix, YouTube, email, and books until late hours into the night. I’ve done the introspective work to look at what shadow belief was driving this behavior and found it to be that “I am not doing enough for myself.” In other words, I owe it to myself to stay up late and watch back-to-back episodes of Mad Men or Breaking Bad until I am completely exhausted. No, what I actually owe to myself is to get a good night’s rest, so I don’t feel like shit the next day. Another poor sleep habit I kicked a while ago: leaving the TV running while falling asleep.

Dim lights as I get ready for sleep
Serotonin and melatonin are flip-sides of each other. Serotonin helps regulate moods during the day and melatonin can help you get a good night’s sleep. I learned that bright lights in the room or from an LCD screen could be reducing melatonin production right before bed. So, it’s easy enough for me to shut off a few lights as I wind down for the day.

Sleep on a good bed
I had an old box-spring mattress from five years ago that had a deep sag on the side where I had been sleeping. Needless to say it was uncomfortable. I finally invested in a good quality mattress after doing quite a bit of research on SLTD. I was tempted to buy one of the low-cost memory foam mattresses on Amazon and decided against it due to the off-gassing and potentially toxic materials that get used in those mattresses. In the end, I opted for a more firm, 100% natural Talalay latex bed. Find what works for you, but if you’re trying to be mindful of the environment, then beware of some of the “eco-friendly” versions of mattresses that simply put an “organic” layer on top of a stack of toxic polyurethane foam.

Sleep in a dark room

I’ve actually been sleeping this way for years and I find having light levels dark as possible allow me to sleep better through the night. Recently, I decided to cover some of the blinking / bright LED lights from electronic equipment in the room. I have white roller shades that I pull down behind blinds, but I still get light leakage and may opt for black-out shades in the future.

Leave my alarm clock (i.e. iPhone) across the room
I started leaving my alarm clock across the room instead of next to my head on the night stand for the main reason that it requires me to get up out of bed to turn off the alarm, which usually defeats the purpose of snoozing. I think because I know I’ll have to do this it reinforces getting to bed early enough where i won’t feel the need to snooze.

Challenge: wake up without an alarm
I’ve only managed to do this one for a short period of time because it requires an added level of discipline. However, it’s pretty cool when it works. I’ll set my alarm for the latest possible time that I can get up and then make sure to get to bed early enough where I get 8 hours of sleep. Usually this is in the range of 10-11pm. If I manage to get up before my alarm clock, then I get to start my morning calmly without “jump-starting” my body to an alert state.

Loose Ends

Tying up a few loose ends, I wouldn’t feel complete unless I mentioned a few more things to round out the series.

Water
I’ve mentioned this before, but I’ll emphasize it again. I drink plenty of water in the day (roughly 3 quarts) and mostly in the morning. If what comes out of my body is clear, then I know I’m good. If it’s yellow, then that’s indicative of a warning.

Sunlight
I’ve spent most of my time indoors as a software engineer and didn’t quite get why people are outside. It feels good dammit! It’s no surprise that my vitamin D levels are still low. So, I try and get out for at least a few minutes a day to get some sun. Requiring water and sunlight, we aren’t too much unlike plants.

Team Outings
We try to get out once a month as a team to do something outside of the office. We use part of a workday to do this, but if that is cost-prohibitive, then there’s no reason why it couldn’t be done on a weekend. At first we started with a movie outing. We tried a never-ending Diplomacy board game another time. Then, we did a Magic: The Gathering constructed deck tournament with a newly purchased box of boosters. Now, we’re moving on to more active outings as it is summertime: we recently hiked up Mt. Tam up in Mill Valley, CA.

Summary

The Healthy Programmer: Get Fit, Feel Better, and Keep Coding. In the book the author states that “one of the most important points you can take away from this book: your mind and body are not independent entities. They are intimately coupled, and for one to perform at its best, both must be healthy.” I certainly learned that lesson the hard way.

I hoped you’ve enjoyed a topic that is important to me and that I think hasn’t gotten much focus in our industry. I didn’t integrate all of the things that I’ve suggested immediately, but I did decide that I was willing to experience something different, so that life could be better.

There you are! You, yes you! Been tasked with a new feature or a change, to the code or a script, to be done by yesterday, haven’t you?

Yes, yes, I know your pain. You’ll be wading through oddly named files, containing briefly labeled identifiers for elements in an obscure relation, and maybe a sprinkle of outdated documentation or commenting to help losing your way. Maybe you’ll be trying to patch in your tasked change, secretly cursing your predecessors’ names for their sloppiness, perhaps the commissioner’s demand to implement something that was clearly not in the scope of the contract, all the time looking at the ever-growing list of bugs (they breed while you’re not looking, you’re sure of that).

Wait, before you light the candles around the pentacle, let me challenge you.

It should just work?

“Muttley, do something!”

– Dick Dastardly

Make minimal changes, briefly check it doesn’t crash, conjure an explanation for your changes for the buddy check, submit with a meaningful description, build machine is green, task done, next!

Sounds familiar? If it is, chances are, not knowing, you added entropy to the system. Made it more obscure, difficult to maintain and refactor. Created harder bugs. Killed performance bit by bit, not with one gunshot but thousands of needle pricks, one per check-in. If you’re really lucky, you created some race condition. You increased the project’s technical debt.

I know it’s true, I’ve done it myself time and time again, until I finally learned these words of wisdom:

Leave it better than you found it

“I never pick up an item without thinking of how I might improve it.”

– Thomas A. Edison

Whenever someone has to make a change, some of the time is lost to understand the context. Your changes are not final either, not even if you’re going gold, therefore my suggestion is: make changes so that the process goes faster for the following times.

In doing your task, you’ve opened a few files; scanned through a few functions; read some lines, followed the flow or execution; wrote new code, perchance creating new class variables or using global ones. Unless you know the code by heart and you were the only one working on it in the last weeks, this process can range from tens of minutes to days (!!).

Were the files and classes names appropriate and what you expected, were they easy to reach, or did you struggle to remember what their names were? It doesn’t take long to rename a file and possibly the contained classes, with a decent tool.

Were the interfaces easy to understand and follow? Were the functions minimal and in charge of only one task? Incremental changes tend to make a mess; it doesn’t take long to rename a function, split it into (more) atomic tasks, and refactor common pieces of code to eliminate duplication. Easier to test, easier to read, and to follow! Oh, and please eliminate those long unused class members, it smells of bit rot in here.

Was the code self-commenting, was the spelling correct? Rename the methods and variables to make it so; create auxiliary functions to help readability. Machine time is cheap, human time isn’t, so use that compiler optimization and make it easy for you and your fellows to read. And if someone wrote “local” instead of “locale”, fix it! Grammar and spelling count, especially if you have non-native speakers on the team.

Are there hard-coded values? Extract them, parametrize. Maybe even make that an exposed variable and save yourself the pain of having to change the code when the designer itself can do it. Designers love the ability to experiment with game parameters, and it’s a great way to aid the creative process – more on this in another article!

Were the comments relevant, helpful and up to date? You’re in a unique position to know if they were, because you just used them. Fix them if need be, integrate the parts where you had to spend some effort understanding the inner workings. Consider rewriting the code to be self-commenting (and test accordingly if you do), or at least fix the names!

Are the original assumptions still valid? It made plenty of sense to use bubble sorting when the specs said there would be never more than 20 elements, but now you’re using many a thousand per frame. Maybe a refactoring is inappropriate at this time, but you can make a note to someone to double check and profile.

Is the code readable and visually coherent? Whatever the writing style of choice, it always should be followed for optimal reading results. Put spaces and indenting in the code you’re reading as you read it, and next time it’ll be already nice and tidy.

Are there any warnings in the code you’re touching? Address them before moving forward. Warnings are there to inform you there’s something fishy going on and when you have a thousand warnings nobody’s going to notice one more… until it bites as a bug and robs you of a day’s worth of work to track it down. And it does.

If you’ve been tracking a bug, have you made your test cases and assertions better, so that next time you won’t have to wade through the jungle to find the problem? Have you gone and fixed the root of the problem, or just threw a bug-festering bandage in way after the problem is generated? There’s always a “why” for a bug, and working around it “where” it shows itself isn’t going to fix it, not in the long term, especially not if there’s multithreading involved.

“But I don’t have time to fix the world”, I hear you scream. Oh dear, that sounds awful. Luckily, there is a way out.

A penny invested is a dollar saved

“The only valid measurement of code quality: WTFs/minute”

– Thom Holwerda

Say you’ve spent an hour understanding the context of your original task (an hour!). If you just stick to the job, anyone coming to the code after you (or yourself, after a few weeks) will have to spend pretty much the same amount of time, usually worse, to be able to do anything with it. That includes new features, tweaks, and most important, bugs (tons of them, the hordes!).

By making the code more readable, you’re investing in the future of the project. You’re making code changes easier, less risky. You’re making the general mood better, as you and your colleagues won’t have to curse and swear to understand what’s happening. You’re learning about writing good code bit by bit, without special courses or classes. You’re also teaching the juniors a new way of going forward, of caring about the project, of writing readable code. You’re taking good care of the project, and this does not go unnoticed.

(This clearly does not apply to everything. Throwaway code and quick scripts must not apply. Tools, sometimes. Game code, often. Be sensible, be incremental.)

The magic moment for me was when the team I was part of realized that, by cleaning as we went, we were actually ending up ahead of milestones with no major bugs, and a reusable code base; I’ve surprised myself wondering if I had understood the meaning of “(just) works” in the first place.

I wish the same to you.

Today, I would like to introduce the Xtext framework to you. Xtext is an open source framework which allows you to define your own textual programming languages before you know it. Xtext was not developed specifically with game developers as a target group in mind. It is rather independent in terms of its application context, and I’m convinced that every tool department that ever needed to define their own programming language can immensely benefit from Xtext. So, although there already exists convenient forums, and so forth, I would like to provide an article that uses a small, game-related example to introduce the technology.

Xtext ships as a plugin for the eclipse IDE. Hence, we will need to cover some basics of eclipse, too. I tried to do this in a pragmatic way and within a reasonable scope.

So, what exactly is Xtext?

Eclipse Public License. It comes with some powerful language design tools, which provide you with

• an easy way to design new programming languages, be it large general purpose or little domain-specific languages,
• powerful default configuration to automatically build rich tooling for your new language
• a highly modular architecture and API which enable you to customize and enhance almost every aspect of your language and its tools
• an open and active community.

Our goal

The hardest part of writing such an article is to construct a decent example. So I didn’t. Instead, I use a script format example suggested by Steve Ince in his book Writing for Video Games (thanks Steve!). We iterated a bit over the language design to come up with a more concise version, but anyway, the screencast shows the language and the editor we want to create throughout this article.

Let’s not put the specific language design to discussion here. Instead, we will learn how to build such a language + rich editor using Xtext, such that you are able to create your own language as you desire.

The cool thing is: In order to get this language plus the tooling I show in the video, all we have to do are these steps:

• Create a new Xtext project
• Define the grammar of our language in the grammar definition file
• Trigger Xtext to generate everything for us

Getting started

Xtext ships as an Eclipse plugin. Hence, you can

• either add it to your existing Eclipse application using the update mechanism of Eclipse,
• or, if you don’t already use Eclipse, download a complete distribution of it, containing Xtext and all the necessary dependencies, at once

You can find the download as well as a short installation guide here. Note that you need to choose an Eclipse version that matches your installed Java Runtime Environment. That means that you can only use 64 bit version of Eclipse if you are running a 64 bit JRE on your system. Let me know in the comments section if you encounter problems running Xtext.

In this tutorial, I work with the Eclipse Kepler release and Xtext version 2.4.2. The file I downloaded from the linked site is “eclipse-dsl-kepler-R-win32.zip”.

Download the example

Refer to download the Xtext projects (sources+runtime project) that are shown in this article.

Intended benefits

What are the benefits creating such a modeling language in the first place? First, the language features domain abstractions that allow users to express information in a natural way. In combination with the rich tooling, users are strongly supported in creating syntactically and semantically correct contents. In our case, it supports game writers to stick with the dialog format and create dialog scripts using a simple language.

Since the language conforms to an underlying model, every dialog script automatically has an object graph we can access programmatically. This means that we can create generators that translate dialog scripts into other formats, like

• XML, C++ or C#, to feed the scripts into a dialog engine,
• Excel and screenplay formats for localization purposes,
• or statistical reports, e.g. how many lines each character has.

Alternatively, we could create an interpreter, a program that is able to execute a dialog script directly, by working on the object graph of a script. A use case for this would be to allow writers to play through their dialogs already during creation.

Moreover, the language comes with syntactic validation, so that writers know if there dialogs are syntactically correct. But since we also have the underlying data model, we can additionally provide semantic validation. This turns the language into a powerful tool, as we will cover in an upcoming article.

Put another way, it makes dialog scripts in their meaning equal to source code, since they provide detailed and concise information, while they still can be written by non-programmers, thanks to the used abstractions and limited scope of a DSL. In combination with the tooling that comes with an Xtext language, the users—in our case game writers—are supported in many ways to efficiently create their content.

But before I start to talk about shortened turnaround times, let’s move on with the article and discover the benefits step by step.

Setting up an Xtext project

Note that I work on a PC, but if you’re on a Unix-based system, you should be able to follow the described steps accordingly.

Start your Eclipse application by launching the eclipse.exe/*.app. By default, Eclipse asks you for a workspace location. The workspace is the root directory where this instance of Eclipse will store your projects, as well as the related metadata Eclipse requires. Check the box at the bottom if you want to set this workspace as your default.

Eclipse starts with showing us a “Welcome page”, which we can just ignore. Instead, select File –> New –> Project from the main menu. This leads us to a wizard selection dialog. Type Xtext in the filter field at the top. As you will see in the filtered list of available project types, Xtext already ships with many example projects, which you might want to explore later for yourself. For now, select Xtext Project and press Next >.

We are directed to the New Xtext Project wizard which already features some defaults. Let’s go through the fields step-by-step.

• Project name: Xtext projects need to feature a project name that starts with a lower case letter since it will derive Java packages from that name. Let’s call our project adbad.dialogScript.sample.
• Use default location: Let it checked so that the project will be stored in our workspace
• Language –> Name: reuse the project name and append a valid Java identifier as your language name, e.g. adbad.dialogScript.sample.DialogScriptDSL
• Language –> Extensions: Here we can define several file extensions. For now, one is sufficient. Let’s use dialog.
• Layout –> Create SDK Feature Project: Uncheck that. It wouldn’t do any harm to have it created, but we don’t need it for this article
• Working sets –> Add project to working sets: We can group projects in Eclipse into so called working sets. We don’t need to do that.

This is how it should look like if you want to follow the suggestions:

Hit Finish and Xtext starts working. We will be redirected to Eclipse. If you haven’t closed the welcome page yet, do it now. Xtext has created three projects for us:

1. adbad.dialogScript.sample: The actual language project. All sources regarding the language itself belong here. Note that this runtime project is independent from the user interface and Eclipse. That means we can use our language definition outside of Eclipse.
2. adbad.dialogScript.sample.tests: A convenient project for testing our language (we won’t cover testing in this article, hence we won’t have to look at this project any further)
3. adbad.dialogScript.sample.ui: All sources related to the user interface of our language, like the rich editor, its features like content assist, highlighting, etc., and the outline view, will be stored here. The ui project is a so called Eclipse plugin, meaning that it depends on Eclipse as a platform.

All code we are going to create should be stored within the src folders, which are available in every project. The folders src-gen resp. xtend-gen are to separate all generated code from the manually written one. Xtext takes care of that, so it’s just important to not place any manually written code in one of these folders.

Exploring the project in the package explorer shows us that there already exist some files in our language project:

• DialogScriptDSL.xtext: This file is already opened in the editor area. It’s our central resource to define our language’s grammar. It features a grammar definition language, which has been created—you guessed it—with Xtext itself. The language resembles EBNF and it allows us to define context free grammars.
• GenerateDialogScriptDSL.mwe2: This file is to configure Xtext, i.e. to tell Xtext what features we want to use in our language and what the framework should generate for our language. We can stick with the default settings for now.

The Grammar Definition File (DialogScriptDSL.xtext)

Let’s see what we have so far in our grammar file to get a first idea of how to define grammars in Xtext.

HINT – Showing line numbers in Eclipse editors: In order to see line numbers in your editors

• Select Window –> Preferences from the main menu
• Type text editors in the filter field at the top left corner of the new window
• Select the item Text Editors (highlighted) from below the filter field to open its configuration page
• Check the box show line numbers (fourth from above) there and press OK

The grammar definition file starts with the “grammar” keyword, followed by the language name we defined earlier in the New Xtext Project wizard. Grammars can make use of other grammars. With the statement in line 2, we tell Xtext to use the org.eclipse.xtext.common.Terminals grammar, which comes with Xtext. It provides us with some handy language features, like:

• Single– and multi-line comments you might know from programming languages like Java or C#. They allow users to annotate programs with additional, free text information that is ignored by the parser.
• An ID rule that allows us to define identifiers in our language. Identifiers have a specific semantic in programming languages, and so they have in Xtext. Things like classes, variables, and methods, or in our case characters and conditions can be named using identifiers. This makes them identifiable and thus referable from other locations.
• INT and STRING rules to use integers and strings in our language. Both rules also feature some specific semantics, as they are mapped to specific data types in our underlying meta model… wait, meta-what?

Okay, I mentioned earlier that our language needs to comply with an underlying model. In my experience, the whole model / meta-model / meta-meta-model terminology tends to be more confusing than helpful. Still, I want you to understand what’s going on in the grammar file, and I’m referring to line 4 now. So let’s try this.

Whenever we define a textual modeling language with Xtext, we define its so called concrete syntax, i.e. how the editor displays programs written in our language to us, the users. In order to work with our language programmatically, we also need an object graph that represents our language (an abstract syntax tree, AST). The parser creates this representation for us when it parses a dialog script file. The abstract syntax of our language determines how such trees can look like. But where does the abstract syntax, the structure of our language, come from? Xtext offers us two possibilities:

• Either, we can define a concrete syntax for an existing abstract syntax by importing an abstract syntax model
• or, we let Xtext derive the abstract syntax from our grammar definition file automatically.

The latter is done by the statement in line 4. We need to provide a name (dialogScriptDSL) for the abstract syntax model as well as a namespace URI (“http://www.dialogScript.adbad/sample/DialogScriptDSL”) that makes it referable.

The remaining part of the file is to define the actual grammar of our language. Lines 6-10 show two grammar rules that already define a simple language. Now, instead of diving into the details of defining context-free grammars with Xtext, let’s approach it pragmatically:

Defining a language can be seen as a top-down process, where you divide your language step-by-step into its components until you have defined all its tokens. The rules in the grammar language allow us to do exactly that.

Again, we are not able to discuss the grammar file for the used example in detail in this article (instead, I made a screencast), but the important part is to understand that this file is the central resource where we define our language’s concrete syntax.

You can copy the rules from the provided grammar file to your own grammar file. I inserted some comments that help you understand the grammar.

Creating the language infrastructure and editor

In order to use our language, we need to make Xtext generate the infrastructure for it. We can do this by opening the context menu somewhere in the Xtext grammar editor and selecting Run As –> Generate Xtext Artifacts. This invokes the GenerateDialogScriptDSL.mwe2 workflow and generates the infrastructure for our language according to the information provided in the workflow file. This might take some seconds, and you might be asked in the Console View at the bottom to download the ANTRL 3 parser generator, which is necessary, so enter ‘y’ in order to proceed.

Running the editor

After that, we can launch a new Eclipse instance from within our current environment. That instance will contain our language, plus the editor as an Eclipse plugin, so we can try it out immediately. We need to select the run configuration first (we need to do this only once). To do so, select Run Configuration … from the Run toolbar menu (click the small black arrow pointing down):

The Run Configurations dialog appears. There, you can see an Eclipse Application entry on the top left side to create a new configuration. Grouped below, we find the configuration we want to start. It is called Launch Eclipse Runtime. Select it and hit the Run button at the bottom. (Note that I renamed it to DialogScriptRunner):

This starts a new Eclipse instance just from within our development environment. Note that, from now on, you can always directly select the DialogScriptRunner configuration to directly start Eclipse!

In order to test the language and the editor, create a new project, e.g. by pressing CTRL+N and then selecting the wizard of your choice (I often use the General Project Wizard without any bells and whistles).

Give the project a name, like sample, and feel free to add sub-folders using the project’s context menu in the Package Explorer. You can now add a new dialog script, again using the project’s context menu:

It is important to explicitly state the file extension of our language when naming the dialog script file. Since we defined dialog as our file extension back when we have created the Xtext project, we might just name our first file sample.dialog. Now, you should be asked whether or not we want to add the Xtext nature to your project, and since we want to have the full Xtext support in our sample project, we sure do.

The editor that Xtext has created for us is used by default now whenever we open *.dialog files, and we can already test our language and editor. Actually, the language already features everything we saw in the first screen cast. It is always great to see how many tooling features are provided by default. You can try out the features that I show in the first screencast now for yourself.

Note that we just edited the grammar file so far, and we receive a fully-fledged editor in combination with our language.

Summing up

Game developers use a multitude of development tools for all kinds of purposes. Due to the individual requirements, it is rare that the same ecosystem of tools is used twice. Instead, developers often are in need of introduce new tools to address the specialties a game project and in most cases there is little to none budget for that. Especially when it comes to non-technical domains, like game design or writing, makeshift solutions like screenwriting or office software are often the status quo to describe how a game should ‘work’.

Technologies like Xtext support tool smiths in creating their own programming languages with a corresponding development environment. We explored a very basic example that shows—just by defining a single language grammar file—how Xtext provides us with a complete language runtime as well as a rich editor. The additionally provided application gives you an impression of how the development environment can be enhanced, and I’m looking forward to provide you with some subsequent articles on how to do that.