It is dangerous out here, I wish I had a map

It's good to plan things ahead.  Designing games or any other system is, for me, a sort of planning. And designing takes a lot of time. You want to start building a system that will not have to be changed or remade after a little while but can instead be adapted easily. It needs to be smart and cover all the functions that you want from it and it needs to be easily extendable. This requires an overview of the project as a whole - you need to know everything that the system will need to do in order to plan a coherent system.

...there will be lots of it!

You need to know what a house needs to be able to "do" in order to be able to draw schematics and blueprints where all the walls, doors, windows, electrical lines, water pipes, roof, stairs, kitchen, toilets are all simply working. You can't just start building something with half the knowledge of what the house should look like and contain - that would be crazy. Suddenly you might realize that you forgot to put in a bathroom, or space to have stairs when you're supposed to build the second floor. It would be a bit absurd.

Say you build a house and after building the first floor your boss suddenly tells you to put one extra window in every room on the first floor. It's not only to cut holes in the walls and place windows there, the windows should probably be placed where they give the most light to the room, the best view, allow for good furniture placement - all the while keeping in mind where electrical wiring and pipes are. Maybe you even have to rewire some electricity in order to put some of these windows in, which might need a re-planning of those systems in the house as a whole.

It's kind of the same with software production. One project that I'm working on at the moment involves teaching Japanese Kanji through an e-learning application. The idea is rather simple. You log into the application and are presented with a bunch of lessons that teach Kanji. You can then take small challenges (minigames) in order to prove how much you've learned. Then, the application keeps track of your progress and unlocks further lessons and minigames, and so forth. Sounds simple, but that explanation is like saying "we want a red two floor house with 5 rooms, a bathroom and a kitchen, a balcony and a gravel pathway to the black front door". It says nothing of how to actually structure everything, how things should interact and work together to form this intended result. That is where architects come in and make sure everything is planned before construction starts.

When it comes to software and games it seems like this planning stage, the drawing of the blueprints, is often overlooked. Inexperienced people tend to want to go from the above description of the result and then say "hey, what I want is really quite simple, so just start making it and if you start now shouldn't you be done with the first floor by the end of the week?". No... no, I won't. Not unless I've done this exact same thing before and/or simply just have a huge repository of already-made parts for me to just puzzle together - and even then it needs planning because I won't know what parts I need until I've figured out the underlying system as a whole anyway and that takes time!


Of course, there can actually be too much planning as well in some circumstances. An old article at BoingBoing explains it beautifully. In short, sometimes one should just go for it, and not plan and mentally test every single part of the project before construction starts. In some cases it's good with a portion of randomness and exploration in order to, for example, find some new game play concept. This sort of requires that there is no really concrete destination in the first place so it's slightly off-topic when it comes to my rant.

The project I'm working on now is sort of like a nightmare in that aspect. It is an interesting project, but the longer I work with it, the more work is required by every little change or addition to the end result. While it's probably possible, it has become extremely difficult to keep everything "in my head". When I code I comment like an angel, and I'm not kidding. I almost always comment my code as if someone else is supposed to read it even though I know they won't. Regardless, after a while the project becomes so huge that it's impossible to remember how everything works because if you try to follow the workings of the code you get lost sooner or later when the code forks into lots of functions and loops and other classes - not to mention files in entirely different editors (AI, XML, AS, FLA, PNG, etc).

...I need some.

An example of how the frak the application I'm working on works; the Kanji application has a Main class that keeps track of showing and removing sections of the application as the user navigates between them. This could be from showing the splash screen, login screen, grade and progress overview, minigame overview, lessons front page, lesson slides, minigames themselves, and probably some other things that I've forgotten right now. There is also a parallel class named Database which takes care of loading all the information about hundreds of kanji and radicals from a bunch of XML files, and offers functions for the rest of the application to fetch important information about kanji or radicals. Such as image URL for kanji, what radicals a kanji uses, what their image URLs are, what their public name is, what lessons are referred to in a grade, what kanji is referred to in a lesson, and so forth. Not to mention, the Database sends information to the lesson section of the application.

The lesson part takes care of showing lessons, which is a package of a few kanji and their lesson slides. Each slide is defined in XML and tells where and when to show video, still graphics, text and when to play sounds. It can also define buttons and make every other item clickable as well. Video and sound can trigger the application to move to another slide when they're done playing, and some of the slides are hidden to the user until automatically navigated to, and so forth. This is a system that admittedly still contains a few bugs (namely in the preloader part, which is actually a whole different part of the application...), and is one of the most complex systems in the application. Of course, from the eyes of the user, this is simple. The sucky part is when an employer sees it in the same way. Then again, it is understandable if you've not worked with programming before (or Flash and ActionScript 3 which... no I won't even go there right now). It doesn't make it any less of a problem though.

Now I could go on to explain in detail how the asset loader works, how the rather huge file archive is organized, how the XML format is structured to be easily readable and modifiable by people with little computer experience, how the Database works to tie different heaps of information together (grades, lessons, kanji, radicals) while not completely crashing every time there's a slight error, and how the player progress class works with the Database and challenges to find out what kanji to send to the challenges and what progress data to update when a challenge is completed without forming a weave of spaghetti (instead of a spider-web of connections between the classes they send clean and and as stand-alone data they can), etc. But that feels hardly like an interesting read, even though it would be rather therapeutic to write about... ah well.

The biggest problem with this project is that the planning and construction of the software needed to be done at the exact same time in order to have a chance to keep up with deadlines and milestones, while at the same time updating and changing the vision of the end product. This is like starting to build a house before having all the blueprints of the parts you are building, while at the same time getting new updated blueprints of things you've already built. Every time some new addition or change is made, you need to go back and make a new plan of how to change/adapt both the existing plan, what you've already built and the new change so that they work as a whole.

This means that the more the application grows and the more complex the system becomes, every change and/or addition to the intended result requires more and more work to incorporate - even when the change might seem small. Add a light switch to the other side of the room as well? Sounds simple, but naturally requires you to put electrical wiring in the walls to that place, etc. The more actual construction you've made, the longer it will take to change it. You can relatively quickly change a blueprint (but as I said, even that might take some time and work).

...sadly has nothing to do with this.

At this point, the system is huge. I slammed headfirst into a concrete wall the other week as I started building another fairly simple minigame for the project which was in my mind just a slight alteration of one minigame that I've already made. A form of quiz. The first minigame showed kanji images and had the user type the correct translation. The second would simply show the kanji's radicals (parts) instead. Somewhere when I planned how the lessons worked and how information was stored about kanji and radicals I had taken a slightly wrong step. The Database (the part responsible for keeping track of kanji and radicals and their relations) can happily regurgitate what radicals a kanji contains, and even with some simple cross-reference searches through the databases find what kanji a radical is used in (as many radicals are part of many different kanji), and what humorous illustration to show to explain the meaning of a radical. But - the database has no idea what a radical actually looks like! This was a gap in the planning of the XML structure way back, when I decided that it was impossible to store any one image for a single radical in the radical XML definitions because of the fact that one radical could look slightly different in different kanji. So instead, I let the kanji contain all of its individual radicals. This worked perfect when manually defining all the lesson slides, but now when I need to ask the Database what image is which radical... it has no idea. It can make guesses that would probably be correct most of the times, but that's hardly good.

So, what do I have to do in this case? The easiest way proved to be to go through 20-30 XML files, find out what image frame is used for which radical in every kanji, and make new sections with XML keys (or tags or whatever you call it) in each kanji, defining in an easily fetchable way what I need to know.

Again, might sound simple, but not only did it take a while to get to that conclusion, I've noticed some cases where I know this won't work. Some kanji seem to use radicals that aren't defined in the radicals XML files, and I have no idea why that is since I wasn't the one writing most of these files (we actually hired someone to do this for us a while back so that I could concentrate on coding).

Fuck.

I would love a map right now. It seems that if Flash doesn't give me little random gifts of unimaginable inconsistent stupidity, then the system I've made so far just confuses the fudge out of me. It's big. At least for one person with no previous experience of making anything remotely similar. And when I work with one part of the system for a long time, I start forgetting exactly how the other parts work. This is fine, as long as they do what they should, but then you realize - such as in my latest problem with the radicals - that you need to dive into these parts again to make changes... without messing anything that works up.