It hurts right around here...

I had mentioned in my first post that I wanted to focus a lot of the content on this site towards two software projects I’m working on in my spare time. One of them is a PC game demo I’m writing with some friends.

When we started the project, everyone was dead set on creating the demo as a Halflife 2 mod using the Source Engine SDK (we’re all loyal Valve fanboys). We spent about three weeks heading that direction and finally gave up. We’re currently in the process of starting over (possibly using XNA).

A lot of the reasons we decided to dump the Source SDK are summed up in this thread on the hlcoders mailing list. It’s getting a bit long though (and has strayed off topic more than once). So after spending some quality time with the SDK, here are my primary gripes:

1. API Docs – This is probably my single biggest complaint. The Source SDK is a huge and complex chunk of code. Without API docs, new developers are basically forced to read the header files (which are sparsely commented at best) and waste a lot time on trial, error, and guess work. I know that commenting and documenting source is royal pain and a bane of all hackers (even the good ones), but it’s still vital. This is especially true for something being released to the public. Doxygen has been around a long time, and is used in at least a few open source rendering and game engines. Given Valves resources, I don’t see a reason for this.
2. The Source SDK Wiki – This was a great idea that I think has just been poorly executed. Valve started this wiki around the summer of `05 as a central source of documentation for the modding community. The content is poorly organized, most if it isn’t written very well, and a lot of it is simply outdated. It seems as if Valve just installed MediaWiki on a server somewhere and said “Here…enjoy.” I’m all for community edited documentation and version control, but I think Valve has to set standards…and the community needs to keep to them. Installation instructions and beginner tutorials should probably be written by or at least approved by Valve developers. This would help keep the learning curve from getting too steep and provide a reference for people that want to write more advanced content.
3. Source Code – The first steps to creating a new Source mod are very straight forward. You open up Steam, launch the Source SDK tool, tell it to create a new mod, and you’re off. The code that it dumps in the project directory is a bit of a mess though. When you open the generated Visual Studio (VS) solution, two projects are presented: one that builds a client DLL and another that builds a server DLL. The base source code directory for the client project contains no less than 315 files. The sub directories contain even more and they’re not organized in any seemingly logical fashion. In addition, the project doesn’t build clean (read: without warnings) right after you create a new mod. Some of the warnings I fixed by tweaking some header code, others could have been suppressed in the project settings. Finally, as of this post, the VS solution generated by the mod tool is a VS 2005 solution. Converting it to a VS 2008 solution creates more problems that need to be fixed. Overall, the base source code seems sloppy and poorly organized.
4. Design Documentation – Another problem with the complexity of the Source Engine is that new developers can easily get overwhelmed. I got frustrated and confused many times because I just wasn’t sure how the pieces fit together. Often times the in-game dev console would spit up errors and I’d have no idea why, where they were coming from, or how to fix them. A good design doc would go a long way to alleviate some of this. Something that described at a higher level how the different parts of the engine and SDK talked to each other and where to find the code for each piece. This could also be helpful as a road map to the API docs as well.

I know a lot of this is just ranting (and I’m not the best coder in the world by any stretch). But overall, I was really disappointed with the Source SDK. As a gamer, I’ve bought everything Valve has ever released. A few of their games are in my top ten as well. I think they listen to their customers and genuinely try to improve products after their initial release (Left 4 Dead and Team Fortress 2 are great examples). I was excited to try my hand at Source development after reading about the origins of Portal, CounterStrike, and Left 4 Dead as mods. But as a developer, I feel like a lot of the work on the SDK was shoddy. I know others have similar grievances, and I hope Valve addresses some of them in the future.