Welcome to the second part of our first Let’s build a game! series. If you’re not a fan of project organization and management, you might want to skip this part, provided you’re reading it after I’ve posted the third part of the series and you actually have something to skip to. If you’re a fan of project organization and management, read on. If you’re unsure whether you’re a fan of P.O & M. (it’s painful to write that down every time) or not, give the wall of text below a try. You might become a fan after all.
The Developer’s Handbook
In this part we’re going to take a look at the developer’s handbook concept. What I call a developer’s handbook is a document that describes the outline of its parent project. It’s short (when compared to the whole project), to the point, and it helps a bunch. If you ever stop working on your project for a while, it can help you remember the most important things you might have forgotten. Also, if you need to focus completely on particular features, the handbook can act like a to-do list. In case you need to start a quest for assets, the handbook can tell you what to search for at all times. And, of course, if another developer joins your team, you can share the handbook with them so they know exactly what’s going on.
The handbook is not a single-write document. During development you may find that certain features you’ve thought would be amazing are actually not fun at all. Thus, you may wipe them from the handbook. At other times, you may think of completely new features, that are more fun. Those should be added to the handbook too. Just make sure the people who are working with you have access to the latest version of the handbook at all times.
There is also no unique recipe for a handbook. Its structure, size, pretty much everything, can vary from project to project. However, there are three sections that, I believe, could be successfully integrated in a handbook regardless of the project it’s being written for. These three sections are:
- A short summary of the project. What it is about, a list of any other similar projects to be looked at as reference and so on.
- A comprehensive list of high level features. In case you have a hard time splitting your project in distinct high level features because you can’t tell what a high level feature actually is (I made this term up, but I believe it makes sense), just concentrate on what the end user should be able to see, hear, and interact with. A visual interface is a feature. In a FPS, guns form one big feature that can be split in smaller features (guns equals M4A1 + Railgun + RPG + Glock + Machinegun and so on). Online multiplayer is a feature for a game that… features (see it now?) such a thing. Time manipulation, as in Braid, the indie platformer, is a (pretty awesome) feature too.
- Any important or extra details on the features listed above. Perhaps that time manipulation feature is a bit more interesting than what can be found out there already? Sine Mora, the (just as indie) 2D side scrolling shooter shows a nice take on the time manipulation concept, for example. Write info on all of those particularities here.
Writing tip! Even if you’re working solo on your project, while writing the handbook, imagine there’s a team of developers waiting for the document so they can start developing the actual game. You’re not in the mood to answer a massive amount of questions, and don’t have the time either. Write the handbook in such a way that said developers would not need to ask too many questions. Keep it clear and cover as many details as possible.
Keep in mind the following: the whole concept of developer’s handbook is something I’ve adopted for usage inside of Vanilla and has proven to be a nice way to organize all in-house projects so far, but this is obviously my case, and the only case that I know of. It is by no means a standard in the industry. It is by no means a perfect way to organize a project, and is by no means something that you should follow blindly. Give the whole thing a try, and see for yourself how things turn out. If the handbook does the job for you, then congratulations are in order! I’d love to hear more about your exploits in the comments section.
To end the general talk, I’ll say that the whole handbook concept is pretty rough around the edges at the moment. In case you have suggestions for its improvement, the comments section is the place to write ‘em down.
Our Game’s Handbook
Our side-scrolling shooter’s handbook could do with the three sections above only, but I’ve added an extra section for a really nice diagram that somehow mirrors the whole handbook.
First of all, the tools I’ve used for this particular handbook:
- For the writing part, I used LibreOffice Writer. It’s very well suited for any task I might happen to have to throw at it. It’s completely cross-platform, and as if that wasn’t enough, it’s also completely free. You can find it here.
- For my favorite part, the diagram, I used yEd. It’s a great, free & cross-platform solution for drawing diagrams of any kind. Diagrams are neat. You can represent pretty much everything on a diagram and, with a bit of luck, it will make tons of sense. You can find yEd here.
But wait! We’re forgetting something. The name of the game! How can we build a game without giving it a name? Let’s call it… Pew-Pew!
Pretty catchy if you ask me. Feel free to call it differently though, if you do not like Pew-Pew!
Here’s the actual handbook I wrote, in pdf format. Check it out to better understand what Pew-Pew! is going to be: link.
In case you are interested in the source document and diagram, there’s a Microsoft Office-friendly doc right here. The graphml file for the diagram can be found here. I will also add the diagram to the article, so that it does not look like a boring wall of text. You think boring walls of text are bad too, right?
This diagram alone tells us what we need to keep our eyes on during development!
What’s next?
In the next part of the series we will (obviously) continue with the development of our side-scrolling shooter. We’ll gather and organize some assets by following the diagram above. We will also (finally!) write some code. Quite a lot of code, actually.
See you next time!
