Wednesday, 24 July 2013

The Importance of Documentation (Blog Update 25/07/2013)

Hello ladies, gentlemen and gamers and welcome to another blog update, brought to you by Sonic Punch Studios and Bubble Virtuoso!

How are you guys? Fantastic. Me? Well, let's just say I got off a slow start with my "Take 2" plan - one of the reasons of which I will be explaining next as per the title of this blog update.

Documentation, documentation, documentation...

One of my very bad habits of game development that I finally noticed (dear me...!) is that I very rarely do documentation on my code. Being that I'm using PlayMaker (a plugin for Unity, just in case if people didn't know) as means of developing Bubble Virtuoso, in virtue of how its coding works, I thought I would easily catch on what each action does when I look at the code again after a period of time.

... Again, I was proven wrong.

I was about to modify one of the features in the code for the free version of Bubble Virtuoso when I faced this:

Makes you want to fall asleep right? What we're looking at here is an example of what happens if you don't do documentation. If one would take a glance at this, they wouldn't be able to immediately make heads or tails of what each action does without clicking through all of  the object names to highlight dependent in-scene game objects - which was exactly what I've been doing; and that certainly took a while.

The problem wasn't as bad as made out to be, but it does become problematic if I were to be giving dependent game objects weird, incomprehensible, ambiguous, or overly long names (especially with the limited display spaces where the object names go).

However, there is one neat little thing that I've finally utilized (I've actually discovered it a long time ago but never thought about using it) that can counteract the above problem, as shown next:

One of the things that I encourage all upcoming Playmaker users to do is to make use of the ability to change the selected action's name into a custom one. One might ask, "Why would I want to do that?" (I sure did think like that before) Well the answer lies back to the problem about poorly named game objects or in the following case study, missing game objects.

See how I've changed the action names to have a short descriptor of what the action does? It might sound like a lot of micro managing but I can assure you that it will save a lot of time down the track when it comes to being reminded of what that particular action actually do.

As you might have noticed in the image to the right, I used two variations of descriptors: generic descriptors and descriptors that addresses actual game object names (the text in square brackets). The descriptors with the actual game object names are only used when I need to be reminded of the game object to be linked back to the action when re-inserting it back into the scene after removing it in the first place.

Of course, you don't have to rename actions like I do, so rename them in a way that you would understand.

There is also one other thing that I've found that might prove useful - using empty actions to denote the function of a group of actions as shown below (highlighted in blue):

As you can see here, I am using empty actions to mark the beginning and end of a group of actions that performs a particular function (in this case - the function of hiding the exit confirmation screen). As a precaution, I've also unchecked those empty actions (thus disabling them) so that they won't be read during runtime. It might seem trivial in this example, but it becomes a godsend when documenting a long sequence of actions and/or calculations used for a particular purpose (for example, calculating the amount of hit points a character has based on external variables) - using empty actions to point out those purposes can potentially save a lot of headaches when revisiting the actions at a later time.

Of course, another way to easily deal with this is to stick those series of actions into another state and then adding a descriptor to that state, but even then - depending on the purpose of the state and the amount of sub-functions in that state - I might end up having to use empty-action documentation anyway. Because I usually like to keep my FSMs uncluttered as possible (thus each state I create has the tendency to contain a lot of actions), it created the need for me to use this kind of documentation.


Hopefully you have found the above tips useful. I certainly did, and I might need to dive further into my code/FSMs to continue creating documentation (only on those I plan to change at the very least considering the amount of time I have left). To all the other PlayMaker users out there, what is your preferred method of documentation?

That's all from me for now! Phew, it's becoming hard for me to come up with topics for the blog updates, so you might find that my updates have been sporadic as of late (hence why I missed out on last week's blog update due to having nothing notable to talk about). But! Do not assume that Sonic Punch Studio is dead as I am hard at work to finish up all development and promotional stuff in time to meet my own deadline!

Adios Amigos! I'll see you guys next time!

No comments:

Post a Comment

Related Posts Plugin for WordPress, Blogger...