I spent this weekend modifying the Model-View-Controller design pattern of the game engine. Up to this point, I had implemented a simple hack to bypass the Model part of the MVC and allow the Controller to communicate directly with game characters.

However, such implementation was wrong, and it was time to fix it. So, I connected the model to the controller and disconnected the controller from the characters. From now on, the model would receive controller input messages and send them directly to the characters.

However, when I did this, I realized that the Model didn't have a proper way to communicate with the character. My first instinct was to implement a "changeState()" function.

From a game perspective, this makes sense. When you are playing a game, and you press a button, it typically means you want to change the state of a character. For example, from a walking state to a running state.

The problem was deciding the argument type for the changeState() function.

At first, I decided to make the argument type a string. It worked but soon realized that it could lead to user errors. For example, typing the wrong state such as "walking" vs. "Walking."

Listing 1. changeState with String type argument

void changeState(string uState);

You should always strive to make APIs simple to use but hard to break. And the changeState() function required a uniform way to receive data.

So I decided to implement a new argument type for changeState(). I opted for using an enum type which looked like this:

Listing 2. Character State Enum

typedef enum{
    //walking state
    kWalking,
    //running state
    kRunning,
    //jumping state
    kJumping

}CharacterState;

Listing 3. changeState with Enum type argument

void changeState(CharacterState uState);

The enum would prevent user errors by forcing them to use the enum members.

However, this meant developers would need access to this enum definition. For example when they want to add more character's states. When you are developing an API, you want to prevent users from modifying the API.

So I needed a way to prevent user errors and decouple the changeState argument from the engine's API.

I needed time to think about this. So, I went to the gym. Did 100 push-ups, 30 pull-ups and while jumping the rope, the idea of using void pointers hit me.

Listing 4. changeState with void pointer type argument

void changeState(void* uState);

By making the changeState() argument a void pointer, the developer can create new data types. He can use an enum or structure to hold the characters states and pass them along the model and character class. Thus preventing user errors and keeping the engine decoupled from the characters' possible states.

I wanted to share this with you because this is one of the seven principles of Object Oriented Programming: Always Strive for loosely coupled designs between objects that interact.

Hope this helps

October 13, 2016

Harold Serrano

Random Stuffs

What do developers need from your APIs?

October 13, 2016

Harold Serrano

Random Stuffs

I've been debating whether to release the game engine as an open source or keep it as a personal project. A game engine is essentially an API that requires user documentation, developer documentation, and tutorials.

It also requires support mediums such as:

Forums
Technical support
Knowledge base
Bug trackers
Mailing lists

As you can see, releasing an open source project does not only mean releasing the source-code. It also involves setting up the right environment that leads to a good user experience.

I do not have experience running an Open Source project. But I do know what developers need from your open source project. What they need is Detailed Documentation. For example, a new user to your open source project would require the following documentation:

How to set up the project
An overview of how the project works
Step by step tutorial to doing common tasks
Hands-on projects
An honest list of the project's limitations. If your project can't do X, then say it. Don't hide it.
Known issues and workarounds, if available
Knowledgebase articles that address common questions

Unfortunately, writing documentation is what developers hate the most, myself included. But it is essential to the success of your project.

In essence, detailed documentation lowers your project's barrier-to-entry. The easier it is for users to start using your project, the less likely they'll lose interest. And the more likely they'll recommend it to others.

Hope this helps

October 12, 2016

Harold Serrano

Random Stuffs

Good-bye Git GUI. Hello Git terminal (well, kind of)

October 12, 2016

Harold Serrano

Random Stuffs

When I started as an indie-developer, performing Git operations through a graphical interface was ideal. However, lately I have realized how much the GUI has held me back.

I'm not saying that using a Git GUI is a bad practice. Not at all. If you are a new developer, your focus should be in learning a new programming language and the proper way to develop an app. You shouldn't spend time learning EVERY Git operation. You have enough on your plate to be learning how to rebase, revert, etc. In this instance using a Git GUI can be helpful.

However, as you grow as a developer, a GUI becomes a roadblock more than a valuable tool. I started noticing this in the last beta version of my game engine. In the back of my head, I knew it was time to start using the terminal. I also knew that my basic Git knowledge was insufficient to further the development of the engine.

This past weekend I decided to spend my free time learning Git commands. I decided to revisit every git command I knew and visualize what it does. I also learned new Git commands. Since I am a visual learner, these tools helped a lot:

To be completely honest, I have been intimidated by the terminal for quite a while. I was afraid that I was going to issue the wrong Git command and completely mess up my game engine. However, that feeling has changed. Now that I can visualize what each command does, the terminal does not scare me anymore. It sounds funny that I say this, but through the terminal, I feel the power in my hands. (Yeah, it does sound weird.)

However, I can't completely say Good-bye to the Git GUI. Unfortunately, the Git terminal is terrible at graphing branch dependencies (see image below) and showing diffs between files. Nonetheless, I see myself executing all Git commands through the terminal, and whenever I need a visual, I will use the Git GUI.

My workflow and the tools I use have changed over time. When I started as a developer, I could not understand why someone would prefer the terminal over the GUI. Years later, I realized that it was advantageous to comprehend Git operations from a terminal perspective. And even though I took the time to learn the basics of Git using the terminal, my preferred choice was the GUI. Today, as the engine has become more involved, I realize that is time to say "Hello" to a tool that intimidated me in the beginning.

My advice to all new developers is this: If you are content using a Git GUI, keep on using it (but do learn the basics). If you are intimidated by the terminal, don't force yourself to use it yet. As your knowledge grows and you develop complex applications, you will realize the shortcomings of a GUI. The best learning occurs when you are curious. And your curiosity to perform various Git operations will remove the intimidation you may have with the terminal.

Hope this helps.

October 11, 2016

Harold Serrano

Random Stuffs

How many books does it take to develop a game engine?

October 11, 2016

Harold Serrano

Random Stuffs

Approximately this many:

No kidding!